Assigning transactions to custodian accounts

Consider the example of equity purchase transactions booked into a portfolio with a BuyEquity transaction type that has two movements:

1. A StockMovement that increases the units/cost of a holding in the equity.

2. A CashCommitment that decreases the units/cost of a holding in the instrument currency.

Let’s assume we have created and registered the following four custodian accounts with the portfolio:

Making transaction types custodian-aware

To assign movements to custodian accounts, set the custodianAccountType field to an appropriate account type.

For example, the following call to the SetTransactionType API for BuyEquity sets:

• The StockMovement to Stock so LUSID (can only) resolve stock movements to custodian accounts with a matching account type of Stock

• The CashCommitment to Cash so LUSID (can only) resolve cash movements to custodian accounts with a matching account type of Cash

{
  "aliases": [
    {
      "type": "BuyEquity",
      "description": "Equity purchases",
      "transactionClass": "Trading",
      "transactionRoles": "LongLonger",
      "isDefault": false
    }
  ],
  "movements": [
    {
      "movementTypes": "StockMovement",
      "side": "Side1",
      "direction": 1,
      "custodianAccountType": "Stock"
    },
    {
      "movementTypes": "CashCommitment",
      "side": "Side2",
      "direction": -1,
      "custodianAccountType": "Cash"
    }
  ]
}

Nominating all custodian accounts explicitly

When booking equity purchase transactions using BuyEquity we have the option to specify a set of custodianEntries explicitly nominating custodian accounts for stock and cash movements.

For example, the following request to the BatchUpsertTransactions API:

• Nominates the JPM-Stock custodian account for stock movements, since its accountType of Stock matches the custodianAccountType of Stock on the StockMovement

• Nominates the JPM-Cash custodian account for cash movements , since its accountType of Cash matches the custodianAccountType of Cash on the CashCommitment

{
  "transactionRequest-1": {
    "transactionId": "Txn-001",
    "type": "BuyEquity",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C6K6G9"},
    "transactionDate": "2026-01-01T00:00:00.0000000+00:00",
    "settlementDate": "2026-01-03T00:00:00.0000000+00:00",
    "units": 200,
    "transactionPrice": {"price": 3, "type": "Price"},
    "totalConsideration": {"amount": 600, "currency": "GBP"},
    "custodianEntries": [
      {
        "accountId": {
          "scope": "CustAccsV2",
          "code": "JPM-Stock"
        }
      },
      {
        "accountId": {
          "scope": "CustAccsV2",
          "code": "JPM-Cash"
        }
      }
    ]
  }
}

We can examine holdings and group by the custodian account SHK to see the resulting stock and cash holdings successfully segregated by custodian account:

LUSID provides a resolution reason for each movement on the output transaction:

Nominating a custodian account just for stock movements

As an alternative, we could nominate just JPM-Stock as the custodian account for stock movements using BuyEquity but omit an explicit nomination for cash movements, for example:

{
  "transactionRequest-1": {
    "transactionId": "Txn-001",
    "type": "BuyEquity",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C6K6G9"},
    "transactionDate": "2026-01-01T00:00:00.0000000+00:00",
    "settlementDate": "2026-01-03T00:00:00.0000000+00:00",
    "units": 200,
    "transactionPrice": {"price": 3, "type": "Price"},
    "totalConsideration": {"amount": 600, "currency": "GBP"},
    "custodianEntries": [
      {
        "accountId": {
          "scope": "CustAccsV2",
          "code": "JPM-Stock"
        }
      }
    ]
  }
}

This time, LUSID resolves cash to the default custodian account for the Cash account type, which in our example is HSBC-Cash:

The resolution reason for the cash movement is now different:

Omitting nominated custodian accounts entirely

If we omit custodianEntries entirely from the request then LUSID falls back to the default custodian accounts for the Stock and Cash account types, which in our example is HSBC-Stock and HSBC-Cash respectively:

The resolution reason for both movements is different again:

Note:  If there were no default custodian accounts for the Stock and Cash account types then all BuyEquity movements would fail to resolve and stock and cash holdings would not be segregated by custodian account.

Handling auto-generated instrument event transactions

LUSID can automatically generate transactions in response to instrument lifecycle or corporate action events impacting certain instruments.

For example, we might load a CashDividendEvent of 20 pence per share for our UK equity into a corporate action source. On the ex-date, LUSID automatically generates a transaction for a dividend amount of 200 units held * £0.20 = £40 and adds it to a GBP cash holding.

By default, auto-generated transactions inherit SHKs and custodian account information from the original holding. While our equity is assigned to the JPM-Stock custodian account, income should typically be directed to a Cash-type custodian account such as JPM-Cash.

To do this, we can create or update the JPM-Stock custodian account to set the CustodianAccount/default/RelatedAccounts system property to a related cash account, for example:

[
  {
    "scope": "CustAccsV2",
    "code": "JPM-Stock",
    "accountType": "Stock"
    "properties": {
      "CustodianAccount/default/RelatedAccounts": {
        "key": "CustodianAccount/default/RelatedAccounts",
        "value": {
          "labelValueSet": {
            "values": ["CustAccsV2/JPM-Cash"]
          }
        }
      }
    },
    ...
  }
]

Then, we can make the DividendIncome transaction type processing CashDividendEvent custodian-aware, for example:

{
  "aliases": [
    {
      "type": "DividendIncome",
      "description": "Transaction type for cash dividend event",
      "transactionClass": "Dividend",
      "transactionRoles": "Longer",
      "isDefault": false
    }
  ],
  "movements": [
    {
      "movementTypes": "CashAccrual",
      "side": "Side1",
      "direction": 1,
      "custodianAccountType": "Cash"
    },
    ...
  ]
}'

Now, LUSID resolves the cash movement to the related JPM-Cash custodian account instead of JPM-Stock, reducing the total negative balance:

The resolution reason is available on the output transaction: