Handling premium, credit and maturity events for CDX instruments

You can model a credit default swap index (CDX) contract as an instrument of type CdsIndex in LUSID. See how to do this.

Note: The information in this article also applies to a single name CDS contract mastered as an instrument of type CreditDefaultSwap.

LUSID emits the following instrument lifecycle events for a CdsIndex, which you can handle or trigger as required:

• CreditPremiumCashFlowEvent. This event is automatically emitted by LUSID each time a premium payment is due. More information.

• ProtectionPayoutCashFlowEvent. This event is not automatically emitted by LUSID, but can be manually triggered if you are informed that a credit event has occurred. More information.

• MaturityEvent. This event is automatically emitted by LUSID on the maturity date specified in the instrument definition. More information.

Note: For an implementation using the Python SDK, see this Jupyter Notebook.

Mastering an instrument and establishing a position

Imagine we have a position in a CdsIndex instrument mastered in LUSID with the following characteristics:

• Instrument start date of 20 March 2024 and maturity date of 20 June 2029.

• Premium (coupon) rate of 5%.

• Premium payments twice yearly due on 20 June and 20 December.

• Purchased at an above par price of 102 on 20 September 2024, so cash received on settlement date. Since purchased part way through a coupon period, premium rebate also received.

See how to set this scenario up.

Handling premium payments

LUSID automatically emits CreditPremiumCashFlowEvent each time a premium payment is due. For more information on this event, start by calling the GetTransactionTemplate API to examine its transaction template.

Important: To handle this event, you must create a CreditPremiumCashFlow transaction type in the default source. See our recommendation.

With a CreditPremiumCashFlow transaction type in place that separates premiums from other cash holdings using a SHK, we can examine holdings mid-way through to see the impact of several payments:

We can examine the output transactions generated by LUSID to fulfil these payments (click to enlarge):

Triggering and handling credit events

We can trigger LUSID to emit ProtectionPayoutCashFlowEvent if we are notified that a credit event has occured (note this event is not emitted automatically). To do this:

1. If a portfolio does not already have a corporate action source (CAS), create one and subscribe the portfolio to it. See how to do this.

2. Create a ProtectionPayoutCashFlow transaction type to determine the economic impact of protection payout transactions automatically generated by ProtectionPayoutCashFlowEvent. See our recommendation.

3. Load a CdxCreditEvent into the CAS to trigger ProtectionPayoutCashFlowEvent on a particular date. Note for a CreditDefaultSwap instrument the trigger is a CdsCreditEvent instead. See below.

Loading CdxCreditEvent to trigger ProtectionPayoutCashFlowEvent

We can call the UpsertInstrumentEvents API and supply the scope and code of a CAS as follows:

curl -X POST 'https://<your-domain>.lusid.com/api/api/corporateactionsources/my-CAS-scope/my-CAS-code/instrumentevents'
 -H 'Content-Type: application/json-patch+json'
 -H 'Authorization: Bearer <your-API-access-token>'
 -d '[
  {
    "instrumentEventId": "CdxCreditEvent2025-02-15",
    "instrumentIdentifiers": {"Instrument/default/ClientInternal": "MarkitiTraxxCrossoverSeries415Y"},
    "description": "Credit event 15 Feb 2025",
    "instrumentEvent": {
      "instrumentEventType": "CdxCreditEvent",
      "effectiveDate": "2025-02-15T00:00:00.0000000+00:00",
      "auctionDate": "2025-03-20T00:00:00.0000000+00:00",
      "paymentDate": "2025-03-25T00:00:00.0000000+00:00",
      "recoveryRate": 0.75,
      "constituentWeight": 0.01333,
      "constituentReference": "Intram"
    }
  }
]'

Note the following:

• The instrumentEventId is a free string field that must uniquely identify this corporate action in the corporate action source.

• The instrumentIdentifiers field uses a ClientInternal identifier to resolve to the correct CdsIndex instrument, but you could specify the LUID.

• If you do not yet know the auctionDate it defaults to seven weeks after effectiveDate.

• If you do not yet know the paymentDate then the transaction automatically generated by ProtectionPayoutCashFlowEvent trades and settles the day after auctionDate.

• If you do not yet know the recoveryRate it defaults to 1.

• The constituentWeight must be a number between 0 and 1.

• The constituentReference is a free string field enabling you to record the defaulting constituent.

You can call the UpsertInstrumentEvents API as many more times as you like to update the event as information about the auction date, recovery rate and constituent weight becomes available.

Examining the impact

With a ProtectionPayoutCashFlow transaction type in place that separates payouts from other cash holdings using a SHK, we can examine holdings after the credit event to see the impact:

We can examine the output transaction generated by LUSID to fulfil this payout (click to enlarge):

Handling instrument maturity

LUSID automatically emits MaturityEvent on the maturity date specified in the instrument definition. This is a generic event designed to reduce an instrument position in a portfolio down to zero, so it drops out of holding and valuation reports.

For more information on MaturityEvent, start by calling the GetTransactionTemplate API to examine its transaction template.

Important: To handle this event, you must create a Maturity transaction type in the default source. See our recommendation.

With the recommended Maturity transaction type in place, we can examine holdings on the maturity date to see there is no longer a CdsIndex position in the portfolio:

We can examine the output transaction generated by LUSID to reduce the units down to zero (click to enlarge):