--- title: "Modelling equity options in LUSID" slug: "modelling-equity-options-in-lusid" updated: 2025-09-26T07:46:49Z published: 2025-09-26T07:46:49Z canonical: "support.lusid.com/modelling-equity-options-in-lusid" --- > ## 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. # Modelling equity options in LUSID You can model an equity (or stock) options contract as an instrument of type `EquityOption` in LUSID. [See all supported instruments](/v1/docs/what-instruments-does-lusid-support). > **Note**: You can model rights issues and warrants using this instrument type too. ## Mastering an instrument There are [numerous tools](/v1/docs/how-do-i-master-an-instrument) 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](/v1/docs/understanding-instrument-identifiers) of `identifiers`, and the facility to [store extra information](/v1/docs/properties) 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](https://www.lusid.com/docs/api/lusid/endpoints/instruments/UpsertInstruments) API reference, or alternatively examine the [EquityOption](https://www.lusid.com/docs/api/lusid/schemas/EquityOption/) schema: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(886).png) ### Mastering the underlying `Equity` instrument You must first separately [master the underlying equity instrument](/v1/docs/modelling-equities-in-lusid), and then provide a reference to it as a `MasteredInstrument`. ### Mastering the `EquityOption` instrument The following example masters a cash-settled European put option on BMW shares: ```json 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"}      }    }  } }' ``` Note the following: - The `EquityOption` instrument is mastered in a [custom instrument scope](/v1/docs/understanding-instrument-scopes) (specified in the URL). - Its `identifiers` object is set to reference a `ClientInternal` [unique identifier](/v1/docs/what-are-unique-and-non-unique-identifiers). - `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](/v1/docs/what-is-a-lusid-instrument-id-or-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](/v1/docs/what-is-the-unknown-instrument-or-luid-zzzzzzzz) is returned. - Generates extra fields that are stored as part of the instrument definition and can be [filtered on](/v1/docs/filtering-information-retrieved-from-lusid). - Supplies default values for fields not explicitly specified in the request: ```json {  "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": []    }  },  ... } ``` ## Booking a transaction to establish a position Once an `EquityOption` instrument is mastered, you can [book a transaction](/v1/docs/how-do-i-create-or-update-a-transaction) to record the acquisition of a number of contracts in a particular [transaction portfolio](/v1/docs/what-is-a-transaction-portfolio), for example: ```json 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"          }        }      }    }  } }' ``` Note the following: - The `type` field invokes a custom `BuyEquityOption` [transaction type](/v1/docs/what-is-a-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](/v1/docs/properties). > **Note**: This example assumes the transaction, settlement and portfolio currencies are all the same. If not, you can [specify exchange rates](/v1/docs/transactions-and-exchange-rates). You might create a `BuyEquityOption` transaction type as follows: ```json 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]"    }  ] }' ``` Note the following: - The `StockMovement` [movement](/v1/docs/what-is-a-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](/v1/docs/what-is-a-transaction-type-calculation#txngrossconsideration) 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. ### Confirming positions We can [generate a holdings report](/v1/docs/how-do-i-generate-a-holdings-report) for the settlement date to see the impact of the transaction on security and cash holdings: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(888).png) ### Auditing LUSID’s transaction type calculations We can examine [output transactions](/v1/docs/input-and-output-transactions) automatically generated by LUSID up to the settlement date to audit calculated amounts: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(889).png) ## Valuing your position To value your position, work through our [valuation checklist](/v1/docs/valuation-checklist). The following [pricing models](/v1/docs/what-pricing-models-can-i-use-in-my-valuation) 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](/v1/docs/recipes-changing-the-default-pricing-models-for-instrument-types) 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](/v1/docs/what-pricing-models-can-i-use-in-my-valuation#option-pricing-models). | For example, to value a position in the European call option on BMW shares defined above using `ConstantTimeValueOfMoney`: 1. [Load a market price](/v1/docs/how-do-i-upload-a-market-price-or-fx-spot-rate-to-the-quote-store) into the LUSID Quote Store for the underlying BMW instrument (not the option) on the valuation date, in this case 15 February 2025: ```json 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"      }    }  }' ``` 2. [Create a recipe](/v1/docs/how-do-i-create-or-generate-a-recipe) to locate this market data and change the default pricing model, for example: ```json 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"        }      ]    }  } }' ``` 3. [Generate a valuation report](/v1/docs/how-do-i-perform-a-valuation) with appropriate metrics, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(894).png) ## Assessing risk For more on how LUSID calculates exposure, see [this article](/v1/docs/how-does-lusid-calculate-exposure). LUSID supports both analytic and bump and valuation mechanisms for assessing risk; [contact Technical Support](https://www.finbourne.com/contact) if you need more information. ## Monitoring the lifecycle of the instrument 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. ### Handling automatic lifecycle events LUSID is transitioning to a system where it automatically emits [lifecycle events for supported instruments](/v1/docs/understanding-instrument-lifecycle-events-emitted-by-lusid). 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](https://www.finbourne.com/contact) 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](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments). 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. | ### 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](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/GetPortfolioCashLadder) API directly. You can call the [GetUpsertablePortfolioCashFlows](https://www.lusid.com/docs/api/lusid/endpoints/transaction-portfolios/GetUpsertablePortfolioCashFlows) API to return imminent cashflows as upsertable DTOs ready to manually load into LUSID as input transactions.