Conversions

Concepts: Conversions in the money lifecycle

A conversion sells an exact amount of one currency you hold for another, between two accounts you already hold, and can end in a sub-client's account (convert into another account of your tree). It is a separate step: convert, read the rate you got, then decide whether to deposit or withdraw the proceeds. No other route converts for you.

A conversion can be fiat to fiat, fiat to crypto, crypto to fiat or crypto to crypto: the route takes any two currencies you hold an active account in.

The route acts as you, never as a sub-client, and refuses x-on-behalf-of with 400 ON_BEHALF_OF_NOT_ALLOWED_HERE.

Convert a balance

POST /conversions · scope trade:execute (plus transfer:execute with toAccountId) · idempotency key required

Replaying a key returns the first result with replayed: true and places no second order. A new key on a retry path places a second order. The full rule is in Conventions.

curl -X POST https://api.threecommabank.com/api/partner/v1/conversions \
  -H "Authorization: Bearer $TCB_API_KEY" \
  -H "Idempotency-Key: acme-conversion-2026-09-02-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "fromCurrency": "USDC",
    "toCurrency": "USD",
    "amount": "1000.00",
    "sourceAccountId": "4d80f3b6-9a17-4c25-8e93-0b6d1f7a3c58",
    "targetAccountId": "1b9d4f07-6c23-4a8e-b510-9f2c7d3e5a68"
  }'

{
  "success": true,
  "data": {
    "conversionId": "6a4d0f38-7c15-42be-9038-4b7e1c6a2d59",
    "status": "SETTLED",
    "idempotencyKey": "acme-conversion-2026-09-02-0001",
    "replayed": false,
    "from": {
      "currency": "USDC",
      "requestedAmount": "1000",
      "filledAmount": "1000",
      "unfilledAmount": "0"
    },
    "to": { "currency": "USD", "amount": "997.30" },
    "rate": {
      "executed": "0.9998",
      "quoted": "0.9999",
      "quotedExpiresAt": "2026-09-02T10:15:58.000Z",
      "pricingModel": "MARKET",
      "note": "This rate came from a venue that prices independently of TCB."
    },
    "commission": { "amount": "2.5", "currency": "USD" },
    "networkFee": null,
    "tradeOrderId": "e5c17a03-9d42-4b68-8f31-0a7c2e6b4d95",
    "toAccountId": null,
    "transferId": null,
    "settledAt": "2026-09-02T10:15:33.000Z",
    "createdAt": "2026-09-02T10:15:28.000Z",
    "disclosure": { "version": "2026-09-06", "summary": "…", "items": ["…"] }
  },
  "timestamp": "2026-09-02T10:15:33.612Z"
}

disclosure is the object printed at the top of this page, abbreviated here. It arrives in full on the wire.

Read the result

rate.executed is the price you actually got. TCB publishes no other rate beside it.

Convert into another account of your tree

Name toAccountId to end the conversion somewhere other than your default account in toCurrency. The key needs transfer:execute as well as trade:execute.

• One of your own accounts. The conversion is credited to it directly, as if you had named it as targetAccountId. Naming a different targetAccountId beside it is refused with 409 CONVERSION_DESTINATION_CONFLICT.
• A sub-client's account. The conversion is credited to your own account in toCurrency (targetAccountId, or your single active one) and the converted amount moves on to the sub-client in the same step that settles the conversion. transferId names that move. The conversion never settles without the move, and the move never posts without the settlement.

The destination must be a fiat account in toCurrency, open, and in your tree: your own, or a sub-client created directly under you. The sub-client must be able to receive. Everything is checked before anything is converted, and a refusal leaves your idempotency key usable:

The conversion is the money call: it counts against your conversion money caps on the sell side, and the sell currency must be yours. A sub-client's account cannot be the source.

If the order fills and the move into the sub-client's account then cannot post, the conversion answers 500 CONVERSION_FAILED_PENDING_COMPENSATION. The converted amount is in your own account in toCurrency, nothing reached the sub-client, and a TCB operator resolves it. Do not re-key it — see the state ladder.

Quote a conversion first

POST /conversions/quote · scope trade:execute (plus transfer:execute with toAccountId) · no idempotency key

Quoting is optional and recommended. A quote prices the conversion you are about to make without making it: the rate a market venue quotes for it, the commission it will be charged at that rate, and what it would credit. Nothing is converted.

The quote takes the same fields as the conversion, except quoteId and idempotencyKey, and runs the same checks before anything is converted: both accounts, your money cap, a real venue quote and the trading risk check. A refusal here is the refusal the conversion would get. A quote reserves nothing: your balance and the risk check are checked again when you convert.

curl -X POST https://api.threecommabank.com/api/partner/v1/conversions/quote \
  -H "Authorization: Bearer $TCB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromCurrency": "USDC",
    "toCurrency": "USD",
    "amount": "1000.00"
  }'

{
  "success": true,
  "data": {
    "quoteId": "5e2c9a17-8b40-4d63-a1f8-3c7e0b9d2f46",
    "from": { "currency": "USDC", "amount": "1000" },
    "toCurrency": "USD",
    "rate": {
      "quoted": "0.9998",
      "pricingModel": "MARKET",
      "note": "This rate came from a venue that prices independently of TCB."
    },
    "commission": { "amount": "2.5", "currency": "USD" },
    "receiveAmount": "997.30",
    "networkFee": null,
    "expiresAt": "2026-10-30T10:15:58.000Z",
    "disclosure": { "version": "2026-10-27", "summary": "…", "items": ["…"] }
  },
  "timestamp": "2026-10-30T10:15:28.402Z"
}

A quoted conversion fills at the quoted rate or better, and is charged at most the quoted commission. It is never filled at a worse rate: if the market has moved against the quote, the conversion is refused instead, with nothing converted.

To execute at the quote, name quoteId on the conversion before expiresAt. The conversion must repeat the quoted request: the same fromCurrency, toCurrency, amount (compared by value, so "1000" matches "1000.00"), sourceAccountId, targetAccountId and toAccountId. A quote executes one conversion, and a conversion that names one is never re-quoted.

A conversion naming a quote is refused, with nothing converted and the idempotency key still usable, when:

• the quote is past expiresAt: 409 QUOTE_EXPIRED
• the quote has already executed a conversion: 409 QUOTE_ALREADY_USED
• the request differs from the quoted one: 409 QUOTE_MISMATCH, with details.fields naming what differs
• the commission terms changed since the quote: 409 QUOTE_TERMS_CHANGED
• the market rate is already below the quoted rate: 409 QUOTE_TERMS_CHANGED, with details.quotedRate and details.availableRate
• there is no conversion quote with that id in your scope: 404 QUOTE_NOT_FOUND

In each case, request a new quote.

The price can also move in the moment between those checks and the fill. The order is then refused before it reaches the venue: nothing is converted or charged, and the answer is 409 QUOTE_TERMS_CHANGED with details.quotedRate, details.availableRate and the conversionId. By then the idempotency key and the quote are both spent, so request a new quote and convert under a new key.

Understand quoting and execution

1. Pre-flight takes a quote from the external venues able to price the pair — never from an internal table — and checks it against your balance and the shared trading risk rules. If no venue returns a usable quote, the request is refused with 503 PRICING_UNAVAILABLE; nothing is converted and your idempotency key stays usable.
2. The order is placed against that quote.
3. If the quote expires before execution, TCB re-quotes once. A usable re-quote is executed against. Anything else fails with 503 CONVERSION_QUOTE_EXPIRED and no order is placed. A stale price is never filled.

A conversion that names a quote skips step 1's fresh quote: it executes against the venue quote its quote holds, and step 3's re-quote never happens. If that quote lapses in the moment between the checks and the order, the conversion fails with 503 CONVERSION_QUOTE_EXPIRED and no order is placed.

The trading risk rules apply to a conversion on this API exactly as to any other order: a shared trading risk check limits order rate, size and daily volume, scoped to your client principal — every sub-account shares one bucket. A refusal is 400 CONVERSION_RISK_REJECTED with details.reasons listing the failed checks. It happens before anything moves, and your idempotency key stays usable.

Follow the state ladder

A conversion walks the same six states as a deposit or a withdrawal. See The money lifecycle. One difference matters to your retry logic: a conversion can report that a failure moved nothing, because the order record is written before any money moves.

Fetch a conversion

GET /conversions/{id} · scope transaction:read

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

curl https://api.threecommabank.com/api/partner/v1/conversions/6a4d0f38-7c15-42be-9038-4b7e1c6a2d59 \
  -H "Authorization: Bearer $TCB_API_KEY"

An id that is not yours, or that belongs to a different flow, answers 404 INTENT_NOT_FOUND. There is no list route. Keep your own ids, or read them off the webhook events.

Money caps

TCB may set ceilings on your account's conversions, per sell currency — the amount you are giving up is what a ceiling bounds. Three kinds exist, all inclusive: maxTicket (one request), daily and monthly (the flow's total over the UTC calendar day or month, counted from acceptance, resetting at 00:00:00Z). They are configured, and told to you, by TCB — no ceiling applies unless one has been set for your account, and there is no API to read or change them. A conversion that would cross one is refused before any venue is asked for a quote with 400 CONVERSION_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, or convert less. Deposits and withdrawals carry their own, separate caps — money caps.

Handle the errors

Nothing has been converted on any 4xx or 503.

The full catalogue is in Errors.

Receive the events

Subscribe at POST /webhooks to conversion.settled and conversion.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