How it works
The object model behind a position: you, your sub-clients, their accounts, and the vault sub-accounts your position is partitioned into.
The object model
Your API key authenticates as one principal, and that principal is the root of everything you can reach. Two separate structures sit below it.
| Structure | Holds | What it is made of |
|---|---|---|
| The account tree | Fiat | Accounts owned by you, or by an end customer you register. An account can carry an IBAN. |
| The vault ledger | Your vault position | Shares held in one wallet TCB custodies for you, partitioned into named sub-accounts for your own reporting. |
Keep the two apart when you read the rest of this page: an account holds fiat, a vault sub-account holds shares. In the diagram below, blue holds fiat, gold holds shares, and the blue lines are money moving between them.
The objects
| Object | What it is | Created / read by |
|---|---|---|
| Client | You. The principal your key authenticates as, and the root of your tree. | GET /me |
| Sub-client | One of your end customers, registered with TCB under your root. Each sub-client holds its own account with TCB, in its own name. You collect the identity information and TCB accepts it. You instruct on the sub-client's behalf. | POST /sub-clients, GET /sub-clients |
| Verification level | Which onboarding model TCB granted you for your sub-clients, and therefore what a sub-client may do once it is verified. | GET /sub-clients/{id} |
| Account | An account holding one currency — fiat, or a crypto asset — belonging to you or to one sub-client. | POST /accounts, GET /accounts |
| MAIN / SUB | An account's role. One account per owner per currency, the MAIN; SUB is retired. To hold the same currency separately, open another account. | POST /accounts |
| IBAN | The payment coordinate on an account, carrying the owner's verified legal name as the payee name. It is inactive until its owner is verified. | POST /accounts/{id}/iban |
| Vault sub-account | A named partition of your own vault position, used to attribute shares to your own funds, strategies or products. | POST /sub-accounts, GET /sub-accounts |
| Position | What a sub-account holds in a vault: settled, reserved and available shares. | GET /positions |
| Vault | The contract your shares live in — one per currency. | Named on every money response |
| Transfer | An instant move of fiat between two accounts inside your tree. | POST /transfers, GET /transfers |
Sub-client, account and vault sub-account
The three names are similar. The objects are not.
| Sub-client | Account | Vault sub-account | |
|---|---|---|---|
| Holds | An identity | Fiat or a crypto asset, one per account | Vault shares |
| Belongs to | You | You or a sub-client | You, always |
| Whose name is on it | Your end customer's, as the payee name on its IBANs | The owner's | Yours |
| Has an IBAN | No — its accounts do | Optionally | Never |
| Identified by | subClientId | accountId | subAccountId |
| Your own label for it | externalRef | externalRef | externalRef |
| Used to | Hold money attributable to an end customer | Send, receive and hold fiat or a crypto asset | Attribute a slice of your own position |
Registering a sub-client opens accounts for your end customer. Each sub-client holds its own account with TCB, in its own name. You collect the identity information and TCB accepts it. You instruct on the sub-client's behalf. Creating a vault sub-account attributes a slice of your own position to a fund, a strategy or a product of yours. A vault sub-account that stands for one of your end customers must be linked to a registered sub-client; how that link is expressed in the API is being finalised.
Use either, or both. A client that never registers a sub-client can still partition its own position by fund, strategy or product.
If you have seen TCB describe client-money accounts, that is what these two objects are: the sub-client is the end customer whose money it is, and the accounts under it are where that money sits. The API uses the word sub-client everywhere — in every route, field and webhook name — so read it that way.
externalRef and the tcb: namespace
Sub-clients, accounts and vault sub-accounts each take an externalRef: your
own identifier, unique within your tree, that you can look the object up by
later. Anything starting with tcb: is reserved and refused. TCB uses that
namespace for the objects it provisions for you, and there is exactly one
today.
tcb:default is the vault sub-account every client holds from the moment
the relationship exists. A deposit, withdrawal or conversion that names no
subAccountId lands there. You never have to create it and you cannot delete
it.
Shares, position and accrual
A deposit converts fiat into shares of a vault. Three rules govern what happens next.
- Your shares sit in one wallet TCB custodies for you, not one per sub-account and not one per sub-client. A vault sub-account is a book entry recording which slice of that wallet you attribute to which fund, strategy or product.
- The share count does not change. Nothing is credited, compounded or swept on a schedule.
- The share price rises as yield accrues. The same share count is worth more each time you read it. That is what accrual means on this API.
A position has three figures per sub-account, and the arithmetic between them is fixed.
| Figure | Meaning |
|---|---|
settledShares | What the sub-account holds. The sum of its posted ledger entries. |
reservedShares | Shares held back against a withdrawal that is in flight from this sub-account. |
availableShares | settledShares minus reservedShares — what you can withdraw right now. |
Your totals are the sum of the sub-accounts, never a separately stored
number, so a total and its decomposition cannot disagree. GET /positions
publishes walletShares alongside them. totals.settledShares is your
entitlement; walletShares is the holding it is against. They are different
facts, so the API states both.
| Field | What it is | When to use it |
|---|---|---|
totals.settledShares | Your entitlement — the sum of your sub-accounts' posted ledger entries. | Your own book: what you attribute to each fund, strategy or product, and what you report. |
totals.walletShares | The holding — the share balance of the wallet TCB custodies for you, read from the vault. | Checking your book against the chain. While a deposit or withdrawal is in flight the two legitimately differ, so a difference is not by itself an error. |
Amounts are decimal strings
Every amount on this API is a decimal string, and there is no decimals field
anywhere. Parse them with a decimal library, not a float. The scales, including
the vault's own share scale, are in
Conventions.
Where the money can go
| From | To | How |
|---|---|---|
| Your fiat account | A vault position | POST /deposits |
| A vault position | Your fiat account | POST /withdrawals |
| One currency you hold | Another currency | POST /conversions |
| One account in your tree | Another account in your tree | POST /transfers |
| An external wallet | An account you control | An on-chain transfer to the address POST /crypto-deposit-addresses issues you |
| An account you control | A registered destination | POST /payouts — a bank destination today |
The guides cover all six. The states the first four pass through, and what to do at each one, are in The money lifecycle; a crypto deposit's states are in its own guide, and a payout's are in Payouts and its own lifecycle ladder.
The money lifecycle
States, webhooks, reserves, freezes and compensation.
Glossary
Every term these pages use, defined once.