Endpoints
The
read scope covers reads and POST /v3/fx/quotes, which prices a trade without changing anything. The write scope covers every other change, payments endpoints included. Selecting Write when you create a key grants both read and write access; selecting Read grants read access only. See Authentication for the permission rules. A key without the scope a call needs returns 403 AUTH_INSUFFICIENT_SCOPE.
Request headers
Response headers
Always set, every response (success and error):
Sometimes set:
Resource IDs
All resource IDs are readable, typed-prefix strings: a lowercase 3-to-6-letter resource-type prefix plus a Base58 encoding of the underlying UUID. Bare UUIDs never appear in a v3 response body. Server-generated, permanent, safe to store and index.- Example:
tde_5W7guYdHT24JFnRQrZN9y8 - Regex:
^[a-z]{3,6}_[1-9A-HJ-NP-Za-km-z]{1,22}$, a loose pre-filter. The authoritative check is a successful decode to 16 bytes, and payments operations also pin each ID’s prefix and a 21-to-22-character body.
Status enums
- Quotes terminate at EXPIRED or CONSUMED.
- Trades terminate at EXECUTED or REVERSED.
- Deposits terminate at COMPLETED, REJECTED, or ERROR.
- Withdrawals terminate at COMPLETED or CANCELLED.
- Payouts terminate at RETURNED, FAILED, CANCELLED, or EXPIRED. PROCESSED is not terminal: reconcile it as delivered, pending the return window.
- Accounts, payout addresses, and capabilities share one four-state machine. ACTIVE is not terminal, and REJECTED has no documented exit.
Amount precision
Amounts are JSON strings, never numbers. Regex:
^-?[0-9]+(\.[0-9]{1,8})?$. See Amounts.
Idempotency TTLs
Payments
POST endpoints follow the Payments API: “A key is consumed by its first accepted request and is never reusable: there is no expiry and nothing to outlive.”
See Idempotency for replay and retry behavior.
Pagination
The unbounded lists (trades, deposits, withdrawals, accounts, payout-addresses, payouts) use cursor pagination, newest-first by createdAt. Default page size is 25 and the maximum is 100. Their responses wrap {data, pagination: {limit, hasNext, nextCursor, hasPrev, prevCursor}}; cursors are opaque tokens that you pass back verbatim. The bounded lists (pairs, balances, financial-accounts) return their complete data array without pagination parameters or a pagination object. No endpoint uses total_count or page numbers.
See Pagination for cursor handling.
Error response shape
code, type, message, retryStrategy, and details are all required on every v3 error response (details is {} when there’s no structured context). code is stable across versions; message may change. Branch on code and type for behavior, or read retryStrategy directly for retry handling. Never branch on message. For body-portable correlation, capture the X-Trace-Id header at call time. Full catalog: Errors.
HTTP status × type quick map
What’s next
Quickstart
5-minute round trip from JWT to executed trade.
API reference
Full schemas with the interactive playground.
Errors
Every documented error code with retry semantics.