Providing you are a LUSID user with sufficient access control permissions, you can create an instrument to model a Contract For Differences (CFD) in the LUSID instrument master. You can then:
Book a transaction in a portfolio to record a purchase of a quantity of the CFD, and establish a holding (position)
Value your position at any time using different models
Examine the exposure of that position in combination with your other holdings
Choose whether or not to automatically close out (that is, realise) P&L on a regular basis
Close the position and book the final cash settlement.
Note: If you are the LUSID domain owner, you are automatically assigned the built-in lusid-administrator role, which has all the permissions necessary to perform the operations in this article.
Note there is an accompanying Jupyter Notebook that demonstrates many of the operations and concepts in this article.
Creating the underlying instrument
Before you can create a CFD instrument, you must first 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 table of reference guides.
Creating a CFD instrument
LUSID's instrument model is designed with reference to ISDA CDM and FpML, and CFDs constitute an integral part of this instrument model.
To create an instrument modelling a CFD, call the LUSID UpsertInstruments API and specify a definition with an instrumentType of ContractForDifference, a start date, a type of either Future or Cash, and an identifier for the separately-mastered underlying instrument.
For more information on constructing a suitable economic definition, examine the API documentation and choose ContractForDifference from the dropdown box:
For example, providing you have a valid API access token, you could run the following command in your LUSID domain to create a CFD instrument for 50 Apple shares (where Apple is separately mastered in LUSID with a LUID of LUID_6OHFNCI7):
curl -X POST "https://<your-domain>.lusid.com/api/api/instruments"
-H "Authorization: Bearer <your-API-access-token>"
-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 of the CFD. 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, 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 currency and the underlyingCcy currency 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 valid, the response contains an automatically-generated LUID (in this case, LUID_00003D5A) for the CFD instrument that is guaranteed to be unique and never change. This LUID is of course different to that of the underlying Apple instrument. You can use LUID_00003D5A to reference the CFD instrument in subsequent API calls:
{
"values": {
"upsert-request-1": {
"href": "https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D5A",
"lusidInstrumentId": "LUID_00003D5A",
"version": {
"effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
"asAtDate": "2021-11-17T10:48:02.8920570+00:00"
},
"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 LUSID 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 is the underlying price of 1 Apple share, and the totalConsideration 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:
curl -X POST "https://<your-domain>.lusid.com/api/api/transactionportfolios/<scope>/<code>/transactions"
-H "Authorization: Bearer <your-API-access-token>"
-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 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.
You can confirm your position at any time by calling the LUSID GetHoldings API with the appropriate LUID:
curl -X GET "https://<your-domain>.lusid.com/api/api/transactionportfolios/<scope>/<code>/holdings?filter=instrumentUid%20eq%20'LUID_00003D5A'"
-H "Authorization: Bearer <your-API-access-token>"Valuing your position
To value your position, you must load suitable market data into LUSID and then create a valuation recipe.
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.
Assessing risk
LUSID supports both analytic and bump and valuation mechanisms for assessing risk; contact Technical Support 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 each 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 for a cash instrument. As demonstrated in section 5.3 of the accompanying Jupyter Notebook, 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.
Note: We can automate this close out process for you by scheduling a daily job in your LUSID environment to book transactions that reset the CFD's cost basis and realise the gain or loss.
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.