Convert one currency you hold into another
Sells an exact amount of fromCurrency for toCurrency between two accounts you already hold, executed by TCB's trading pipeline. It is a stage in its own right, not something the deposit or withdrawal endpoints do for you: convert first, read the rate you got, then deposit or withdraw. An idempotency key is MANDATORY: send it as the Idempotency-Key header or as the idempotencyKey body field. Replaying a key returns the original result without re-executing; reusing one with different parameters is rejected with IDEMPOTENCY_KEY_REUSED. The rate comes only from an external venue that prices independently of TCB. When no such venue can price the pair, the request is refused with 503 PRICING_UNAVAILABLE and nothing is converted — TCB never prices a conversion from an internal table instead. READ rate.pricingModel ON EVERY RESPONSE: MARKET means a venue quoted it; any other value (SIMULATED appears only on conversions settled before 2026-09-06) is not a market rate and must never be presented or reported as one. Every response also carries the pilot disclosure. Converting into a currency and straight back out is priced twice. 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. Name toAccountId to end the conversion in another account of your tree: one of your own fiat accounts in toCurrency, or a sub-client's. Into a sub-client's account the converted amount lands in your own account first and moves on in the same step that settles the conversion; transferId names that move. A key naming toAccountId needs transfer:execute as well as trade:execute. To see the rate and the commission before you convert, quote the conversion first (POST /conversions/quote) and name the quoteId here: the conversion then executes at that quote and is never re-quoted. Every response states the commission charged (commission) and networkFee, which is always null: TCB covers any network cost.
Sells an exact amount of fromCurrency for toCurrency between two accounts you already hold, executed by TCB's trading pipeline. It is a stage in its own right, not something the deposit or withdrawal endpoints do for you: convert first, read the rate you got, then deposit or withdraw. An idempotency key is MANDATORY: send it as the Idempotency-Key header or as the idempotencyKey body field. Replaying a key returns the original result without re-executing; reusing one with different parameters is rejected with IDEMPOTENCY_KEY_REUSED. The rate comes only from an external venue that prices independently of TCB. When no such venue can price the pair, the request is refused with 503 PRICING_UNAVAILABLE and nothing is converted — TCB never prices a conversion from an internal table instead. READ rate.pricingModel ON EVERY RESPONSE: MARKET means a venue quoted it; any other value (SIMULATED appears only on conversions settled before 2026-09-06) is not a market rate and must never be presented or reported as one. Every response also carries the pilot disclosure. Converting into a currency and straight back out is priced twice. 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. Name toAccountId to end the conversion in another account of your tree: one of your own fiat accounts in toCurrency, or a sub-client's. Into a sub-client's account the converted amount lands in your own account first and moves on in the same step that settles the conversion; transferId names that move. A key naming toAccountId needs transfer:execute as well as trade:execute. To see the rate and the commission before you convert, quote the conversion first (POST /conversions/quote) and name the quoteId here: the conversion then executes at that quote and is never re-quoted. Every response states the commission charged (commission) and networkFee, which is always null: TCB covers any network cost.
Authorization
bearer In: header
Header Parameters
Your own key for this request, 1-100 characters. Required, here or as the idempotencyKey body field; sending both is allowed only if they match. Replaying a key returns the first result without executing anything a second time, and sets replayed to true where the response carries that field. Sending the same key with different parameters is refused with 409 IDEMPOTENCY_KEY_REUSED — use a new key for a different request. While the first call is still running, a second call with the same key answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS. The key is remembered permanently: it is recorded against the movement it created, so a replay years later still resolves to that one movement.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
The currency pair and the exact amount to sell, plus the accounts to debit and credit.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/partner/v1/conversions" \ -H "Content-Type: application/json" \ -d '{ "amount": "1000.00", "fromCurrency": "USDC", "idempotencyKey": "acme-conversion-2026-08-31-0001", "quoteId": "5e2c9a17-8b40-4d63-a1f8-3c7e0b9d2f46", "sourceAccountId": "4d80f3b6-9a17-4c25-8e93-0b6d1f7a3c58", "targetAccountId": "1b9d4f07-6c23-4a8e-b510-9f2c7d3e5a68", "toAccountId": "9c3e5a1f-2b7d-4e60-8a94-6f1d0c2b7e35", "toCurrency": "USD" }'{ "data": { "commission": { "amount": "2.5", "currency": "USD" }, "conversionId": "6a4d0f38-7c15-42be-9038-4b7e1c6a2d59", "createdAt": "2026-09-02T10:15:28.000Z", "disclosure": { "items": [ "ENVIRONMENT_IS_TESTNET: The environment is a testnet (Arbitrum Sepolia). No mainnet deployment exists.", "YIELD_IS_SIMULATED: The vault rate is set administratively and the interest it produces is minted as fresh underlying, not earned. It does not represent a return generated by deployed capital.", "FIAT_RAILS_ARE_MOCKED: No real fiat movement occurs. Balances are ledger entries against a sandbox provider.", "CONVERSION_RATES_ARE_MARKET_QUOTED_OR_REFUSED: A conversion is priced only by an external venue that quotes independently of TCB. When no such venue can price the pair, the conversion is refused rather than priced from an internal table. Read rate.pricingModel on every conversion: MARKET is a venue quote; any other value is not a market rate and must not be presented as one.", "CONTRACTS_ARE_UNAUDITED: No audit has been performed. Mainnet is gated on a two-firm audit that has not been commissioned.", "CUSTODY_IS_TCB_SUBACCOUNT: Everything held for the client — its vault shares, and the tcbUSD it holds between the steps of the tokenised deposit chain — is held in TCB custody, in the one TCB wallet assigned to the client. The client holds no keys and moves those tokens only through this API; each sub-account's shares and tcbUSD are book entries against what that wallet holds.", "INTEGRATION_AGREEMENT_ONLY: Fees as published on the rate card; no yield share, no return commitment." ], "summary": "This is a pilot integration on a testnet. Nothing in this system earns anything: the yield is simulated and the fiat rails are mocked.", "version": "2026-10-27" }, "from": { "currency": "USDC", "filledAmount": "1000", "requestedAmount": "1000", "unfilledAmount": "0" }, "idempotencyKey": "acme-conversion-2026-08-31-0001", "networkFee": null, "rate": { "executed": "0.9998", "note": "This rate came from a venue that prices independently of TCB.", "pricingModel": "MARKET", "quoted": "0.9999", "quotedExpiresAt": "2026-09-02T10:15:58.000Z" }, "replayed": false, "settledAt": "2026-09-02T10:15:33.000Z", "status": "SETTLED", "to": { "amount": "999.80", "currency": "USD" }, "toAccountId": "9c3e5a1f-2b7d-4e60-8a94-6f1d0c2b7e35", "tradeOrderId": "e5c17a03-9d42-4b68-8f31-0a7c2e6b4d95", "transferId": "2f8b6d14-7a3c-4e91-b5d0-8c1e4f7a9b26" }, "success": true, "timestamp": "2026-09-02T10:15:30.000Z"}Fetch one crypto deposit by id GET
The deposit in its current state, including a FAILED record, which is reported as the object rather than as an error. This is the fetch half of the thin crypto_deposit.credited webhook payload. The id is stable across replays of the same on-chain transfer.
Quote a conversion before making it POST
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 and no idempotency key is needed. The request is checked exactly as the conversion would be (both accounts, your money cap, the trading risk check), so a refusal here is the refusal the conversion would get. The quote holds until expiresAt: the venue's own quote window, and never more than 60 seconds. Name its quoteId on POST /conversions to execute at this quote: the conversion must repeat the quoted request and can use the quote once, and it is never re-quoted. Quoting first is optional and recommended: it is how you see the rate and the commission before you commit. A quote reserves nothing: your balance and the risk check are checked again when you convert. Like every conversion rate, the quoted one comes only from a venue that prices independently of TCB (rate.pricingModel MARKET).