Vault deposits & withdrawals

Concepts: Intents and the money lifecycle

A deposit turns fiat you hold at TCB into a position in the curated vault for that currency. A withdrawal redeems part of that position back into one of your fiat accounts. Both are synchronous: the response is the outcome.

Both routes act as you, never as a sub-client. They refuse x-on-behalf-of with 400 ON_BEHALF_OF_NOT_ALLOWED_HERE.

Each call runs the whole tokenised deposit chain at once: a deposit mints tcbUSD from your fiat and puts it into the vault, and a withdrawal reverses both. To run one step at a time — to hold tcbUSD between them, or to queue a redemption the vault cannot pay right now — use Tokenised deposits, step by step. These two calls are unchanged by it.

Follow the state ladder

Both flows walk the same six states. GET /deposits/{id} and GET /withdrawals/{id} report the current one.

The full ladder, including which webhook fires on each terminal transition, is in The money lifecycle.

Deposit fiat into a vault

POST /deposits · scope vault:deposit · idempotency key required

Debits your fiat account, mints the vault's underlying and deposits it into the active vault for that currency, holding the shares in the wallet TCB custodies for you. Your first deposit creates that wallet before anything is charged.

subAccountId enters the idempotency fingerprint only when you state it, so a key issued before you started naming sub-accounts still replays unchanged.

curl -X POST https://api.threecommabank.com/api/partner/v1/deposits \
  -H "Authorization: Bearer $TCB_API_KEY" \
  -H "Idempotency-Key: acme-deposit-2026-09-02-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": "1000.00",
    "sourceAccountId": "1b9d4f07-6c23-4a8e-b510-9f2c7d3e5a68",
    "subAccountId": "5d3b8e10-2f47-4c9a-b6e8-0a71d4c2f395"
  }'

{
  "success": true,
  "data": {
    "depositId": "2f6c9a41-3e58-4b70-9d12-6a8f0c3e5b71",
    "status": "SETTLED",
    "idempotencyKey": "acme-deposit-2026-09-02-0001",
    "replayed": false,
    "currency": "USD",
    "amount": "1000",
    "vault": {
      "address": "0x7a2fD3c8e91B4A5d06E7c1F2b38A9d4C5e6f0B12",
      "chain": "ARBITRUM"
    },
    "custody": {
      "mode": "TCB_SUBACCOUNT",
      "walletAddress": "0x3B9aC4f27D18E056b1C4a9F30d2E85c7A6b1F094"
    },
    "shares": { "balance": "1024.518330000000000000000000", "minted": "1024.518330000000000000000000" },
    "onchain": {
      "depositTxHash": "0x4a1f9c07d3b28e615a0c47f8d29b3e6c15087af2d94b6c308e17b5d02fa4c396",
      "mintTxHash": "0x9d20b7e548c1f36a0742e9bd35c108af62d497130ba85e6c2f9d40718ac35be2"
    },
    "settledAt": "2026-09-02T10:15:34.000Z",
    "createdAt": "2026-09-02T10:15:28.000Z",
    "disclosure": { "version": "2026-09-06", "summary": "…", "items": ["…"] }
  },
  "timestamp": "2026-09-02T10:15:34.271Z"
}

Every response on this page carries the same disclosure object printed at the top of this page. It is abbreviated in the examples.

Read three fields carefully:

• amount is normalised, not echoed. A submitted "1000.00" comes back as "1000".
• shares.balance is the sub-account's whole share balance after this deposit, as a decimal string at the vault's own share scale. It is null when the balance could not be read. A settled deposit is never failed over an unavailable read, so retry the fetch, not the deposit. There is no per-deposit minted-shares figure.
• custody.mode is TCB_SUBACCOUNT: TCB holds the shares for you, in the TCB wallet assigned to you. You hold no keys; the sub-account's shares are a book entry against what that wallet holds.

Withdraw fiat from a vault

POST /withdrawals · scope vault:withdraw · idempotency key required

Redeems shares back into fiat and credits one of your accounts. You ask for an amount of fiat, the same way you deposit one. You never name a number of shares.

What you can withdraw

A withdrawal is authorised against the named sub-account alone:

available = settled − reserved

• settled — what the sub-account holds, as recorded on your ledger.
• reserved — shares held against your own withdrawals that are still in flight from that sub-account.
• available — what a new withdrawal may take. It is the only figure checked. A balance you hold in another sub-account is not available here.

The check, the claim on your idempotency key and the reserve are one atomic step, so two concurrent withdrawals can never spend the same shares. The reserve is released when the withdrawal settles. A withdrawal that ends compensable keeps its reserve held until TCB resolves it, and nothing releases a reserve because time passed. Read all three figures on GET /positions.

curl -X POST https://api.threecommabank.com/api/partner/v1/withdrawals \
  -H "Authorization: Bearer $TCB_API_KEY" \
  -H "Idempotency-Key: acme-withdrawal-2026-09-02-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "amount": "250.00",
    "destinationAccountId": "1b9d4f07-6c23-4a8e-b510-9f2c7d3e5a68",
    "subAccountId": "5d3b8e10-2f47-4c9a-b6e8-0a71d4c2f395"
  }'

{
  "success": true,
  "data": {
    "withdrawalId": "8c1e7b25-4a93-4f06-b83d-51a0d7c46e29",
    "status": "SETTLED",
    "idempotencyKey": "acme-withdrawal-2026-09-02-0001",
    "replayed": false,
    "currency": "USD",
    "amount": "250",
    "settledAmount": "250",
    "precisionResidue": "0.004821",
    "vault": {
      "address": "0x7a2fD3c8e91B4A5d06E7c1F2b38A9d4C5e6f0B12",
      "chain": "ARBITRUM"
    },
    "custody": {
      "mode": "TCB_SUBACCOUNT",
      "walletAddress": "0x3B9aC4f27D18E056b1C4a9F30d2E85c7A6b1F094"
    },
    "shares": { "balance": "774.518330000000000000000000" },
    "onchain": {
      "withdrawTxHash": "0x6c58e2af017d94b3182fa0e7c53d69b148027ea5f31c8d60947b25e0fa1c3d78",
      "burnTxHash": "0xb31d0f6a29c85e470132d9af6058c7be24913f5d7ea0c86241b09fd35c7a1e64"
    },
    "settledAt": "2026-09-02T10:15:41.000Z",
    "createdAt": "2026-09-02T10:15:28.000Z",
    "disclosure": { "version": "2026-09-06", "summary": "…", "items": ["…"] }
  },
  "timestamp": "2026-09-02T10:15:41.336Z"
}

Three fields have no deposit counterpart. All three describe one fact: what you asked for and what settles can differ by the rounding to the currency's own precision.

shares.balance is the sub-account's remaining share balance, at the vault's own share scale, or null when the read was unavailable. There is no per-withdrawal burned-shares figure.

Fetch a deposit or a withdrawal

GET /deposits/{id} and GET /withdrawals/{id} · scope transaction:read

Each returns the object in its current state, including a terminal failure, which is reported as the object rather than as an error. A settled object answers with the same body the original POST returned. It is the poll surface the compensable errors point at, and the fetch half of the thin webhook payloads.

curl https://api.threecommabank.com/api/partner/v1/deposits/2f6c9a41-3e58-4b70-9d12-6a8f0c3e5b71 \
  -H "Authorization: Bearer $TCB_API_KEY"

An id that is not yours, or that belongs to a different flow, answers 404 INTENT_NOT_FOUND.

List your deposits and withdrawals

GET /deposits and GET /withdrawals · scope transaction:read

Both return your vault deposits or withdrawals, newest first, one page at a time.

curl -G https://api.threecommabank.com/api/partner/v1/withdrawals \
  -H "Authorization: Bearer $TCB_API_KEY" \
  --data-urlencode "limit=25"

{
  "success": true,
  "data": {
    "items": [
      {
        "withdrawalId": "7a1d0c55-91e2-4f36-8b0a-2e64c9d8f173",
        "status": "COMPLETED",
        "subAccountId": "5d3b8e10-2f47-4c9a-b6e8-0a71d4c2f395",
        "currency": "USD",
        "requestedAmount": "250",
        "creditedAmount": "249.99",
        "shares": "249.380000000000000000000000",
        "estimatedAvailableAt": null,
        "createdAt": "2026-10-06T10:02:05.000Z",
        "settledAt": "2026-10-06T10:02:13.000Z"
      }
    ],
    "nextCursor": null
  },
  "timestamp": "2026-10-06T10:05:00.000Z"
}

A deposit row carries depositId, status, subAccountId, currency, requestedAmount, shares, createdAt and settledAt. A withdrawal row adds:

shares is the vault shares the movement received or redeemed, at the vault's own share scale. On a deposit it is null unless the deposit is COMPLETED. A deposit's own response and GET /deposits/{id} carry the same figure as shares.minted. Reading it needs the vault's share scale, so on rare occasions these reads answer 503 CHAIN_UNAVAILABLE; retry. On a withdrawal it is null until the vault leg is done.

A malformed cursor is refused with 400 INVALID_AMOUNT. A well-formed cursor that matches none of your rows returns an empty page.

Statuses

Every list row uses the one savings status set that TCB uses on every surface. It is a summary of the state ladder above.

COMPLETED, FAILED, REFUNDED and CANCELLED are final.

Money caps

TCB may set ceilings on your account's money movement, per currency and per flow — deposits and withdrawals are capped independently, and conversions carry their own. Four kinds of ceiling exist, every one inclusive:

No ceiling applies unless TCB has configured one for your account; TCB tells you your ceilings when they are set, and there is no API to read or change them. A request that would cross one is refused before anything moves with 400 DEPOSIT_CAP_EXCEEDED or 400 WITHDRAWAL_CAP_EXCEEDED: details.cap names the ceiling, details.limit its value, and details.attempted what the figure would have become. The idempotency key stays usable — resubmit the same key when the window rolls over, after withdrawals settle, or with a smaller amount.

The daily and monthly figures count your requests as soon as they are accepted, including requests still in flight; only a request that terminally failed with nothing moved stops counting.

Handle the errors

Nothing has been charged or withdrawn on any 4xx, or on a 503.

The full catalogue is in Errors.

Receive the events

Subscribe at POST /webhooks to deposit.settled, deposit.failed, withdrawal.settled and withdrawal.failed. A compensable outcome fires no event — see which webhook fires when.

The machine-readable specification for these endpoints is openapi.partner.v1.json. Where it and this page disagree, the specification is authoritative.

Pilot disclosure