Modelling equity options in LUSID

Updated
  • Updated on Jun 18, 2025
  • Published on Aug 23, 2024
Prev Next

You can model an equity (or stock) options contract as an instrument of type EquityOption in LUSID. See all supported instruments.

Note: You can model rights issues and warrants using this instrument type too.

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

You must first separately master the underlying equity instrument, and then provide a reference to it as a MasteredInstrument.

The following example masters a European call option on BMW shares:

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": "EO_BMW_2024-03-21_European_Cash_Put",
    "identifiers": {"ClientInternal": {"value": "EO_BMW_2024-03-21_European_Cash_Put"}},
    "definition": {
      "instrumentType": "EquityOption",
      "startDate": "2025-01-01T00:00:00.0000000+00:00",
      "optionMaturityDate": "2025-03-21T00:00:00.0000000+00:00",
      "deliveryType": "Cash",
      "exerciseType": "European",
      "optionType": "Put",
      "equityOptionType": "Vanilla",
      "strike": 80,
      "domCcy": "EUR",
      "numberOfShares": 100,
      "underlying": {
        "instrumentType": "MasteredInstrument",
        "identifiers": {"Instrument/default/Isin": "DE0005190003"}
      }
    }
  }
}'
JSON

Note the following:

  • The EquityOption 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.

  • 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.

  • equityOptionType can be Vanilla, RightsIssue or Warrant.

  • numberOfShares is set to the number of underlying BMW shares per contract.

  • The underlying.instrumentType field must be set to MasteredInstrument and the underlying.identifiers object to an identifier for that instrument, in this case an ISIN for BMW. Note the underlying must reside in the same instrument scope as the EquityOption, or else in the default instrument scope.

Providing the request is successful, the response:

  • Confirms the globally-unique LUID of the EquityOption instrument (in this case LUID_00003EHI).

  • Confirms the LUID of the underlying MasteredInstrument providing LUSID is able to resolve it correctly (in this case LUID_00003EHG). 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": "default",
      "lusidInstrumentId": "LUID_00003EHI",
      "name": "EO_BMW_2024-03-21_European_Cash_Put",
      "identifiers": {
        "ClientInternal": "EO_BMW_2024-03-21_European_Cash_Put",
        "LusidInstrumentId": "LUID_00003EHI"
      },
      "properties": [],
      "instrumentDefinition": {
        "startDate": "2025-01-01T00:00:00.0000000+00:00",
        "optionMaturityDate": "2025-03-21T00:00:00.0000000+00:00",
        "optionSettlementDate": "2025-03-21T00:00:00.0000000+00:00",
        "deliveryType": "Cash",
        "optionType": "Put",
        "strike": 80,
        "domCcy": "EUR",
        "equityOptionType": "Vanilla",
        "numberOfShares": 100,
        "exerciseType": "European",
        "underlying": {
          "identifiers": {
            "Instrument/default/Isin": "DE0005190003"
          },
          "masteredDomCcy": "EUR",
          "masteredInstrumentType": "Equity",
          "masteredLusidInstrumentId": "LUID_00003EHG",
          "masteredName": "BMW",
          "masteredScope": "default",
          "masteredAssetClass": "Equities",
          "instrumentType": "MasteredInstrument"
        },
        "deliveryDays": 0,
        "businessDayConvention": "None",
        "settlementCalendars": [],
        "instrumentType": "EquityOption"
      },
      "state": "Active",
      "assetClass": "Equities",
      "domCcy": "EUR",
      "relationships": []
    }
  },
  ...
}
JSON

Once an EquityOption 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": "BuyEquityOption",
    "instrumentIdentifiers": {"Instrument/default/LusidInstrumentId": "LUID_00003EHI"},
    "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"
          }
        }
      }
    }
  }
}'
JSON

Note the following:

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

  • The units field specifies the number of contracts.

  • The transactionPrice object records the agreed 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 BuyEquityOption transaction type as follows:

curl -X PUT 'https://mydomain.lusid.com/api/api/transactionconfiguration/types/default/BuyEquityOption?scope=default'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer myAPIAccessToken'
  -d '{
  "aliases": [
    {
      "type": "BuyEquityOption",
      "description": "Transaction type for equity 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]"
    }
  ]
}'
JSON

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 * number of shares, 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.

We can generate a holdings report for the settlement date to see the impact of the transaction on security and cash holdings:

We can examine output transactions automatically generated by LUSID up to the settlement date to audit calculated amounts:

To value your position, work through our valuation checklist.

The following pricing models are available for instruments of type EquityOption; note your choice impacts the market data required and the composition of your recipe.

Note: The default pricing model is SimpleStatic; we recommend changing this to one of the pricing models below.

Pricing model

Notes

ConstantTimeValueOfMoney

Ignores the time value of an option and simply reports PV and P&L if the option is in the money, or 0 if out of the money. You only need load market prices for the underlying instrument. See below for an example.

BlackScholes, BjerksundStensland1993, Bachelier

Takes into account the impact of time and other risk factors. Requires complex market data such as discount factors and volatility surfaces in addition to market prices for the underlying instrument. The returns are available as follows: Price and Delta, Gamma, Rho, Theta and Vega ("the Greeks"). More information.

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

  1. Load a market price into the LUSID Quote Store for the underlying BMW instrument (not the option) for the valuation date, in this case 15 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": "Isin",
          "instrumentId": "DE0005190003",
          "quoteType": "Price",
          "field": "mid"
        },
        "effectiveAt": "2025-02-15T00:00:00Z"
      },
      "metricValue": {
        "value": 75, "unit": "EUR"
      }
    }
  }'
    JSON

  2. Create a recipe to locate this market data and change the default pricing model, 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.Isin.*",
          "dataScope": "MyOptionQuotes",
          "supplier": "Lusid",
          "quoteType": "Price",
          "field": "mid"
        }
      ]
    },
    "pricing": {
      "modelRules": [
        {
          "instrumentType": "EquityOption",
          "modelName": "ConstantTimeValueOfMoney"
        }
      ]
    }
  }
}'
    JSON

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

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.

An EquityOption has a maturity 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.

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 EquityOption:

Instrument event type

Event emission criteria

If emitted, effect of LUSID default transaction template

Recommendations for transaction types

OptionExerciseCashEvent

This event is not automatically emitted by LUSID. If your holding is in the money, it can be triggered by loading an event instruction, providing the EquityOption is defined as cash-settled.

One transaction is automatically generated with the realised gain.

See this tutorial. The example instrument is an ExchangeTradedOption, but the events, and the impact of those events, are the same.

OptionExercisePhysicalEvent

This event is not automatically emitted by LUSID. If your holding is in the money, it can be triggered by loading an event instruction, providing the EquityOption is defined as physically-settled.

Two transactions are automatically generated, one for the EquityOption and the other for the underlying instrument.

ExpiryEvent

This event is automatically emitted by LUSID on the expiry date, but only if either OptionExerciseCashEvent or OptionExercisePhysicalEvent has not been triggered.

One transaction is automatically generated setting the option holding to zero and realising a loss.

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.