--- title: "Modelling exchange-traded options in LUSID" slug: "modelling-exchange-traded-options-in-lusid" updated: 2026-06-17T13:53:17Z published: 2026-06-17T13:53:17Z canonical: "support.lusid.com/modelling-exchange-traded-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 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](/v1/docs/what-instruments-does-lusid-support). > **Note**: See also this article on [instrument events](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments) and these Jupyter Notebook implementations for [cash-settled options](https://github.com/finbourne/finbourne-notebooks/blob/main/V3/features/instrument-events/ExchangeTradedOption-(cash-settlement)-and-instrument-events.ipynb) and [physically-settled options](https://github.com/finbourne/finbourne-notebooks/blob/main/V3/features/instrument-events/ExchangeTradedOption-(physical-settlement)-and-instrument-events.ipynb). ## Mastering an instrument There are [numerous tools](/v1/docs/how-do-i-master-an-instrument) 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](/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 `ExchangeTradedOption`. For more information on these fields, select **ExchangeTradedOption** from the **definition** dropdown in the [UpsertInstruments](https://www.lusid.com/docs/api/lusid/endpoints/instruments/UpsertInstruments) API reference: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(448).png) ### Specifying the underlying instrument If the asset underlying an `ExchangeTradedOption` is: - An [equity](/v1/docs/modelling-equities-in-lusid) or an [exchange-traded future](/v1/docs/modelling-exchange-traded-futures-and-options-in-lusid), 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](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments) 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: ```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": "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](/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. - `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. Instrument events are available. - Be populated with a full inline economic definition if the underlying is any other type of asset. Note instrument events are not available. - `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](/v1/docs/modelling-exchange-traded-options-in-lusid#valuing-your-position)). - `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](/v1/docs/what-is-a-lusid-instrument-id-or-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](/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": "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](/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": "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](/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 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](/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 `BuyETO` transaction type as follows: ```json 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](/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 `(units * price * contracts * contract size) / scale factor`, and stores the result in the `Transaction/default/GrossConsideration` system property: `(1000 * 3.13 * 1 * 100) / 1 = 313,000` - 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: `313,000 + 170 = 313,170` ### Confirming positions You can [generate a holdings report](/v1/docs/how-do-i-generate-a-holdings-report) to see the impact of the transaction on security and cash holdings, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(452).png) ### Auditing LUSID’s transaction type calculations You can examine the [output transaction](/v1/docs/input-and-output-transactions) automatically generated by LUSID to audit calculated amounts, for example: ![](https://cdn.document360.io/d575ad81-c0ed-4980-bbd1-d59ac5c3de82/Images/Documentation/image(453).png) ## Valuing your position To value your position, work through our [valuation checklist](/v1/docs/valuation-checklist). | **Pricing model** | **Notes** | | --- | --- | | `SimpleStatic` | **Recommended**. This is the default. Calculates PV according to the formula `price / scaling factor * units * contract size`. Requires a market price uploaded to the LUSID Quote Store for both: - The `ExchangeTradedOption` instrument. - The underlying instrument. See below for an example. | For example, to value a position in the European call option on BMW shares defined above using `SimpleStatic`: 1. [Load two market prices](/v1/docs/how-do-i-upload-a-market-price-or-fx-spot-rate-to-the-quote-store) into the LUSID Quote Store for the valuation date, in this case 11 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": "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](/v1/docs/how-do-i-create-or-generate-a-recipe) to locate this market data, 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.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](/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(454).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 `ExchangeTradedOption` 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’. Providing the underlying is an `Equity` or a `Future`, an `ExchangeTradedOption` is tightly integrated into LUSID’s [instrument event framework](/v1/docs/understanding-instrument-lifecycle-events-emitted-by-lusid). Note that other underlyings do not support instrument events. To enable this you must: 1. Register a recipe with every portfolio holding an `ExchangeTradedOption`. 2. Create transaction types to determine the economic impact of the transactions automatically generated by `ExchangeTradedOption` events. **Required reading**: [Handling instrument events for options](/v1/docs/handling-lifecycle-events-for-exchangetradedoption-instruments) | **Instrument event** | Event emission criteria | **If emitted, effect of LUSID default transaction template** | | --- | --- | --- | | `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 `ExchangeTradedOption` is defined as cash-settled. | One transaction is automatically generated with the realised gain. | | `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 `ExchangeTradedOption` is defined as physically-settled. | Two transactions are automatically generated, one for the `ExchangeTradedOption` 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 or cannot enable 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.