--- title: "Handling instrument events for interest rate swaps" slug: "handling-instrument-events-for-interest-rate-swaps" updated: 2026-06-26T06:25:22Z published: 2026-06-26T06:25:22Z canonical: "support.lusid.com/handling-instrument-events-for-interest-rate-swaps" --- > ## 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 instrument events for interest rate swaps You can model an interest rate swap contract as an instrument of type `InterestRateSwap` in LUSID. [See how to do this](/v1/docs/modelling-interest-rate-swaps-in-lusid). LUSID provides the following [instrument lifecycle events](/v1/docs/understanding-instrument-lifecycle-events-emitted-by-lusid) for an `InterestRateSwap`, which you can handle as required: - `SwapCashFlowEvent`. This event is automatically emitted for each leg on each payment date to exchange cashflows. [More information](/v1/docs/handling-instrument-events-for-interest-rate-swaps#handling-cash-flow-exchange-on-fixing-dates). - `SwapPrincipalEvent`. This event is automatically emitted for one or both legs on one or more dates, providing principal exchange is set up in the instrument definition. [More information](/v1/docs/handling-instrument-events-for-interest-rate-swaps#handling-cash-flow-exchange-on-fixing-dates1). - `MaturityEvent`. This event is automatically emitted on the maturity date to zero the holding. [More information](/v1/docs/handling-instrument-events-for-interest-rate-swaps#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/Interest-rate-swap-and-instrument-events.ipynb). ## Mastering instruments and establishing positions Imagine we have a vanilla interest rate swap mastered in LUSID with the following characteristics: - Notional of 100000. - Start date of 1 January 2026 and maturity date of 31 December 2030, trading and settling on the start date. - Annual payment on the 15th. Payment dates are therefore: 15 January 2027, 15 January 2028, 15 January 2029, 15 January 2030. - A fixed receive leg at 5%. - A floating pay leg based on the SOFR compounded index. We have a portfolio with a holding in this instrument of one unit at zero cost: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-57SQFXQX.png) ## Handling cash flow exchange on payment dates LUSID emits `SwapCashFlowEvent`: - For a fixed leg on each payment date. - For a floating leg on each payment date *providing interest rate fixings can be located in the Quote Store*. [More information](/v1/docs/how-do-i-load-an-interest-rate-fixing-into-the-lusid-quote-store). For more information on `SwapCashFlowEvent`, 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 `SwapCashFlow` transaction type in the `default` source. [See our recommendation](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#swapcashflowevent). With the `SwapCashFlow` transaction type in place, we can [examine holdings](/v1/docs/how-do-i-generate-a-holdings-report) after the first payment date to see a cash holding for the interest differential between pay and receive legs: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-6IV0ANAC.png) We can examine [output transactions](/v1/docs/input-and-output-transactions) to see the pair of transactions (one per leg) generated to facilitate this exchange: - The receive leg is for 5191.78 - The pay leg is for -4752.24, netting 439.54: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-4GP6A90A.png) ## Handling principal exchange LUSID emits `SwapPrincipalEvent` on the maturity date for a leg if its `notionalExchangeType` field is set to `Final` in the instrument definition. Note the following: - You can set this field to `Initial` and `Both` but these values do not currently generate `SwapPrincipalEvent` on the start date. - `SwapPrincipalEvent` is emitted at exactly the same datetime as `MaturityEvent`, but is always processed first. For more information on `SwapPrincipalEvent`, 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 `SwapPrincipal` transaction type in the `default` source. [See our recommendation](/v1/docs/recommended-transaction-types-for-instrument-lifecycle-events#swapprincipalevent). Imagine we have a USD/GBP cross-currency swap with a pay notional of $130000 and a receive notional of £100000, exchanged at maturity. With the `SwapPrincipal` transaction type in place, and SHKs to separate principal and interest payments, we can examine holdings on the maturity date to see the effect of the exchange: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-KA8O1I6L.png) We can examine output transactions to see the pair of transactions (one per leg) generated to facilitate this exchange: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-ZJIWRZ4H.png) ## Handling instrument maturity LUSID 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 `Maturity` transaction type in place, we can examine holdings on the maturity date to see there is no longer a position in the `InterestRateSwap` instrument in the portfolio: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-G50RTE43.png) We can examine output transactions to see the transaction generated to reduce the units down to zero: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image-KQ8JFLBP.png)