Modelling PIK bonds in LUSID

You can model a payment-in-kind (PIK) bond as a special kind of ComplexBond in LUSID. See other uses for this instrument type.

A PIK bond pays some or all of its interest by adding to the principal rather than in cash. LUSID splits each coupon for you, grows the current face of your holding, and pays later coupons and the final redemption on the grown amount.

Mastering an instrument

There are numerous methods you can use to master a PIK bond as an instrument of type ComplexBond in the LUSID Security Master.

Some fields are common to all types of instrument, such as an intuitive name, the requirement to specify a set of identifiers, and the facility to store extra information as properties.

Fields in the economic definition object are specific to ComplexBond. For more information on these fields, select ComplexBond from the definition dropdown in the API documentation:

In this tutorial, we’ll master a three-year bond paying an 8% coupon twice a year. For the first two years, half of each coupon is paid in cash and half is capitalised into the principal. For the final year, the whole coupon is paid in cash. We call the UpsertInstruments API as follows:

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments?scope=mycustominstrscope"
   -H "Content-Type: application/json-patch+json"
   -H "Authorization: Bearer <your-API-access-token>"
   -d '{
  "upsert-request-1": {
    "name": "PIK bond",
    "identifiers": {"ClientInternal": {"value": "PIK"}},
    "definition": {
      "instrumentType": "ComplexBond",
      "schedules": [
        {
          "scheduleType": "FixedSchedule",
          "startDate": "2024-01-15T00:00:00+00:00",
          "maturityDate": "2027-01-15T00:00:00+00:00",
          "paymentCurrency": "USD",
          "notional": 1,
          "couponRate": 0.08,
          "flowConventions": {
            "paymentFrequency": "6M",
            "dayCountConvention": "Thirty360",
            "rollConvention": "15",
            "businessDayConvention": "Following",
            "paymentCalendars": ["USD"],
            "resetCalendars": [],
            "currency": "USD",
            "accrualDateAdjustment": "Unadjusted"
          }
        },
        {
          "scheduleType": "PikSchedule",
          "startDate": "2024-01-15T00:00:00+00:00",
          "maturityDate": "2026-01-15T00:00:00+00:00",
          "pikPaymentType": "InterestCapitalisation",
          "pikFraction": 0.5
        }
      ],
      "tradingConventions": {
        "priceScaleFactor": 100
      }
    }
  }
}'

Note the following:

• We’ve chosen to master this instrument in a custom instrument scope (specified in the URL).

• The identifiers field uniquely identifies the instrument using a ClientInternal identifier.

• In the economic definition object:

  • The instrumentType must be ComplexBond.

  • The schedules array contains a FixedSchedule that sets the coupon, and a PikSchedule that sets how much of that coupon is paid in kind. A PikSchedule always works alongside a FixedSchedule or FloatSchedule; it cannot stand on its own.

  • In the FixedSchedule:

    • The notional must be unitised (set to 1), with the amount bought or sold specified on the transaction. LUSID calculates PIK amounts per unit, so a different notional gives the wrong amounts.

    • The couponRate is the whole coupon, cash and PIK together, expressed as a decimal rather than a percentage (0.08 for 8%).

    • The flowConventions object stores all the information necessary to determine coupon periods, accrued interest amounts and payment dates:

      • The paymentFrequency can be any tenor, in this case 6M to signify twice a year. The Thirty360 day count gives every full coupon period exactly 180 days. Supported day count conventions.

      • The rollConvention field should count back from maturity, so in this case 15 for a bond maturing on 15 January, which means the coupon dates are the 15th of January and July. We also recommend setting a businessDayConvention to determine what should happen if this is not a good business day. More information on roll and business day conventions. Note business days in LUSID are determined by holiday calendars.

      • The accrualDateAdjustment field is optional and defaults to Adjusted. This is suitable for European bonds but for US bonds we recommend Unadjusted.

  • In the PikSchedule:

    • The startDate and maturityDate set which coupons are PIK coupons. A coupon is a PIK coupon if its accrual period starts on or after the startDate and before the maturityDate. In our example, these are the first four coupons. Coupons after the PIK period are paid wholly in cash, on the grown principal.

    • The pikPaymentType of InterestCapitalisation means the PIK portion is added to the principal. See other options.

    • The pikFraction of 0.5 means half of each coupon is paid in kind and half in cash. It must be between 0 (all cash) and 1 (all PIK).

• The tradingConventions.priceScaleFactor field is set to 100 so market prices can be entered as a percentage of par.

• If you do not specify a stubType field, the first and last coupon periods are expected to be regular. See how to model irregular periods.

Providing the request is successful, the response:

• Confirms the globally-unique LUID for the instrument.

• Generates extra fields that are stored as part of the instrument definition and can be filtered on.

• Supplies default values for fields not explicitly specified in the request:

{
  "values": {
    "upsert-request-1": {
      "scope": "mycustominstrscope",
      "lusidInstrumentId": "LUID_00003HC4",
      "name": "PIK bond",
      "identifiers": {
        "LusidInstrumentId": "LUID_00003HC4",
        "ClientInternal": "PIK"
      },
      "properties": [],
      "instrumentDefinition": {
        "identifiers": {},
        "calculationType": "Standard",
        "schedules": [
          {
            "startDate": "2024-01-15T00:00:00.0000000+00:00",
            "maturityDate": "2027-01-15T00:00:00.0000000+00:00",
            "flowConventions": {
              "currency": "USD",
              "paymentFrequency": "6M",
              "dayCountConvention": "Thirty360",
              "rollConvention": "15",
              "paymentCalendars": [
                "USD"
              ],
              "resetCalendars": [],
              "settleDays": 0,
              "resetDays": 0,
              "leapDaysIncluded": true,
              "accrualDateAdjustment": "Unadjusted",
              "businessDayConvention": "F",
              "accrualDayCountConvention": "Thirty360"
            },
            "couponRate": 0.08,
            "notional": 1.0,
            "paymentCurrency": "USD",
            "stubType": "None",
            "scheduleType": "FixedSchedule"
          },
          {
            "startDate": "2024-01-15T00:00:00.0000000+00:00",
            "maturityDate": "2026-01-15T00:00:00.0000000+00:00",
            "isPikFractionElectable": false,
            "pikFraction": 0.5,
            "pikPaymentType": "InterestCapitalisation",
            "pikTravelsFree": true,
            "pikInterestBasis": "Alternative",
            "scheduleType": "PikSchedule"
          }
        ],
        "roundingConventions": [],
        "assetBacked": false,
        "tradingConventions": {
          "priceScaleFactor": 100.0,
          "minimumOrderSize": 0.0,
          "minimumOrderIncrement": 0.0,
          "priceQuotationType": "Clean"
        },
        "instrumentType": "ComplexBond"
      },
      "state": "Active",
      "assetClass": "Credit",
      "domCcy": "USD",
      "relationships": []
    }
  },
  ...
}

Understanding how LUSID pays a PIK coupon

A PIK bond needs no extra market data. LUSID calculates everything from the instrument definition and your holding. You do not load factors or quotes, as you do for a mortgage-backed security.

Splitting each coupon

On each PIK coupon date, LUSID splits the coupon into two parts:

• A cash coupon of the coupon multiplied by (1 − pikFraction).

• A capitalised amount of the coupon multiplied by pikFraction. LUSID adds this to the current face of your holding. The number of units does not change.

Each coupon is calculated on the current face of your holding on the coupon date. Since the current face grows with each capitalisation, both parts of the next coupon grow too. This is how the PIK interest compounds. In our example, a holding of 100,000 units bought at issue develops as follows:

Note the following:

• LUSID does not store accreted principal on the instrument. It records the current face on each holding, so every holding must start with a current face. If a holding has none, LUSID cannot calculate its coupons. See how to book a purchase.

• LUSID credits the exact capitalised amount unless you specify a faceRoundingConvention on the PikSchedule (for example, Floor to capitalise whole currency units only).

Other kinds of PIK bond

You can change the fields of the PikSchedule to model other structures:

Note the following:

• The values of pikPaymentType and faceRoundingConvention are case-sensitive.

• For a floating-rate PIK bond, use a FloatSchedule instead of a FixedSchedule. You must then load fixings and register a recipe that can locate them, as for any floating-rate ComplexBond.

• You can specify more than one PikSchedule, providing their date ranges do not overlap.

• You cannot combine a PikSchedule with a StepSchedule, OptionalitySchedule or BondConversionSchedule, or set assetBacked or parPerUnit on a PIK bond.

• LUSID does not currently support corporate actions on a PIK bond other than its maturity and a default.

Electing how to pay a PIK toggle coupon

For a PIK toggle bond, each coupon is paid in cash (or according to the pikFraction, if you set one) unless you elect otherwise. To elect for a particular coupon, you load a PikBondCouponEvent for it and then instruct LUSID how to respond.

First, make sure your portfolio has a corporate action source registered with it, and load the event into that source. For example, for the 15 July 2024 coupon of a PIK toggle bond with LUID LUID_00003HC5:

curl -X POST "https://<your-domain>.lusid.com/api/api/corporateactionsources/MySourceScope/MySourceCode/instrumentevents"
   -H "Content-Type: application/json-patch+json"
   -H "Authorization: Bearer <your-API-access-token>"
   -d '[
  {
    "instrumentEventId": "LUID_00003HC5_PikBondCouponEvent_20240715",
    "instrumentIdentifiers": {"Instrument/default/LusidInstrumentId": "LUID_00003HC5"},
    "description": "PIK toggle election for the 15 July 2024 coupon",
    "participationType": "MandatoryWithChoices",
    "instrumentEvent": {
      "instrumentEventType": "PikBondCouponEvent",
      "exDate": "2024-07-15T00:00:00Z",
      "paymentDate": "2024-07-15T00:00:00Z",
      "elections": [
        {"electionKey": "None", "isDefault": true, "isChosen": false},
        {"electionKey": "InterestCapitalisation", "isDefault": false, "isChosen": false}
      ]
    }
  }
]'

Note the following:

• The instrumentEventId must have the form <LUID>_PikBondCouponEvent_<payment date as yyyyMMdd>. LUSID uses it to match your election to the right coupon period.

• The participationType must be MandatoryWithChoices.

• The elections array offers None (pay in cash) and InterestCapitalisation (pay in kind). For a bond with a pikPaymentType of AdditionalSecurities, offer AdditionalSecurities instead.

Then call the UpsertInstrumentEventInstructions API for your portfolio with the event’s ID, the election key and the percentage to pay in kind. For example, to capitalise the whole coupon:

curl -X POST "https://<your-domain>.lusid.com/api/api/portfolios/FixedIncome/US/instrumenteventinstructions?successMode=Partial"
   -H "Content-Type: application/json-patch+json"
   -H "Authorization: Bearer <your-API-access-token>"
   -d '{
  "elect-1": {
    "instrumentEventInstructionId": "elect-1",
    "instrumentEventId": "LUID_00003HC5_PikBondCouponEvent_20240715",
    "instructionType": "ElectForHolding",
    "holdingId": 83898241,
    "electionKey": "InterestCapitalisation",
    "quantityInstructed": {"type": "Percentage", "amount": 100}
  }
}'

Note the following:

• The instructionType must be ElectForHolding, with the holdingId of your holding (returned by the GetHoldings API), since only this type accepts a percentage.

• An election of None, or 0 percent, pays the coupon in cash. A coupon with no election pays the default: the pikFraction if you set one, or cash otherwise.

For a toggle bond held from issue, this election means that on 15 July 2024 LUSID generates no cash coupon, and a BondInterestCapitalisation transaction of 4000 that raises the current face to 104000. The next coupon, with no election, is paid wholly in cash on the new face: 104000 × 0.04 = 4160.

Booking a transaction to establish a position

Once an instrument is mastered, you can book a transaction to record the acquisition of a quantity in a particular transaction portfolio. As mentioned above, we recommend unitising PIK bonds and specifying the face amount on transactions.

For example, the following call to the BatchUpsertTransactions API acquires 100,000 units of our PIK bond before its first coupon:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/FixedIncome/US/transactions/$batchUpsert?successMode=Partial&preserveProperties=true'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "transactionRequest-1": {
    "transactionId": "pik_purchase_001",
    "type": "BuyPIK",
    "instrumentIdentifiers": {"Instrument/default/ClientInternal": "PIK"},
    "transactionDate": "2024-03-12T00:00:00.0000000+00:00",
    "settlementDate": "2024-03-15T00:00:00.0000000+00:00",
    "units": 100000,
    "transactionPrice": {
      "price": 99,
      "type": "CleanPrice"
    },
    "totalConsideration": {
      "amount": 0,
      "currency": "USD"
    }
  }
}'

Note the following:

• The instrumentIdentifiers field uses the ClientInternal identifier to resolve the transaction to the correct PIK bond instrument (but it could use the LUID).

• The type field invokes a custom BuyPIK transaction type to confer a particular economic impact (see below).

• The units field specifies the face amount bought.

• The transactionPrice object records the clean market price (not including accrued interest) as a percentage of par. This is used by LUSID to automatically calculate the gross consideration (see below).

• The totalConsideration object:

  • Sets the settlement currency to USD.

  • Specifies a cost of 0 to enable LUSID to automatically derive the total consideration (see below).

• LUSID has a transaction fee engine to help calculate fees and either capitalise or expense them.

Note: This example assumes the transaction, settlement and portfolio currencies are the same. If not, you can specify exchange rates.

We recommend that every transaction type you use to buy or sell a PIK bond includes the Txn:BondInterest and Txn:GrossConsideration transaction type calculations, so that LUSID calculates the current face and the amounts that depend on it for you. For example, you might create a BuyPIK transaction type as follows:

curl -X PUT 'https://<your-domain>.lusid.com/api/api/transactionconfiguration/types/default/BuyPIK?scope=default'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "aliases": [
    {
      "type": "BuyPIK",
      "description": "Transaction type for PIK bond purchases",
      "transactionClass": "Trading",
      "transactionRoles": "LongLonger",
      "isDefault": false
    }
  ],
  "movements": [
    {
      "name": "Increase units of security",
      "movementTypes": "StockMovement",
      "side": "Side1",
      "direction": 1
    },
    {
      "name": "Decrease cash balance",
      "movementTypes": "CashCommitment",
      "side": "Side2",
      "direction": -1
    },
    {
      "name": "Report bond interest bought as a flow of value out of the security",
      "movementTypes": "Carry",
      "side": "BondInterest",
      "direction": -1
    }
  ],
  "calculations": [
    {
      "type": "Txn:BondInterest"
    },
    {
      "type": "Txn:GrossConsideration"
    },
    {
      "type": "DeriveTotalConsideration",
      "formula": "Txn:GrossConsideration + Txn:TotalFees"
    }
  ]
}'

Note the following:

• The Txn:GrossConsideration calculation first sets the current face to units * notional, and stores the result in the Transaction/default/CurrentFace system property. It then calculates gross consideration according to the formula (Transaction/default/CurrentFace * price / priceScaleFactor) + Transaction/default/BondInterest, and stores the result in the Transaction/default/GrossConsideration system property.

• The Txn:BondInterest calculation automatically calculates the amount of bond interest bought or sold, cash and PIK together, and stores the result in the Transaction/default/BondInterest system property, available for use in sides.

• The DeriveTotalConsideration calculation automatically calculates total consideration according to the given, user-defined formula, which in this case sums gross consideration and total fees; this is stored as the totalConsideration.amount of the transaction.

• The StockMovement uses the built-in Side1 side to establish a holding in the instrument with the specified number of units at a cost derived from the total consideration. Side1 also records the current face of the holding, taken from Transaction/default/CurrentFace.

• The CashCommitment movement uses the built-in Side2 to decrease the instrument currency holding by the total consideration.

• The Carry movement uses a custom BondInterest side to record a flow of value out of the instrument equivalent to the interest purchased.

Important: LUSID can only work out the current face for a purchase made before the first capitalisation, when each unit carries one unit of face. If you buy a PIK bond that has already capitalised interest, supply the current face yourself in a Transaction/default/CurrentFace property on the transaction. For example, after the July 2024 coupon in our example, each unit carries 1.02 of face, so a purchase of 50,000 units has a current face of 51,000. LUSID then applies the price to your current face, and calculates later coupons on it. However, LUSID calculates the accrued interest bought on the units rather than the current face, so you should also supply it in a Transaction/default/BondInterest property. For a purchase settling on 16 September 2024, this is 51000 × 0.08 × 61 / 360 = 691.33 (LUSID would otherwise calculate 677.78).

The built-in PikBondBuy transaction type has no calculations, so if you use it you must always supply Transaction/default/CurrentFace.

You might create a BondInterest custom side as follows:

curl -X PUT 'https://<your-domain>.lusid.com/api/api/transactionconfiguration/sides/BondInterest?scope=default'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "security": "Txn:LusidInstrumentId",
  "currency": "Txn:TradeCurrency",
  "rate": "Txn:TradeToPortfolioRate",
  "units": "Txn:Units",
  "amount": "Txn:BondInterest"
}'

Note this is the same as Side1 except the amount field is set to Txn:BondInterest instead of Txn:TradeAmount, and there is no currentFace field.

Auditing LUSID's calculations of transaction amounts

We can navigate to Portfolio Management > Transactions in Output mode in the LUSID web app to call the BuildTransactions API with a suitable window and examine the output transaction generated by LUSID:

• The current face is units * notional, so 100000 × 1 = 100000

• The gross transaction amount is current face * price / priceScaleFactor, so 100000 × 99 / 100 = 99000

• The amount of accrued interest purchased, for the 60 days from 15 January to the settlement date, is 100000 × 0.08 × 60 / 360 = 1333.33. Half of this (666.67) will be capitalised on the next coupon date, but LUSID reports it as a single amount.

• Since the price is clean, the gross consideration is the gross transaction amount plus accrued interest: 99000 + 1333.33 = 100333.33

• The total consideration is gross consideration plus total fees. There are no fees in this example, so this is 100333.33.

[Screenshot needed: Portfolio Management > Transactions in Output mode, showing pik_purchase_001 with its current face, bond interest and gross consideration.]

Confirming positions on the settlement date

We can navigate to Portfolio Management > Holdings to call the GetHoldings API on the settlement date and see that we have:

• 100,000 units of the PIK bond instrument with a current face of 100000, and a cost calculated as total consideration minus accrued interest: 100333.33 - 1333.33 = 99000

• A USD currency holding with a negative amount reflecting the total consideration paid.

[Screenshot needed: Portfolio Management > Holdings on 15 March 2024, showing the PIK bond holding (units, current face, cost) and the USD cash holding.]

Valuing your position

The basic process of valuing a portfolio containing a PIK bond is the same as for a vanilla fixed-rate bond.

Note the following for a PIK bond:

• We recommend the BondLookupPricer pricing model. LUSID multiplies the market price by the current face of your holding, and adds accrued interest on the current face.

• Include the Valuation/CurrentNotional metric in your valuation request. LUSID needs it to scale the valuation by the current face. If you omit it, LUSID values the holding on its units, which understates it once interest has been capitalised.

• In our example, at a price of 99:

  • On the settlement date, PV is 0.99 × 100000 + 1333.33 = 100333.33.

  • On 31 July 2024, after the first capitalisation, PV is 0.99 × 102000 + 102000 × 0.08 × 16 / 360 = 100980 + 362.67 = 101342.67.

• Valuation/Accrued is the whole accrued coupon, cash and PIK together. Valuation/PikAccrual reports the part of it that will be capitalised (666.67 on the settlement date, 181.33 on 31 July). Don’t add the two together. Valuation/InstrumentPikAccrual reports the PIK accrual for one unit of the instrument.

• The Discounting pricing model can also value a PIK bond, but it discounts each capitalised amount as if it were paid in cash on its coupon date. It does not compound the capitalised interest or repay it at maturity, so its PV equals that of the same bond paying its whole coupon in cash.

• LUSID calculates Analytic/YieldToMaturity, durations, convexity and z-spreads from the bond’s cash flows after compounding, so a PIK bond has a longer duration than the same bond paying cash. For a floating-rate PIK bond, Analytic/DiscountMargin is quoted on the cash part of the coupon; it is not available if the whole coupon is paid in kind.

• For a bond with a pikPaymentType of AdditionalSecurities, LUSID cannot calculate yields, durations or z-spreads.

Assessing risk

The basic process of assessing risk while valuing a PIK bond is the same as for a vanilla fixed-rate bond.

Note the following for a PIK bond:

• Under Discounting, LUSID bumps a PV that treats capitalised interest as cash, so Risk/Rates/Pv01 equals that of the same bond paying cash. It is not consistent with the duration, which LUSID calculates after compounding.

• Under BondLookupPricer with the spreadAnchoredRisk model option, LUSID revalues the bond’s cash flows after compounding. This is not available for a bond with a pikPaymentType of AdditionalSecurities.

Monitoring the lifecycle of the instrument

A PIK bond is tightly integrated into LUSID's instrument event framework. To enable this for your domain, you must:

1. Register a recipe with every portfolio holding such an instrument.

2. Make sure every holding has a current face. See how.

3. Create transaction types to determine the economic impact of the transactions automatically generated by the following events.

LUSID emits all of the following events automatically, except the PikBondCouponEvent you load to make an election. LUSID calculates each amount on the current face of your holding.

In our example, the 15 July 2024 coupon generates a BondCoupon transaction of 2000 and a BondInterestCapitalisation transaction of 2000. The current face of the holding rises from 100000 to 102000, and its cost from 99000 to 101000; the number of units stays at 100,000. On the maturity date, the PikBondPrincipal transaction repays the current face of 108243.22 and the Maturity transaction removes the units.