Modelling exchange-traded options in LUSID

You can model an exchange-traded options contract as an instrument of type ExchangeTradedOption in LUSID. See all supported instruments.

Mastering an instrument

There are numerous tools you can use to master an ExchangeTradedOption 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 ExchangeTradedOption. For more information on these fields, select ExchangeTradedOption from the definition dropdown in the UpsertInstruments API reference:

Specifying the underlying instrument

If the asset underlying an ExchangeTradedOption is:

• An equity or an exchange-traded future, the recommended approach is to master it as a separate, dedicated instrument in LUSID and provide a reference to a MasteredInstrument. If you do this, instrument events are available. See the rest of this article for more information.

• A bond, interest rate, index, commodity or any other type of asset, the only option is to provide an inline definition as part of the ExchangeTradedOption. Instrument events are not available.

Mastering an ExchangeTradedOption instrument

The following example masters a European call option on BMW shares that is itself already mastered as an instrument of type Equity in LUSID:

curl -X POST 'https://mydomain.lusid.com/api/api/instruments?scope=MyCustomInstrScope'
   -H 'Content-Type: application/json-patch+json'
   -H 'Authorization: Bearer myAPIAccessToken'
   -d '{"upsert-request-1": {
    "name": "BMW GR Equity OMON",
    "identifiers": {"ClientInternal": {"value": "ETO_BMW_2024-03-21_European_Physical_Call"}},
    "definition": {
      "instrumentType": "ExchangeTradedOption",
      "startDate": "2025-01-01T00:00:00.0000000+00:00",
      "contractDetails": {
        "domCcy": "EUR",
        "strike": 80,
        "contractSize": 100,
        "country": "DE",
        "deliveryType": "Physical",
        "description": "BMW GR Equity OMON",
        "exchangeCode": "Eurex",
        "exerciseDate": "2025-03-21T00:00:00.0000000+00:00",
        "exerciseType": "European",
        "optionCode": "BMW",
        "optionType": "Call",
        "underlying": {
          "instrumentType": "MasteredInstrument",
          "identifiers": {"Instrument/default/Isin": "DE0005190003"}
        },
        "underlyingCode": "MyIDForBMWQuotes"
      },
      "contracts": 1,
      "refSpotPrice": 0
    }
  }
}'

Note the following:

• The ExchangeTradedOption instrument is mastered in a custom instrument scope (specified in the URL).

• Its identifiers object is set to reference a ClientInternal unique identifier.

• startDate is a mandatory field but note it is not subsequently used by LUSID.

• contractSize is set to the number of underlying units per contract as specified by the exchange.

• deliveryType can be Physical (if you intend to take delivery of the underlying) or Cash.

• exerciseType can be American or European.

• optionType can be Put or Call.

• The underlying object must either:

  • Have the underlying.instrumentType field set to MasteredInstrument if the underlying is already mastered in LUSID as an Equity or a Future, and the underlying.identifiers object set to an identifier for that instrument, in this case an ISIN. Note the underlying must reside in the same instrument scope as the ExchangeTradedOption, or else in the default instrument scope.

  • Be populated with a full inline economic definition if the underlying is any other type of asset.

• underlyingCode can be set to any intuitive string that represents a market data identifier for the underlying instrument in the LUSID Quote Store (required for valuation).

• contracts should be set to 1 and the amount bought or sold specified on the transaction.

• refSpotPrice should be set to 0 unless otherwise directed by FINBOURNE Technical Support.

Providing the request is successful, the response:

• Confirms the globally-unique LUID of the ExchangeTradedOption instrument (in this case LUID_00003E8Z).

• Confirms the LUID of the underlying MasteredInstrument providing LUSID is able to resolve it correctly (in this case LUID_00003E90). If not, the unknown instrument is returned.

• 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_00003E8Z",
      "name": "BMW GR Equity OMON",
      "identifiers": {
        "ClientInternal": "ETO_BMW_2024-03-21_European_Physical_Call",
        "LusidInstrumentId": "LUID_00003E8Z"
      },
      "properties": [],
      "instrumentDefinition": {
        "startDate": "2025-01-01T00:00:00.0000000+00:00",
        "contractDetails": {
          "domCcy": "EUR",
          "strike": 80,
          "contractSize": 100,
          "country": "DE",
          "deliveryType": "Physical",
          "description": "BMW GR Equity OMON",
          "exchangeCode": "Eurex",
          "exerciseDate": "2025-03-21T00:00:00.0000000+00:00",
          "exerciseType": "European",
          "optionCode": "BMW",
          "optionType": "Call",
          "underlying": {
            "identifiers": {
              "Instrument/default/Isin": "DE0005190003"
            },
            "masteredDomCcy": "EUR",
            "masteredInstrumentType": "Equity",
            "masteredLusidInstrumentId": "LUID_00003E90",
            "masteredName": "BMW",
            "masteredScope": "MyCustomInstrScope",
            "masteredAssetClass": "Equities",
            "instrumentType": "MasteredInstrument"
          },
          "underlyingCode": "MyIDForBMWQuotes",
          "deliveryDays": 0,
          "businessDayConvention": "F",
          "settlementCalendars": []
        },
        "contracts": 1,
        "refSpotPrice": 0,
        "tradingConventions": {
          "priceScaleFactor": 1,
          "minimumOrderSize": 0,
          "minimumOrderIncrement": 0
        },
        "instrumentType": "ExchangeTradedOption"
      },
      "state": "Active",
      "assetClass": "Unknown",
      "domCcy": "EUR",
      "relationships": []
    }
  },
  ...
}

Booking a transaction to establish a position

Once an ExchangeTradedOption instrument is mastered, you can book a transaction to record the acquisition of a number of contracts in a particular transaction portfolio, for example:

curl -X POST 'https://mydomain.lusid.com/api/api/transactionportfolios/MyPortfolioScope/MyPortfolioCode/transactions/$batchUpsert?successMode=Partial&preserveProperties=true'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer myAPIAccessToken'
  -d '{
  "transactionRequest-1": {
    "transactionId": "my_option_purchase_001",
    "type": "BuyETO",
    "instrumentIdentifiers": {"Instrument/default/LusidInstrumentId": "LUID_00003E8Z"},
    "transactionDate": "2025-01-14T00:00:00.0000000+00:00",
    "settlementDate": "2024-01-15T00:00:00.0000000+00:00",
    "units": 1000,
    "transactionPrice": {
      "price": 3.13,
      "type": "Price"
    },
    "totalConsideration": {
      "amount": 0,
      "currency": "EUR"
    },
    "properties": {
      "Transaction/MyProperties/TradeCommission": {
        "key": "Transaction/MyProperties/TradeCommission",
        "value": {
          "metricValue": {
            "value": 170,
            "unit": "EUR"
          }
        }
      }
    }
  }
}'

Note the following:

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

• The units field specifies the number of contracts.

• The transactionPrice object records the market price of the options contract (not the underlying). This is used by LUSID to automatically calculate gross consideration (see below).

• The totalConsideration object:

  • Sets the settlement currency to EUR.

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

• The trade commission for entering into the contract is recorded as a custom property.

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

You might create a BuyETO transaction type as follows:

curl -X PUT 'https://mydomain.lusid.com/api/api/transactionconfiguration/types/default/BuyETO?scope=default'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer myAPIAccessToken'
  -d '{
  "aliases": [
    {
      "type": "BuyETO",
      "description": "Transaction type for option purchases",
      "transactionClass": "Basic",
      "transactionRoles": "AllRoles",
      "isDefault": false
    }
  ],
  "movements": [
    {
      "name": "Increase units by number purchased",
      "movementTypes": "StockMovement",
      "side": "Side1",
      "direction": 1
    },
    {
      "name": "Decrease cash by total cost of purchase, including commission",
      "movementTypes": "CashCommitment",
      "side": "Side2",
      "direction": -1
    }
  ],
  "calculations": [
    {
      "type": "Txn:GrossConsideration"
    },
    {
      "type": "DeriveTotalConsideration",
      "formula": "Txn:GrossConsideration + Properties[Transaction/MyProperties/TradeCommission]"
    }
  ]
}'

Note the following:

• The StockMovement movement sets the units of the holding to the number purchased in the transaction.

• The CashCommitment movement decreases a cash balance by the total consideration.

• The Txn:GrossConsideration transaction type calculation automatically calculates gross consideration (amount before fees) as price * units * contract size, and stores the result in the Transaction/default/GrossConsideration system property.

• The DeriveTotalConsideration transaction type calculation automatically calculates the totalConsideration.amount field according to the given formula, which in this case sums gross consideration and commission.

Confirming positions

You can generate a holdings report to see the impact of the transaction on security and cash holdings, for example:

Auditing LUSID’s transaction type calculations

You can examine the output transaction automatically generated by LUSID to audit calculated amounts, for example:

Valuing your position

To value your position, work through our valuation checklist.

For example, to value a position in the European call option on BMW shares defined above using SimpleStatic:

1. Load two market prices into the LUSID Quote Store for the valuation date, in this case 11 February 2025:

   curl -X POST 'https://mydomain.lusid.com/api/api/quotes/MyOptionQuotes'
     -H 'Authorization: Bearer myAPIAccessToken'
     -H 'Content-Type: application/json-patch+json'
     -d '{
       "Quote-0001": {
         "quoteId": {
           "quoteSeriesId": {
             "provider": "Lusid",
             "instrumentIdType": "LusidInstrumentId",
             "instrumentId": "LUID_00003E8Z",
             "quoteType": "Price",
             "field": "mid"
           },
           "effectiveAt": "2025-02-11T00:00:00Z"
         },
         "metricValue": {
           "value": 3.15, "unit": "EUR"
         }
       },
       "Quote-0002": {
         "quoteId": {
           "quoteSeriesId": {
             "provider": "Lusid",
             "instrumentIdType": "LusidInstrumentId",
             "instrumentId": "MyIDForBMWQuotes",
             "quoteType": "Price",
             "field": "mid"
           },
           "effectiveAt": "2025-02-11T00:00:00Z"
         },
         "metricValue": {
           "value": 82, "unit": "EUR"
         }
       }
     }'

   Note the following:

   • The first price is for the ExchangeTradedOption instrument and the second for the underlying Equity instrument.

   • Both are encapsulated in a MyOptionQuotes quote scope (specified in the URL).

   • The instrumentIdType field is LusidInstrumentId.

   • The instrumentId field for:

     • The ExchangeTradedOption instrument is its LUID.

     • The underlying Equity instrument is the underlyingCode specified in the ExchangeTradedOption instrument definition, in this case MyIDForBMWQuotes.

2. Create a recipe to locate this market data, for example:

   curl -X POST 'https://mydomain.lusid.com/api/api/recipes'
     -H 'Content-Type: application/json-patch+json'
     -H 'Authorization: Bearer myAPIAccessToken'
     -d '{
     "configurationRecipe": {
       "scope": "MyRecipes",
       "code": "MyBasicRecipe",
       "market": {
         "marketRules": [
           {
             "key": "Quote.LusidInstrumentId.*",
             "dataScope": "MyOptionQuotes",
             "supplier": "Lusid",
             "quoteType": "Price",
             "field": "mid"
           }
         ]
       }
     }
   }'

   Note the following:

   • The key field has a prefix of Quote.LusidInstrumentId. and a suffix of * (wildcard) to find prices keyed by both LUID and underlyingCode.

   • The dataScope field matches the quote scope in which prices are encapsulated in the LUSID Quote Store.

   • The other fields match their respective quote fields exactly (values are case-sensitive).

3. Generate a valuation report with appropriate metrics, for example:
   

Assessing risk

For more on how LUSID calculates exposure, see this article.

LUSID supports both analytic and bump and valuation mechanisms for assessing risk; contact Technical Support if you need more information.

Monitoring the lifecycle of the instrument

An ExchangeTradedOption has an exercise date specified when you master that instrument. If you do not exercise the option on or before that date, the instrument ‘expires’.

Note: An instrument in LUSID is still available post-expiry, although the valuation is zero. If you set your holding to zero it no longer appears in reports unless you are deliberately backdating.

Handling automatic lifecycle events

LUSID is transitioning to a system where it automatically emits lifecycle events for supported instruments. We provide default transaction templates that you can use as-is to automatically generate transactions in impacted portfolios, and recommendations for transaction types that deliver appropriate economic impacts.

Contact us to turn this feature on in your environment. The following events are available for an ExchangeTradedOption:

Manually loading settlement transactions

If you do not want to turn on automatic instrument lifecycle events you can continue to monitor upcoming cashflows using Dashboards > CashLadder in the LUSID web app, or by calling the GetPortfolioCashLadder API directly.

You can call the GetUpsertablePortfolioCashFlows API to  return imminent cashflows as upsertable DTOs ready to manually load into LUSID as input transactions.