Segregating holdings using custodian accounts

You have the option to set up any number of custodian accounts for a transaction portfolio.

When you load transactions into the portfolio, you can assign them to particular custodian accounts, or alternatively pro-rate across all accounts. You may simply do this in order to record custodian information for transactions, but you can also use custodian accounts to segregate holdings in the portfolio in the same way as sub-holding keys (SHKs).

Advantages of custodian accounts over SHKs may be:

  • LUSID automatically establishes relationships between custodian accounts and legal entities or person entities mastered in LUSID.

  • Custodian accounts are simpler to manage (create, read, update and delete).

  • Custodian accounts have their own tax lot accounting methods, so you can manage liquidation strategies at a more granular level.

Consider the following scenario:

Creating custodian accounts

To create one or more custodian accounts, call the UpsertCustodianAccounts API, specifying the scope and code of the parent portfolio in the URL and, in the body of the request:

  • A scope and code that together uniquely identify the custodian account (the latter must be unique within the former).

  • An accountNumber and meaningful accountName.

  • An accountingMethod if you want to change the Default option (which means no liquidation strategy).

  • A custodianIdentifier referencing either a legal entity or a person entity already mastered in LUSID. This identifier consists of three parts: idTypeScope, idTypeCode and code. More information.

  • The currency of the portfolio. Note this field is informational only and not used by LUSID.

  • An accountType if you want to change the default of Margin. Note this field is informational only and not used by LUSID.

Note: If you have a Luminesce license you can use the Lusid.Portfolio.CustodianAccount.Writer provider.

For example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/custodianaccounts'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '[
  {
    "scope": "CustodianAccounts",
    "code": "HSBC-FIFO",
    "accountNumber": "1234",
    "accountName": "HSBC FIFO",
    "accountingMethod": "FirstInFirstOut",
    "currency": "GBP",
    "custodianIdentifier": {
      "idTypeScope": "InternationalBanks",
      "idTypeCode": "BankId",
      "code": "HSBC"
    }
  }
]'

Providing the request is successful, LUSID creates the custodian account and sets the status to Active:

{
  "custodianAccounts": [
    {
      "custodianAccountId": {
        "scope": "CustodianAccounts",
        "code": "HSBC-FIFO"
      },
      "status": "Active",
      "accountNumber": "1234",
      "accountName": "HSBC FIFO",
      "accountingMethod": "FirstInFirstOut",
      "currency": "GBP",
      "accountType": "Margin"
      "custodian": {
        "displayName": "HSBC",
        "description": "An international bank and investment firm"
        "lusidLegalEntityId": "LUID_00003DAR",
        "identifiers": {
          "LegalEntity/InternationalBanks/BankId": {
            "key": "LegalEntity/InternationalBanks/BankId",
            "value": {
              "labelValue": "HSBC"
            },
            "effectiveFrom": "0001-01-01T00:00:00.0000000+00:00",
            "effectiveUntil": "9999-12-31T23:59:59.9999999+00:00"
          }
        },
        "properties": {},
        "relationships": [],
      }
    }
  ],
  ...
}

Registering custodian accounts in order to segregate holdings

To use custodian accounts as SHKs you must register the Transaction/internal/ReferencedCustodianAccount system property with the parent portfolio.

To do this for a new portfolio, call the CreatePortfolio API and add the system property to the subHoldingKeys collection. For an existing portfolio, call the PatchPortfolioDetails API as follows to append to the collection rather than overwriting existing SHKs:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/details'
 -H 'Authorization: Bearer <your-API-access-token>'
 -H 'Content-Type: application/json-patch+json'
 -d '[
  {
    "value": "Transaction/internal/ReferencedCustodianAccount",
    "path": "/subHoldingKeys/-",
    "op": "add"
  }
]'

Assigning transactions to custodian accounts and examining holdings

To assign a transaction to a particular custodian account, call the BatchUpsertTransactions API and specify the scope and code in the custodianAccountId object, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/transactions/$batchUpsert?successMode=Partial' 
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "transactionRequest-1": {
    "transactionId": "Txn-01",
    "type": "StockIn",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C05BD1"},
    "transactionDate": "2024-11-01T00:00:00.0000000+00:00",
    "settlementDate": "2023-11-03T00:00:00.0000000+00:00",
    "units": 1000,
    "transactionPrice": {"price": 5, "type": "Price"},
    "totalConsideration": {"amount": 5000, "currency": "GBP"},
    "custodianAccountId": {
      "scope": "CustodianAccounts",
      "code": "HSBC-FIFO"
    }
  }
}'

You can call the GetHoldings API and group by custodian account to segregate holdings, for example:

Prorating transactions across all custodian accounts

You can optionally call the BatchUpsertTransactions API and specify the Transaction/default/AllocationMethod=Prorated system property instead of the custodianAccountId object, for example:

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/transactions/$batchUpsert?successMode=Partial' 
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "transactionRequest-1": {
    "transactionId": "Txn-05",
    "type": "StockIn",
    "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000C05BD1"},
    "transactionDate": "2024-11-02T00:00:00.0000000+00:00",
    "settlementDate": "2023-11-04T00:00:00.0000000+00:00",
    "units": 1000,
    "transactionPrice": {"price": 4.5, "type": "Price"},
    "totalConsideration": {"amount": 4500, "currency": "GBP"},
    "properties": {
      "Transaction/default/AllocationMethod": {
        "key": "Transaction/default/AllocationMethod",
        "value": {
          "labelValue": "Prorated"
        }
      }
    }
  }
}'

LUSID distributes the units and cost proportionally among all custodian accounts with a holding in the underlying instrument that is greater than zero:

Deleting custodian accounts

You can call the DeleteCustodianAccounts API and specify either a delete mode of :

  • Soft to set the status of the custodian account to Inactive. It is still returned by the ListCustodianAccounts API.

  • Hard to set the status of the custodian account to Deleted. It is not returned by the ListCustodianAccounts API but is by the GetCustodianAccount API.

You can no longer assign new transactions to a deleted custodian account, but LUSID maintains existing holdings.