Providing you are a LUSID user with sufficient access control permissions, you can create an instrument to model an equity in the LUSID instrument master. You can then:
Book a transaction in a portfolio to record a purchase of a quantity of that equity, and establish a holding (position)
Value your position at any time
Assess PV and P&L on a regular basis
Book further transactions to change or close your position
Monitor lifecycle events such as cashflows from dividend payments.
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 an instrument
LUSID's instrument model is designed with reference to ISDA CDM and FpML, and equities constitute an integral part of this instrument model.
To create an instrument modelling an equity, call the LUSID UpsertInstruments API and specify a definition with an instrumentType of Equity and a domestic currency. For more information, examine the API documentation and choose Equity 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 an instrument for BP PLC $0.25 shares traded in London:
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": "BP $0.25 LDN",
"identifiers": {
"ClientInternal": {"value": "bp-plc-ldn"},
"Figi": {"value": "BBG000C05BD1"},
"Isin": {"value": "GB0007980591"},
"Sedol": {"value": "0798059"}
},
"definition": {
"instrumentType": "Equity",
"domCcy": "GBP"
}
}
}'Providing the request is valid, the response contains an extra identifier, in this case LUID_00003D5C. This is because LUSID automatically generates a LUSID instrument ID (or LUID) for every instrument that is guaranteed to be unique and never change. You can use this LUID to reference the instrument in subsequent API calls:
{
"values": {
"upsert-request-1": {
"href": "https://<your-domain>.lusid.com/api/api/instruments/LusidInstrumentId/LUID_00003D5C",
"lusidInstrumentId": "LUID_00003D5C",
"version": {
"effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
"asAtDate": "2021-11-23T10:14:07.7454320+00:00"
},
"name": "BP $0.25 LDN",
"identifiers": {
"Figi": "BBG000C05BD1",
"ClientInternal": "bp-plc-ldn",
"LusidInstrumentId": "LUID_00003D5C",
"Sedol": "0798059",
"Isin": "GB0007980591"
},
"properties": [],
"instrumentDefinition": {
"domCcy": "GBP",
"instrumentType": "Equity"
},
"state": "Active",
"assetClass": "Equities",
"domCcy": "GBP"
}
},
...
}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 equity in a particular portfolio:
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": "txn-bp-01",
"type": "Buy",
"instrumentIdentifiers": {
"instrument/default/LusidInstrumentId": "LUID_00003D5C"
},
"transactionDate": "2021-11-15T00:00:00.0000000+00:00",
"settlementDate": "2021-11-16T00:00:00.0000000+00:00",
"units": 10,
"transactionPrice": {
"price": 350,
"type": "Price"
},
"totalConsideration": {
"amount": 3500,
"currency": "GBP"
},
"transactionCurrency": "GBP"
}
]'Note this transaction uses the built-in Buy transaction type, which is tailor-made to represent a stock movement into the portfolio and a cash movement out, but you could define your own custom transaction type to represent equity purchases if you wish.
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_00003D5C'"
-H "Authorization: Bearer <your-API-access-token>"Valuing your position
To value your position, first load suitable market data into LUSID and then create a valuation recipe. For demonstrations of these operations, see sections 4 and 6 respectively of the accompanying Jupyter Notebook.
In your recipe, there's no need to specify a PricingContext object with a pricing model to use. This is because, by default, a LUSID recipe automatically performs a simple calculation of market price * quantity held.
Assessing PV and P&L
You can value your position at any time to calculate P&L from PV and use this information to decide the right time to change or close your position.
In section 6 of the accompanying Jupyter Notebook, you can see the P&L changing between days 1 and 2 as the market price of the equity fluctuates.
Changing your position
You can call the LUSID UpsertTransactions API again to sell a quantity of the equity at any time to reduce your position. The following example shows the use of the built-in Sell transaction type to represent a stock movement out of the portfolio and a cash movement in:
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": "txn-bp-02",
"type": "Sell",
"instrumentIdentifiers": {
"instrument/default/LusidInstrumentId": "LUID_00003D5C"
},
"transactionDate": "2021-11-21T00:00:00.0000000+00:00",
"settlementDate": "2021-11-22T00:00:00.0000000+00:00",
"units": 5,
"transactionPrice": {
"price": 400,
"type": "Price"
},
"totalConsideration": {
"amount": 2000,
"currency": "GBP"
},
"transactionCurrency": "GBP"
}
]'Monitoring the lifecycle of the instrument
The purchase of an equity is not a contract that expires, so an equity instrument does not have a lifecycle in the normal sense.
Typically, you close your position at a time when P&L is favourable to you, though real-world change of control events such as mergers or insolvencies may impact the outcome. You can load your stream of corporate actions into a source and trigger LUSID to emit events that you can then handle appropriately.
LUSID does have tools that enable you to monitor portfolio cashflows that derive from a dividend payment or some other corporate action affecting an equity instrument. You can:
Use the Cash Ladder dashboard in the LUSID web app.
Call the LUSID GetPortfolioCashLadder API directly.
Schedule a job to create a regular report.
For a demonstration, see section 6, Cash Ladder in the accompanying Jupyter Notebook. The corporate action itself, a dividend payment, is defined and booked in section 5.