Concepts
Glossary
Every term these pages use, defined once, in alphabetical order.
| Term | Definition |
|---|---|
| Accrual | The growth in what your position is worth. Your share count does not change; the vault's share price rises, so the same shares are worth more each time you read them. No scheduled job credits it. |
| Account | An account holding one currency — fiat, or a crypto asset such as USDC — belonging to you or to one of your sub-clients. It has a balance, an IBAN, and a role (MAIN). An owner holds one account per currency: to hold the same currency separately, open another account. POST /accounts opens fiat ones; a crypto one is opened for you when you issue a deposit address. Not to be confused with a vault sub-account. |
| Available | settledShares minus reservedShares on a vault sub-account: what you can withdraw from it right now. For tcbUSD, held minus reserved: what a tcbUSD redemption or a vault subscription can draw on. |
| Client | You — the institution integrating against this API, and the root of your tree. |
| Compensation | The resolution of an intent that ended FAILED_PENDING_COMPENSATION. TCB establishes what happened and closes the record forward — automatically where the outcome can be proven, by an operator otherwise; the state then reads COMPENSATED. Nothing resolves one merely because time passed. |
| Decimal string | How every amount crosses this API: "1000.50", not 1000.5. Never a JSON number, never base units, never exponential notation. Parse with a decimal library. The one exception is the share figures on a statement, which are integer base units, still as strings. |
| Destination | A third party a payout can name: a bank account or a wallet you registered in advance, together with its payee. It must clear screening, TCB approval and a holding period before it is usable, and no call pays an unregistered one. Not to be confused with destinationAccountId on a withdrawal or transfer, which names an account inside your own tree. |
| Envelope | The wrapper around every 2xx body: success, data, timestamp. Your payload is always under data. Errors are shaped differently — see Errors. |
externalRef | Your own identifier for a sub-client, an account or a vault sub-account. Unique within your tree, chosen by you, and returned on reads so you can match TCB's objects to your own. The tcb: prefix is reserved. |
| Holding period | The window every destination serves after TCB approves it, before it becomes usable — 24 hours by default, never less than four. The clock starts at approval, and nothing shortens it for an API-registered destination. |
| IBAN | The payment coordinate issued against an account, carrying the account owner's verified legal name as the payee name, presented for payee-name checks where the receiving scheme runs them. It is inactive (active: false) and accepts no funds until its owner is verified. |
| Idempotency key | A string you choose, 1–100 characters from letters, digits and . _ : -, sent as the Idempotency-Key header. It claims exactly one money movement. Resending it replays the first result rather than moving money again. |
| Intent | The durable record of one money call — a deposit, a withdrawal, a conversion, a payout or one step of the tokenised deposit chain — carrying its state, its amounts and its receipts. One idempotency key claims one intent. |
| MAIN | An account role. The owner's account in a currency; it cannot be closed while the owner exists. |
| Omnibus | The single TCB wallet assigned to you, which holds your whole vault position and any tcbUSD you hold. Your sub-accounts partition it on the book; they do not each get a wallet. |
| On-behalf-of | The x-on-behalf-of header. Naming one of your sub-clients on a route that accepts it executes the request as that sub-client, against its own accounts and rows. See Authentication. |
| Owner | Whoever an account belongs to: you, or one of your sub-clients. ownerType on an account response is CLIENT or SUB_CLIENT. |
| Payout | A payment from one of your fiat accounts to a registered destination. See Payouts. |
| Position | What a sub-account holds in a vault, expressed as settled, reserved and available shares, and valued by the vault's own share price. |
| Principal | The identity a request executes as. Normally you; a sub-client when you send x-on-behalf-of. GET /me reports which. |
| Queued redemption | A vault redemption that waits in the vault's queue instead of being paid at once, for when the vault cannot pay the amount right now. The shares are held in the queue; the vault pays the request no earlier than its claimableAt, possibly in parts, and each part is booked to the sub-account as tcbUSD. You can cancel what has not been paid. See the queue. |
| Rail freeze | A stop TCB places after reconciliation finds a divergence it cannot explain: deposits and withdrawals in that vault, and every payout from your principal, are refused while it is open. Surfaces as 409 PARTNER_RAIL_FROZEN. Only a person lifts one. |
| Reserved | Shares or tcbUSD held back on a sub-account because a movement from it is in flight — a withdrawal, a vault redemption, a tcbUSD redemption or a vault subscription — so two movements can never spend the same holding. Released when that movement settles or is resolved, and by nothing else; never because time passed. |
| Scope | One permission on an API key, written resource:action — vault:deposit, sub-client:read. A route requires exactly one; a key without it gets 403 INSUFFICIENT_SCOPE. |
| Settled | Of an intent: it completed and the money is where you asked. Of a position: shares actually posted to a sub-account's ledger. |
| Share | A unit of a vault. Deposits buy them, withdrawals sell them, and their price rises as yield accrues. Share amounts are decimal strings at the vault's own scale, except on a statement, which prints them as integers in the share token's base units. |
| SUB | A retired account role: an extra account beside the MAIN in the same currency. POST /accounts no longer opens one; existing ones are folded into the MAIN. |
| Sub-account | Short for vault sub-account: a named partition of your own vault position, used to attribute shares — and tcbUSD held between the steps of the tokenised deposit chain — to your own funds, strategies or products. It confers no wallet, no key and no change of custody: its shares and tcbUSD are book entries against the one TCB wallet assigned to you, and it can spend only what is booked to it. A partition that stands for one of your end customers must be linked to a registered sub-client. |
| 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. TCB also runs its own screening on it. It holds no credential of its own. |
| Subscription (vault) | Putting tcbUSD booked to a sub-account into the currency's vault, in exchange for shares booked to the same sub-account: POST /share-subscriptions. A vault deposit does this as its second half. |
tcb:default | The vault sub-account every client has from day one. Money calls that name no subAccountId land there. It cannot be created or deleted by you. |
tcb: namespace | Reserved. An externalRef starting with tcb: is refused, because TCB uses that prefix for objects it provisions for you. |
| tcbUSD | The token a mint creates from US dollars you hold at TCB — the same amount of tcbUSD as the fiat it debits — and the asset the USD vault takes in and pays out. It is held in the TCB wallet assigned to you and booked to a sub-account; you move it only through the chain steps. tcbUSD earns nothing on its own: only vault shares carry the yield. |
| Tree | Your root principal and everything under it — your sub-clients and every account they and you own. Within-tree transfers move money inside it; nothing crosses out of it. |
| Vault | The contract your shares live in, one per currency. Named by address and chain on every money and position response. |
| Verification level | Which onboarding model TCB granted you for your sub-clients, and therefore who performs the due diligence behind one. It determines what a sub-client may do — whether it may receive money, be debited by a within-tree transfer, and so on. Granted per client account at your own onboarding. |
How it works
How these objects fit together.
The money lifecycle
States, reserves, compensation and freezes in full.