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

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"
                    }
                    }
                    ]'

{
                    "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/system/CustodianAccountUniqueId system property with the parent portfolio.

Note: There are two other system properties storing different information that you can use to register custodian accounts as SHKs instead if you wish: Transaction/system/CustodianAccountName and Transaction/system/CustodianAccountAccountNumber.

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/system/CustodianAccountUniqueId",
        "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 the Transaction/system/CustodianAccountUniqueId SHK 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 (1000) and cost (£4,500) proportionally among all custodian accounts with a holding in the underlying instrument that is greater than zero:

Valuing a portfolio with holdings segregated by custodian account

You can specify the following metrics when valuing a portfolio to retrieve more information about custodian accounts:

• CustodianAccount/CustodianAccountId/Scope

• CustodianAccount/CustodianAccountId/Code

• CustodianAccount/AccountNumber

• CustodianAccount/Status

• CustodianAccount/Name

• CustodianAccount/AccountingMethod

• CustodianAccount/Currency

• CustodianAccount/AccountType

• CustodianAccount/Custodian/displayName

• CustodianAccount/Custodian/description

• CustodianAccount/Custodian/lusidEntityId

For example:

Deleting custodian accounts

You can either:

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

• Hard-delete a custodian account to set the status 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.

curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/custodianaccounts/$delete?deleteMode=Hard'
                    -H 'Content-Type: application/json-patch+json'
                    -H 'Authorization: Bearer <your-API-access-token>'
                    -d '[
                    {
                    "scope": "CustodianAccounts",
                    "code": "HSBC-FIFO"
                    }
                    ]'