Skip to main content
A single-page reference for v3 vocabulary. Terms are alphabetical; each links out to the page that uses it in context.

​
A

Account The identity of a person or organization you move money to or on behalf of, plus its payout capabilities. An Account holds no money; a FinancialAccount holds the funds. See Account model. Atomic execution A trade either succeeds at the quoted rate or fails; there is no partial fill. See Trades.

​
B

Balance The per-currency record returned by GET /v3/fx/balances. One row per currency, carrying withdrawableBalance and totalBalance. The response also carries an aggregate block with the org’s net equity across all currencies, converted to USD. Bearer token The JWT passed in Authorization: Bearer <jwt>. ES256-signed, 60s TTL, single-use. Every request also carries a body-bound X-Request-Signature header. See Authentication.

​
C

Capability Permission for an account to receive payouts in a currency or act as a payout’s sender. Each AccountCapability has an opaque id, read-only coverage details, and its own status. See Capabilities. Cursor pagination v3’s pagination model: startingAfter / endingBefore with stable IDs. No page / offset integers. See Pagination. Cut-off The latest time OpenFX submits a fiat withdrawal to a rail on the same banking day. Submissions after the cut-off roll to the next banking day. Tables in Settlement times.

​
D

Deposit Incoming funds (fiat wire or on-chain stablecoin transfer) observed by OpenFX and (once cleared) credited to your balance. Read via GET /v3/fx/deposits. See Deposits.

​
E

ES256 The ECDSA signature algorithm OpenFX uses to sign JWTs (and validate yours). Asymmetric: your private key signs, OpenFX validates with the public key on file. See Authentication. expiresAt On a Quote, the wall-clock at which the quoted rate is no longer executable. Default 3 seconds from creation; configurable via quoteForSeconds (standard durations: 3, 15, 30, 45, 60). See Quotes → Quote lifecycle. Exposure limit The amount of unsettled trades your organization can have open at one time. You can execute trades up to this limit and settle them before you withdraw. Read via GET /v3/fx/exposures. See Exposure.

​
F

Financial account A balance your organization holds with OpenFX that can fund a payout. The payout debits financialAccountId; the recipient is identified separately through receiver.payoutAddressId. See Account model.

​
I

Idempotency-Key Client-generated UUID (or any unique string) passed on state-changing requests. A retry with the same key returns the cached result instead of executing the operation twice. Required on every write; returns 428 IDEMPOTENCY_KEY_MISSING per RFC 6585 when omitted. See Idempotency. Idempotency-Replayed Response header emitted on every response from idempotent endpoints (POST /quotes, POST /trades, POST /withdrawals). true on a cache hit (the body is replayed from a prior request with the same key); false on a fresh execution. Always present on these three endpoints; omitted on GETs. See Idempotency → How to tell a replay from a fresh execution.

​
J

JWT (JSON Web Token) The bearer token format v3 uses for authentication. ES256-signed, 60s TTL, single-use (server-enforced nonce uniqueness). Mint a fresh one per request and pair it with a freshly computed X-Request-Signature header. See Authentication.

​
N

Naming conventions Three layers, three rules. JSON field keys are camelCase (withdrawalAccountId, buyAmount, createdAt). URL path segments are kebab-case (/v3/fx/withdrawal-accounts, /v3/fx/pairs). Type / schema / resource names are PascalCase in prose and OpenAPI components (WithdrawalAccount, Trade, Quote). HTTP headers keep their HTTP-spec form (X-Trace-Id, Idempotency-Key). Same split used by Stripe, Plaid, Twilio. network On a Deposit or Withdrawal, the settlement network or rail (e.g. ETHEREUM for a stablecoin movement, FIAT for a bank-rail movement). See Supported networks for the stablecoin chain matrix.

​
P

Pair A tradable (buyCurrency, sellCurrency) combination with minTradeAmount and maxTradeAmount (denominated in sellCurrency). Listed via GET /v3/fx/pairs. See Currencies for the platform-wide set. Payout Money sent from one of your financial accounts to a recipient’s payout address. A payout starts in REQUIRES_CONFIRMATION without moving funds; you confirm it to accept the priced payout. Unlike a first-party withdrawal, a payout can pay someone else’s bank account. See Payouts. Payout address A recipient’s registered bank destination, represented by PayoutAddress and owned by an Account. It is separate from a verified withdrawal account. To correct an address, create a replacement and archive the old one. See Account model → Payout addresses. Payout quote An immutable, time-bounded price snapshot that moves no funds. Pass its id as quoteId to create a payout from that price, or create an inline-priced payout without a separate quote. See Payouts. Status enums Different resources expose different status values. For payouts, PROCESSED is not terminal: funds can still be returned. The terminal states are RETURNED, FAILED, CANCELLED, and EXPIRED. See Payouts and Account model. Trades terminate at EXECUTED or REVERSED; LOCKED and READY_TO_SETTLE are transitional states on a future-dated (T1/T2) trade. Deposits terminate at COMPLETED, REJECTED, or ERROR. Withdrawals terminate at COMPLETED or CANCELLED. All documented values are UPPERCASE, consistent with currency codes (USD, EUR), network identifiers (ETHEREUM, SOLANA), and error codes (TRADE_NOT_FOUND) elsewhere in v3. See Trades, Deposits, and Withdrawals.

​
Q

Quote A binding rate returned by POST /v3/fx/quotes. Single-execution: pass the id to POST /v3/fx/trades before expiresAt. Retrievable by ID for 2 days from createdAt; see Quotes → Retrieving a quote.

​
R

Rail The fiat settlement system a withdrawal or payout travels through (e.g. Fedwire, SWIFT, SEPA, SPEI, FPS, PIX, NPP, UAEFTS). For withdrawals, it is bound to the verified withdrawal account and reported as WithdrawalAccount.rail. For payouts, the platform selects the rail and reports it on the quote and payout. CHAPS is a withdrawal settlement route that OpenFX chooses; it is not a WithdrawalAccount.rail value. See Settlement times and Payouts. Receiver The account being paid, identified on a payout through receiver.payoutAddressId. The address belongs to that account, so you do not name its account id separately. See Account model → Roles on a payout. reference_amount / reference_currency (v2, removed in v3) v2 quote-create indirection: client passed an amount plus the currency it was denominated in. Removed in v3; the v3 quote request supplies exactly one of buyAmount or sellAmount directly. Routing family The routingFamily on a payout address determines which bank details it needs, such as an IBAN for SEPA or a CLABE for Mexico. It is not the same as the settlement rail selected for a payout. See Account model → Payout addresses.

​
S

Sandbox The OpenFX test environment. Same base URL (api.openfx.com) as Live; each API key is bound to one environment, and Sandbox keys carry a sandbox_ prefix. X-App-Mode must match the key’s environment and defaults to SANDBOX when omitted. See Environments. Sender An account on whose behalf you make a payout, distinct from the recipient. Funds still come from your financial account. Only INR payouts support a sender; it needs an active sending capability. See Account model → Roles on a payout. Stablecoin Fiat-pegged crypto assets supported on v3: USDC, USDT, EURC. Each is tradable, depositable, and withdrawable on one or more chains. See Currencies → Stablecoins.

​
T

Timestamps All v3 timestamps are ISO 8601 UTC with millisecond precision: YYYY-MM-DDTHH:mm:ss.sssZ (e.g. 2026-04-28T10:00:00.000Z). The trailing Z is required. Always parse as UTC; convert to a local zone only at display time. totalBalance Total funds held in a currency on a Balance row, including any amount earmarked against pending operations. Ordinarily withdrawableBalance ≤ totalBalance, but totalBalance can itself go negative if the org owes a settlement in that currency; in that case withdrawableBalance is 0. The held portion is the difference totalBalance − withdrawableBalance (when totalBalance is non-negative) and is not broken out as a separate field in v3. See Amounts → Balance lifecycle. Trade The execution of a quote. Status progresses through PENDING, LOCKED (future-dated only), and READY_TO_SETTLE (future-dated, manual settlement only) to a terminal EXECUTED, or to REVERSED if unwound before settlement. See Trades. Trade Settlement The v3 surface that covers balances, deposits, withdrawals, and verified withdrawal accounts. Sits under /v3/fx/. See Settlement models. transactionHash The on-chain transaction hash of a stablecoin deposit or withdrawal. Null until the transaction is broadcast, and always null on fiat movements.

​
W

Webhook A signed HTTP POST OpenFX sends to your endpoint when an event occurs. The envelope carries type (the resource noun, e.g. "withdrawals"), eventType (the product-prefixed event name, e.g. "fx.withdrawal.completed"), id, createdAt, and a single data object: close to, but not identical to, the resource’s v3 REST shape (data.status: "COMPLETED", camelCase keys, string amounts), not an array. HMAC-SHA256 signed via the X-OpenFX-Signature header. See Webhook authentication and Webhooks setup. Verified withdrawal account A pre-configured bank account or on-chain address that withdrawals can settle to. Created via the dashboard; referenced by withdrawalAccountId on withdrawals. The rail or chain is bound to the withdrawal account at creation. See Verified accounts. Withdrawal An outgoing transfer initiated via POST /v3/fx/withdrawals. Same endpoint covers fiat and stablecoin; the rail is resolved server-side from the referenced withdrawal account. See Withdrawals. withdrawalAccountId The ID (wac_ prefix; a bare UUID is also accepted on input) of the verified withdrawal account a withdrawal settles to: either a fiat bank account or a stablecoin wallet. Created in the OpenFX dashboard, read via GET /v3/fx/withdrawal-accounts, and supplied on POST /v3/fx/withdrawals. Carries the rail/chain, so the request body never names a network. Renamed from the v2 request field withdrawalAddressId. See Verified accounts. withdrawableBalance Funds usable right now for trades or withdrawals: on a Balance row (per currency) or on the response’s aggregate block (org-wide net equity in USD). Never negative; 0 when the corresponding totalBalance (or the org’s overall net position) is negative. Renamed from availableBalance. See Amounts → Prefix vocabulary.

​
X

X-Trace-Id Response header carrying a per-request trace ID. Include it in support requests; capture it on the success path too. See Metadata and tracing.

​
What’s next

Payouts

Recipient setup, payout pricing, confirmation, and settlement.

Currencies

Fiat + stablecoin platform tables.

Supported networks

Per-stablecoin chain matrix.

Settlement times

Fiat-rail cut-off tables.

Errors

Stable error codes and the retry triage matrix.