--- title: "Handling premium, credit and maturity events for CDX instruments" slug: "handling-premium-and-credit-events-for-cdx-instruments" updated: 2026-08-01T13:54:21Z published: 2026-08-01T13:54:21Z canonical: "support.lusid.com/handling-premium-and-credit-events-for-cdx-instruments" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.lusid.com/llms.txt > Use this file to discover all available pages before exploring further. # 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](/v1/docs/modelling-cds-index-instruments-in-lusid). > **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](/v1/docs/understanding-instrument-lifecycle-events-emitted-by-lusid) 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](/v1/docs/handling-premium-and-credit-events-for-cdx-instruments#handling-premium-payments). - `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](/v1/docs/handling-premium-and-credit-events-for-cdx-instruments#handling-credit-events). - `MaturityEvent`. This event is automatically emitted by LUSID on the maturity date specified in the instrument definition. [More information](/v1/docs/handling-premium-and-credit-events-for-cdx-instruments#handling-instrument-maturity). > **Note**: For an implementation using the Python SDK, see [this Jupyter Notebook](https://github.com/finbourne/finbourne-notebooks/blob/main/V3/features/instrument-events/CDX-CDS-and-instrument-events.ipynb). ## 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](/v1/docs/modelling-cds-index-instruments-in-lusid#mastering-an-instrument). ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-EOC1LTKM.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A27Z&se=2026-11-09T07%3A00%3A27Z&sr=c&sp=r&sig=uJPvKIr6lOA0cVALlvJwAOMvHScfKJnrrG%2BLKag3RX4%3D) ## 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](/v1/docs/what-is-a-transaction-template). > [!WARNING] > **Important**: To handle this event, you must create a `CreditPremiumCashFlow` transaction type in the `default` source. [See our recommendation](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#creditpremiumcashflowevent). With a `CreditPremiumCashFlow` transaction type in place that separates premiums from other cash holdings using a SHK, we can [examine holdings](/v1/docs/how-do-i-generate-a-holdings-report) mid-way through to see the impact of several payments: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-RPQP2MOT.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A27Z&se=2026-11-09T07%3A00%3A27Z&sr=c&sp=r&sig=uJPvKIr6lOA0cVALlvJwAOMvHScfKJnrrG%2BLKag3RX4%3D) We can examine the [output transactions](/v1/docs/input-and-output-transactions) generated by LUSID to fulfil these payments (click to enlarge): ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-DJRP2VUW.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A27Z&se=2026-11-09T07%3A00%3A27Z&sr=c&sp=r&sig=uJPvKIr6lOA0cVALlvJwAOMvHScfKJnrrG%2BLKag3RX4%3D) ## 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](/v1/docs/handling-a-cash-dividend-corporate-action-event#creating-a-corporate-action-source). 2. Create a `ProtectionPayoutCashFlow` transaction type to determine the economic impact of protection payout transactions automatically generated by `ProtectionPayoutCashFlowEvent`. [See our recommendation](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#protectionpayoutcashflowevent). 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](https://www.lusid.com/docs/api#operation/UpsertInstrumentEvents) API and supply the scope and code of a CAS as follows: ```json curl -X POST 'https://.lusid.com/api/api/corporateactionsources/my-CAS-scope/my-CAS-code/instrumentevents' -H 'Content-Type: application/json-patch+json' -H 'Authorization: Bearer ' -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](/v1/docs/what-is-a-lusid-instrument-id-or-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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-F76A2I7N.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A27Z&se=2026-11-09T07%3A00%3A27Z&sr=c&sp=r&sig=uJPvKIr6lOA0cVALlvJwAOMvHScfKJnrrG%2BLKag3RX4%3D) We can examine the output transaction generated by LUSID to fulfil this payout (click to enlarge): ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-U0S9O3Q8.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A27Z&se=2026-11-09T07%3A00%3A27Z&sr=c&sp=r&sig=uJPvKIr6lOA0cVALlvJwAOMvHScfKJnrrG%2BLKag3RX4%3D) ## 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](/v1/docs/what-is-a-transaction-template). > [!WARNING] > **Important**: To handle this event, you must create a `Maturity` transaction type in the `default` source. [See our recommendation](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#maturityevent). 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: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-H1YTTDRK.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A27Z&se=2026-11-09T07%3A00%3A27Z&sr=c&sp=r&sig=uJPvKIr6lOA0cVALlvJwAOMvHScfKJnrrG%2BLKag3RX4%3D) We can examine the output transaction generated by LUSID to reduce the units down to zero (click to enlarge): ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-10DR3GTF.png?sv=2026-02-06&spr=https&st=2026-11-09T06%3A00%3A27Z&se=2026-11-09T07%3A00%3A27Z&sr=c&sp=r&sig=uJPvKIr6lOA0cVALlvJwAOMvHScfKJnrrG%2BLKag3RX4%3D)