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 an 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 instrument in LUSID and provide a reference to a
MasteredInstrument
. If you do this, instrument events are available. See below 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 aClientInternal
unique identifier.startDate
is a mandatory field but note it is not subsequently used by LUSID.deliveryType
can bePhysical
(if you intend to take delivery of the underlying) orCash
.exerciseType
can beAmerican
,European
orBermudan
.optionType
can bePut
orCall
.The
underlying
object must either:Have the
underlying.instrumentType
field set toMasteredInstrument
if the underlying is already mastered in LUSID as anEquity
or aFuture
, and theunderlying.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 theExchangeTradedOption
, or else in thedefault
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 to1
and the amount bought or sold specified on the transaction.refSpotPrice
should be set to0
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 caseLUID_00003E8Z
) and also that of theMasteredInstrument
providing LUSID is able to resolve it correctly (in this caseLUID_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 customBuyETO
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) asprice * units * contract size
, and stores the result in theTransaction/default/GrossConsideration
system property.The
DeriveTotalConsideration
transaction type calculation automatically calculates thetotalConsideration.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 generated by LUSID in response to the input transaction, for example:
Valuing your position
To value your position, work through our valuation checklist.
The following pricing models are available for instruments of type ExchangeTradedOption
; note your choice impacts the market data required and the composition of your recipe.
Pricing model | Notes |
---|---|
| This is the default. Calculates PV according to the formula
See below for more information. |
|
For example, to value a position in the European call option on BMW shares defined above using SimpleStatic
:
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 underlyingEquity
instrument.Both are encapsulated in a
MyOptionQuotes
quote scope (specified in the URL).The
instrumentIdType
field isLusidInstrumentId
.The
instrumentId
field for:The
ExchangeTradedOption
instrument is its LUID.The underlying
Equity
instrument is theunderlyingCode
specified in theExchangeTradedOption
instrument definition, in this caseMyIDForBMWQuotes
.
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 ofQuote.LusidInstrumentId.
and a suffix of*
(wildcard) to find prices keyed by both LUID andunderlyingCode
.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).
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 ExchangeTradedOption
‘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
:
Instrument event type | Event emission criteria | If emitted, effect of LUSID default transaction template | Recommendations for transaction types |
---|---|---|---|
| This event is not automatically emitted by LUSID. Providing the | One transaction is automatically generated with the realised gain. | More information coming soon |
| This event is not automatically emitted by LUSID. Providing the | Two transactions are automatically generated, one for the | |
| This event is automatically emitted by LUSID on the expiry date, but only if | One transaction is automatically generated. |
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.