Modelling equities in LUSID

  • Updated on Apr 15, 2025
  • Published on Aug 23, 2024
Prev Next

You can model an equity as an instrument of type Equity in LUSID. See all supported instruments.

Mastering an instrument

There are numerous tools you can use to master an Equity 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 Equity. For more information on these fields, select Equity from the definition dropdown in the UpsertInstruments API reference:

In this tutorial we’ll master BP PLC $0.25 shares traded in London by calling the UpsertInstruments API as follows:

curl -X POST 'https://<your-domain>.lusid.com/api/api/instruments?scope=MyCustomInstrScope'
   -H 'Content-Type: application/json-patch+json'
   -H 'Authorization: Bearer <your-API-access-token>'
   -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"
    }
  }
}'

Note the following:

Providing the request is successful, the response:

  • Confirms the globally-unique LUID for the instrument.

  • 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_00003EDQ",
      "version": {
        "asAtCreated": "2025-04-15T12:12:35.6248820+00:00",
        "userIdCreated": "00u91lo2d7X42sdse2p7",
        "requestIdCreated": "2025041512-b098190a3157476d9b522604be3e9589",
        "asAtModified": "2025-04-15T12:12:35.6248820+00:00",
        "userIdModified": "00u91lo2d7X42sdse2p7",
        "requestIdModified": "2025041512-b098190a3157476d9b522604be3e9589",
        "asAtVersionNumber": 1,
        "entityUniqueId": "b6000edd-06e1-4842-bba3-8735cacc348c"
      },
      "name": "BP $0.25 LDN",
      "identifiers": {
        "LusidInstrumentId": "LUID_00003EDR",
        "ClientInternal": "bp-plc-ldn",
        "Sedol": "0798059",
        "Isin": "GB0007980591",
        "Figi": "BBG000C05BD1"
      },
      "properties": [],
      "instrumentDefinition": {
        "identifiers": {},
        "domCcy": "GBP",
        "lotSize": 1,
        "instrumentType": "Equity"
      },
      "state": "Active",
      "assetClass": "Equities",
      "domCcy": "GBP",
      "relationships": []
    }
  },
  "staged": {},
  "failed": {},
  ...
}

Booking a transaction to establish a position

Once an instrument is mastered, we can book a transaction to record the acquisition of a quantity in a suitable portfolio, for example by calling the BatchUpsertTransactions API as follows:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/UK/transactions/$batchUpsert?successMode=Partial&preserveProperties=true'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "transactionRequest-1": {
    "transactionId": "equity_purchase_001",
    "type": "BuyEquity",
    "instrumentIdentifiers": {"Instrument/default/LusidInstrumentId": "LUID_00003EDR"},
    "transactionDate": "2025-04-02T00:00:00.0000000+00:00",
    "settlementDate": "2024-04-05T00:00:00.0000000+00:00",
    "units": 10000,
    "transactionPrice": {
      "price": 3.50,
      "type": "Price"
    },
    "totalConsideration": {
      "currency": "GBP",
      "amount": 0
    },
    "properties": {
      "Transaction/MyProperties/TotalCapitalisedFees": {
        "key": "Transaction/MyProperties/TotalCapitalisedFees",
        "value": {
          "metricValue": {
            "value": 1330,
            "unit": "GBP"
          }
        }
      }
    }
  }
}'

Note the following:

  • The instrumentIdentifiers field uses the LUID to resolve the transaction to the correct instrument, but it could use any unique identifier.

  • The type field invokes a BuyEquity transaction type to confer a particular economic impact on the transaction (see below).

  • The units field specifies the purchase amount.

  • The transactionPrice object records the market price (in pounds not pence). This is used by LUSID to automatically calculate gross consideration (see below).

  • The totalConsideration object:

    • Sets the settlement currency to GBP.

    • Specifies a settlement cost of 0 to enable LUSID to automatically derive total consideration (see below).

  • The trade commission is recorded using a custom property.

Note: This example assumes the transaction, settlement and portfolio currencies are all the same. If not, you can specify exchange rates.

We can call the SetTransactionType API to create a BuyEquity transaction type as follows:

curl -X PUT 'https://<your-domain>.lusid.com/api/api/transactionconfiguration/types/default/BuyEquity?scope=default'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "aliases": [
    {
      "type": "BuyEquity",
      "description": "Transaction type for equity purchases",
      "transactionClass": "Basic",
      "transactionRoles": "Longer",
      "isDefault": false
    }
  ],
  "movements": [
    {
      "name": "Increase units of security",
      "movementTypes": "StockMovement",
      "side": "Side1",
      "direction": 1
    },
    {
      "name": "Decrease cash balance by total consideration",
      "movementTypes": "CashCommitment",
      "side": "Side2",
      "direction": -1
    }
  ],
  "calculations": [
    {
      "type": "Txn:GrossConsideration"
    },
    {
      "type": "DeriveTotalConsideration",
      "formula": "Txn:GrossConsideration + Properties[Transaction/MyProperties/TotalCapitalisedFees]"
    }
  ]
}'

Note the following:

  • The Txn:GrossConsideration calculation automatically calculates gross consideration according to the formula price * units, and stores the result in the Transaction/default/GrossConsideration system property.

  • The DeriveTotalConsideration calculation automatically calculates total consideration according to the given, user-defined formula, which in this case sums gross consideration and total fees; this is stored as the totalConsideration.amount of the transaction.

  • The StockMovement uses the built-in Side1 side to update a holding in the instrument with the specified number of units at a cost of the total consideration. See how LUSID calculates holding cost.

  • The CashCommitment movement uses the built-in Side2 to decrease the instrument currency holding by the total consideration.

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 automatically generated by LUSID to audit calculated amounts, for example:

Valuing your position

To value your position, work through our valuation checklist.

Note the only pricing model available to an Equity is SimpleStatic, which calculates PV as holding units * market price.

Monitoring the lifecycle of the instrument

An Equity does not have an expiry or maturity date, so the 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 a 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. You can: