--- title: "Modelling CFDs in LUSID" slug: "modelling-cfds-in-lusid" updated: 2025-07-16T09:28:24Z published: 2025-07-16T09:28:24Z canonical: "support.lusid.com/modelling-cfds-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 CFDs in LUSID You can model a [Contract For Difference](https://www.investopedia.com/terms/c/contractfordifferences.asp) (CFD) as an instrument of type `ContractForDifference` in LUSID. [See all supported instruments](/v1/docs/what-instruments-does-lusid-support). Note there is an [accompanying Jupyter Notebook](https://github.com/finbourne/finbourne-notebooks/blob/main/V1/features/instruments/Contract%20for%20Difference.ipynb) that demonstrates many of the operations and concepts in this article. ## Mastering an underlying instrument Before you can create a `ContractForDifference`, you must separately master the underlying instrument if this has not been done already. To see how to do this, choose the appropriate instructions for the underlying asset class from this [this table](/v1/docs/supported-instruments-in-lusid). ## Mastering a `ContractForDifference` instrument There are [numerous tools](/v1/docs/how-do-i-master-an-instrument) you can use to master an `ContractForDifference` 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 `ContractForDifference`. For more information on these fields, select **ContractForDifference** 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(938).png) In this tutorial we’ll master a `ContractForDifference` for 50 Apple shares, where Apple has been separately mastered as an `Equity` with a [LUID](/v1/docs/what-is-a-lusid-instrument-id-or-luid) of `LUID_6OHFNCI7`: ```json curl -X POST "https://.lusid.com/api/api/instruments"   -H "Authorization: Bearer "   -H "Content-Type: application/json"   -d '{"upsert-request-1": {    "name": "CFD for 50 AAPL 2021-11-1",    "identifiers": {      "ClientInternal": {        "value": "CFD-50-AAPL-20211101",        }    },    "definition": {      "instrumentType": "ContractForDifference",      "startDate": "2021-11-01T10:00:00.0000000+00:00",      "contractSize": 50,      "payCcy": "USD",      "underlyingCcy": "USD",      "type": "Cash",      "underlyingIdentifier": "LusidInstrumentId",      "code": "LUID_6OHFNCI7",      "referenceRate": 0    }  } }' ``` Note the following: - The `referenceRate` should be set to the price of the underlying. The gain or loss will then reference changes in the underlying against that price. - If you are using the [mark to market P&L model](/v1/docs/modelling-cfds-in-lusid#managing-pl-on-a-regular-basis), set `referenceRate` to 0 instead (as per this example) and the transaction's total consideration is then the reference for gain or loss. - The `contractSize` determines the leverage applied to the underlying asset. - The `payCcy` and the `underlyingCcy` can be different. - CFDs typically don't expire but you can set a `maturityDate` if you wish. - If you want to explicitly set or maintain a funding leg against your equity position, please see the alternative `EquitySwap` instrument. Providing the request is successful, the response: - Confirms the globally-unique LUID for the instrument, in this case, `LUID_00003D5A`. This is of course different to that of the underlying. - 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": {           "lusidInstrumentId": "LUID_00003D5A",           "name": "CFD for 50 AAPL 2021-11-1",           "identifiers": {               "LusidInstrumentId": "LUID_00003D5A",               "ClientInternal": "CFD-50-AAPL-20211101"           },           "properties": [],           "instrumentDefinition": {               "startDate": "2021-11-01T10:00:00.0000000+00:00",               "maturityDate": "9999-12-31T23:59:59.9999999+00:00",               "code": "LUID_6OHFNCI7",               "contractSize": 50.0,               "payCcy": "USD",               "referenceRate": 0.0,               "type": "Cash",               "underlyingCcy": "USD",               "underlyingIdentifier": "LusidInstrumentId",               "instrumentType": "ContractForDifference"           },           "state": "Active",           "assetClass": "Equities",           "domCcy": "USD"       }   },   ... } ``` ## Booking a transaction to establish a position Once the instrument is mastered, you can call the [UpsertTransactions](https://www.lusid.com/docs/api/#operation/UpsertTransactions) API to purchase a quantity of the CFD in a particular portfolio. As mentioned above, the CFD instrument determines contract size. In the transaction, you specify a number of contracts (units) to buy or sell. In our example, the `transactionPrice.price` is the underlying price of 1 Apple share, and the `totalConsideration.amount` is the units multiplied by price and the instrument's contract size. Note that the margin paid to the broker is typically booked as a separate fee or commission. For example: ```json curl -X POST "https://.lusid.com/api/api/transactionportfolios///transactions"  -H "Authorization: Bearer "  -H "Content-Type: application/json"  -d '[ {       "transactionId": "cfd-appl-buy-01",       "type": "StockIn",       "instrumentIdentifiers": {         "instrument/default/LusidInstrumentId": "LUID_00003D5A"       },       "transactionDate": "2021-11-15T00:00:00.0000000+00:00",       "settlementDate": "2021-11-16T00:00:00.0000000+00:00",       "units": 10,       "transactionPrice": {         "price": 165,         "type": "Price"       },       "totalConsideration": {         "amount": 82500,         "currency": "USD"       }   } ]' ``` Note this transaction uses the built-in `StockIn` [transaction type](/v1/docs/what-is-a-transaction-type) rather than the built-in `Buy`, since there is no cash movement. However, you could define your own custom transaction type to represent CFD purchases if you wish, as demonstrated in section 3 of the [accompanying Jupyter Notebook](https://github.com/finbourne/finbourne-notebooks/blob/main/V1/features/instruments/Contract%20for%20Difference.ipynb). You can confirm your position at any time by calling the [GetHoldings](https://www.lusid.com/docs/api/#operation/GetHoldings) API with the appropriate LUID: ```json curl -X GET "https://.lusid.com/api/api/transactionportfolios///holdings?filter=instrumentUid%20eq%20'LUID_00003D5A'"   -H "Authorization: Bearer " ``` ## Valuing your position To value your position, work through our [valuation checklist](/v1/docs/valuation-checklist). In your recipe, you can choose between two valuation models. Specify: - `ConstantTimeValueOfMoney` to set the PV to the unrealised gain (whether you choose to realise it daily or not). - `Discounting` to achieve the same effect, but taking into account a particular discount curve. For a demonstration of the former, see section 5 of the [accompanying Jupyter Notebook](https://github.com/finbourne/finbourne-notebooks/blob/main/V1/features/instruments/Contract%20for%20Difference.ipynb). ## Assessing risk 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. ## Managing P&L on a regular basis You can choose between two models for managing P&L on a regular basis, for example at or near month end. ### Mark to market model This 'close out' mark to market model realises P&L for a period by booking it as a cash amount and resetting the CFD's cost price to today’s close (so the P&L is now 0). To choose this model, you must: - Set the `referenceRate` to `0` when you create the CFD instrument. - Manually book a transaction in a cash instrument. As demonstrated in section 5.3 of the [accompanying Jupyter Notebook](https://github.com/finbourne/finbourne-notebooks/blob/main/V1/features/instruments/Contract%20for%20Difference.ipynb), from one month in there is a second line item for the Apple CFD representing cumulative cash adjustments. You can record this as a total for the portfolio, for the CFD position itself, or for a particular strategy combination of CFDs. ### Cumulative P&L model This 'non-close out' model maintains P&L as unrealised. To choose this model, set `referenceRate` to the price of the underlying when you create the CFD instrument. You do not need to take any other action. As demonstrated in section 5.3 of the Jupyter Notebook, the Amazon CFD is shown as a single line entry. The **Present Value** column in the valuation tables for Amazon shows the (lifetime) unrealised contract gain. ## Closing your position and booking cash settlements Typically, CFDs don't expire, so there may be no occasion to monitor the final cashflows on a contract. You would normally close the position at a time when P&L is favourable to you. You would then book the final cash transaction to realise either the lifetime contract gain, or the gain since the last time you realised P&L, depending on the model chosen above.