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.

LUSID provides the following instrument lifecycle events 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.
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.
MaturityEvent. This event is automatically emitted on the maturity date to zero the holding. More information.

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 receive leg fixed at 5%.
A pay leg floating around LIBOR.

We have a portfolio with a holding in this instrument of one unit at zero cost:

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.

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

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

With the SwapCashFlow transaction type in place, we can examine holdings after the first payment date to see a cash holding for the interest differential between pay and receive legs:

We can examine 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:

Handling principal exchange

LUSID emits SwapPrincipalEvent on the maturity date for each leg whose 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.

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

Imagine we have a USD/GBP cross-currency swap with a pay notional of $130000 and 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:

We can examine output transactions to see the pair of transactions (one per leg) generated to facilitate this exchange:

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.

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

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 vanilla InterestRateSwap instrument in the portfolio:

We can examine output transactions to see the transaction generated to reduce the units down to zero: