# OpenFX

> OpenFX API documentation. Real-time cross-border FX and stablecoin payment infrastructure.

- [Introduction](https://docs.openfx.com/v3/introduction.md): OpenFX gives financial institutions programmatic access to FX and stablecoin liquidity, plus payouts to bank accounts, with a consistent `{ data }` response envelope, stable error codes, and cursor pagination.
- [Quickstart](https://docs.openfx.com/v3/quickstart.md): Get from zero to your first executed trade in under 5 minutes.
- [Cheat sheet](https://docs.openfx.com/v3/cheat-sheet.md): Every endpoint at a glance. Method, path, auth, idempotency, pagination, response shape.
- [MCP connectors](https://docs.openfx.com/v3/mcp-connectors.md): Connect Claude, ChatGPT, Claude Code, or Codex to your OpenFX account to query trades, deposits, and withdrawals in plain language.
- [Glossary](https://docs.openfx.com/v3/glossary.md): Definitions for the vocabulary: resources, headers, status enums, and concepts used across the spec.
- [Trades](https://docs.openfx.com/v3/trades.md): The trade state machine from execution to settlement or reversal: statuses, settlement windows, the settle and reverse actions, and the webhooks that report each change.
- [Currencies](https://docs.openfx.com/v3/currencies.md): Fiat and stablecoin currencies for FX trading and first-party withdrawals, with rails, networks, and early-access labels.
- [Quotes](https://docs.openfx.com/v3/quotes.md): Atomic FX trades: discover supported pairs, quote a rate, execute the trade against the quote.
- [Settlement models](https://docs.openfx.com/v3/settlement-models.md): Netted and Per-Trade settlement models, plus the balances, deposits, and withdrawals flows they share.
- [Balances](https://docs.openfx.com/v3/balances.md): How to read the balances response: the org-wide aggregate, the per-currency rows, and what moves each amount.
- [Exposure](https://docs.openfx.com/v3/exposure.md): The organization's exposure-limit usage: how much is committed to unsettled trades, and the breakdown by currency and settlement stage.
- [Verified accounts](https://docs.openfx.com/v3/verified-accounts.md): Pre-configure your bank accounts and stablecoin wallets so withdrawals only need an `withdrawalAccountId` and a `withdrawalAmount`.
- [Deposits](https://docs.openfx.com/v3/deposits.md): Deposit status values, detection mechanics per rail, and the reconciliation pattern for incoming funds.
- [Withdrawals](https://docs.openfx.com/v3/withdrawals.md): Settlement windows per rail, and how to track the time between submission and settlement: webhooks first, adaptive polling as a fallback.
- [Settlement times](https://docs.openfx.com/v3/settlement-times.md): Submission cut-offs per fiat rail. Withdrawals submitted after the cut-off are processed the next banking day.
- [Payouts](https://docs.openfx.com/v3/payouts.md): The full payout flow: account structure, one-time recipient setup, and the payout state machine from create to settlement.
- [EUR payout integration guide](https://docs.openfx.com/v3/eur-payout-integration.md): Pay a euro bank account over SEPA or SWIFT: set up the account and bank details, then price, create, and confirm the payout.
- [INR payout integration guide](https://docs.openfx.com/v3/inr-payout-integration.md): Pay an Indian bank account in INR: set up the sender and receiver, register the bank account, and pay regular or NRE accounts.
- [MXN payout integration guide](https://docs.openfx.com/v3/mxn-payout-integration.md): Pay a Mexican bank account in MXN over SPEI: register the CLABE, then meet the memo and ownership-check rules.
- [COP payout integration guide](https://docs.openfx.com/v3/cop-payout-integration.md): Pay a Colombian bank account or Bre-B key in COP: register the account or key, then meet the memo and limit rules.
- [AED payout integration guide](https://docs.openfx.com/v3/aed-payout-integration.md): Pay a UAE bank account in AED: register the IBAN, then meet the purpose, funding, memo, and limit rules.
- [Capabilities](https://docs.openfx.com/v3/capabilities.md): Every capability you can request, the identity details each one needs, and how capabilities control who can be paid.
- [Account model](https://docs.openfx.com/v3/account-model.md): The resources behind a payout, how they relate, and the statuses they share.
- [Blueprints](https://docs.openfx.com/v3/blueprints.md): Choose what you're converting and get each integration step in order, with the API calls behind it and request and response bodies taken from the v3 specification.
- [Authentication](https://docs.openfx.com/v3/authentication.md): Mint ES256-signed JWT bearer tokens and ES256 request signatures to access the OpenFX API.
- [Environments](https://docs.openfx.com/v3/environments.md): The Sandbox and Live environments available on the OpenFX API, and how a request selects between them.
- [Resource IDs](https://docs.openfx.com/v3/resource-ids.md): Every resource has a readable, typed ID: a resource-type prefix plus a Base58 encoding of the underlying UUID. Foreign-key fields like withdrawalAccountId and quoteId reference these IDs across resources.
- [Amounts](https://docs.openfx.com/v3/amounts.md): Format rules, prefix vocabulary, parsing examples, and precision behavior for monetary values.
- [Idempotency](https://docs.openfx.com/v3/idempotency.md): Idempotency-Key headers make retries safe: required on every write, TTLs from 30 minutes to 7 days, explicit responses for in-flight/mismatch, and the crash-recovery pattern to keep it safe across restarts.
- [Errors](https://docs.openfx.com/v3/errors.md): Errors return in a stable, machine-readable envelope with a code, type, human message, retry strategy, and per-code details.
- [Rate limiting](https://docs.openfx.com/v3/rate-limiting.md): OpenFX exposes IETF-standard RateLimit-* headers on every response so you always know your cap and when it resets.
- [Pagination](https://docs.openfx.com/v3/pagination.md): List endpoints use cursor pagination with a Stripe-style startingAfter / endingBefore pattern. No page numbers, no deep-pagination cliff.
- [Metadata & tracing](https://docs.openfx.com/v3/metadata-and-tracing.md): Every response carries an X-Trace-Id and an X-Request-Timestamp. Log the trace ID for correlation, retries, and support triage.
- [Live checklist](https://docs.openfx.com/v3/live-checklist.md): Pre-launch checklist, key rotation, IP allowlisting, monitoring, and ongoing operations guidance.
- [List currency pairs](https://docs.openfx.com/v3/api-reference/trade/list-currency-pairs.md): Returns every currency pair tradable on your account, with per-pair limits and supported directions.
- [Create a quote](https://docs.openfx.com/v3/api-reference/trade/create-quote.md): Locks a rate for a currency pair and amount, returning a quote id valid until expiresAt.
- [Retrieve a quote](https://docs.openfx.com/v3/api-reference/trade/get-quote-by-id.md): Returns a single quote by ID, retrievable for 2 days after creation. Useful for audit, reconciliation, and verifying a quote has not been consumed.
- [Execute a trade](https://docs.openfx.com/v3/api-reference/trade/execute-trade.md): Executes a trade against a quote. Call this before the quotes expiresAt.
- [List trades](https://docs.openfx.com/v3/api-reference/trade/list-trades.md): Returns trades on your account.
- [Retrieve a trade](https://docs.openfx.com/v3/api-reference/trade/get-trade.md): Returns a single trade by ID.
- [Generate a reverse quote](https://docs.openfx.com/v3/api-reference/trade/generate-reverse-quote.md): Creates a time-limited quote previewing the amounts and differential for reversing a trade.
- [Reverse a trade](https://docs.openfx.com/v3/api-reference/trade/reverse-trade.md): Executes a reversal of a previously executed unsettled trade against a reverse quote.
- [Settle a trade](https://docs.openfx.com/v3/api-reference/trade/settle-trade.md): Settles a trade whose settlement is finalized out of band.
- [List balances](https://docs.openfx.com/v3/api-reference/trade-settlement/list-balances.md): Returns one entry per currency held, with available and total balances.
- [List deposits](https://docs.openfx.com/v3/api-reference/trade-settlement/list-deposits.md): Returns deposits to your account. Filter by `currency`.
- [Retrieve a deposit](https://docs.openfx.com/v3/api-reference/trade-settlement/get-deposit.md): Returns a single deposit by ID.
- [Create a withdrawal](https://docs.openfx.com/v3/api-reference/trade-settlement/create-withdrawal.md): Initiates a withdrawal to a verified withdrawal account. Pass a withdrawalAccountId from List withdrawal accounts.
- [List withdrawals](https://docs.openfx.com/v3/api-reference/trade-settlement/list-withdrawals.md): Returns withdrawals on your account. Fiat and stablecoin withdrawals appear in the same list.
- [Retrieve a withdrawal](https://docs.openfx.com/v3/api-reference/trade-settlement/get-withdrawal.md): Returns a single withdrawal by ID.
- [List withdrawal accounts](https://docs.openfx.com/v3/api-reference/trade-settlement/list-withdrawal-accounts.md): Returns the withdrawal accounts on your account, in any status: fiat bank accounts and stablecoin wallets. Filter to verified accounts with `verified=true`.
- [Retrieve exposure summary](https://docs.openfx.com/v3/api-reference/exposure/get-exposure-summary.md): Returns the organization's exposure-limit usage, aggregated and broken down by currency.
- [Create an account](https://docs.openfx.com/v3/api-reference/payments/accounts/create-account.md): Create an account and optionally request capabilities for it in the same call.
- [List accounts](https://docs.openfx.com/v3/api-reference/payments/accounts/list-accounts.md): List with cursor pagination.
- [Retrieve an account](https://docs.openfx.com/v3/api-reference/payments/accounts/get-account.md): Retrieve a single account.
- [Archive an account](https://docs.openfx.com/v3/api-reference/payments/accounts/archive-account.md): Soft-archive an account.
- [List financial accounts](https://docs.openfx.com/v3/api-reference/payments/accounts/list-financial-accounts.md): List the financial accounts your organization can currently use to fund a payout settling in a given `receiveCurrency`.
- [Create a payout address](https://docs.openfx.com/v3/api-reference/payments/addresses/create-payout-address.md): Register a destination `accountId` can be paid at.
- [List payout addresses](https://docs.openfx.com/v3/api-reference/payments/addresses/list-payout-addresses.md): Cursor list of payout addresses across the organization, optionally narrowed to one account via `?accountId=`.
- [Verify a payout address](https://docs.openfx.com/v3/api-reference/payments/addresses/verify-payout-address.md): Verify a payout address before creating it.
- [Retrieve a payout address](https://docs.openfx.com/v3/api-reference/payments/addresses/get-payout-address.md): Retrieve a full `PayoutAddress`, including its `verifications[]` and the `status` derived from them.
- [Archive a payout address](https://docs.openfx.com/v3/api-reference/payments/addresses/archive-payout-address.md): Soft-archive a payout address.
- [Create a payout quote](https://docs.openfx.com/v3/api-reference/payments/payouts/create-payout-quote.md): Request a quote for a currency pair by specifying either the amount to send or the amount to receive.
- [Create a payout](https://docs.openfx.com/v3/api-reference/payments/payouts/create-payout.md): Create a payout, ordinarily in `REQUIRES_CONFIRMATION` (no funds moved until confirm).
- [List payouts](https://docs.openfx.com/v3/api-reference/payments/payouts/list-payouts.md): Cursor list; each element a full Payout, not a summary row.
- [Retrieve a payout](https://docs.openfx.com/v3/api-reference/payments/payouts/get-payout.md): Retrieve a payout.
- [Confirm a payout](https://docs.openfx.com/v3/api-reference/payments/payouts/confirm-payout.md): Acknowledge all `confirmations[]` atomically.
- [Cancel a payout](https://docs.openfx.com/v3/api-reference/payments/payouts/cancel-payout.md): Cancel a payout while it's still in `REQUIRES_CONFIRMATION`; idempotent, re-cancelling returns 200.
- [Webhooks setup](https://docs.openfx.com/v3/webhooks/setup.md): Register an HTTPS endpoint, store the signing secret, verify every event, and stop polling.
- [Webhook authentication](https://docs.openfx.com/v3/webhooks/authentication.md): Timestamped HMAC-SHA256 signatures in `X-OpenFX-Signature`. Verify every event server-side with a constant-time comparison and a replay window.
- [Deposit completed](https://docs.openfx.com/v3/webhooks/deposits/deposit-completed.md): A fiat or stablecoin deposit reaches `COMPLETED` and is credited to your balance.
- [Withdrawal completed](https://docs.openfx.com/v3/webhooks/withdrawals/withdrawal-completed.md): A fiat or stablecoin withdrawal reaches `COMPLETED` and settles to the destination account.
- [Trade ready to settle](https://docs.openfx.com/v3/webhooks/trades/trade-ready-to-settle.md): A future-dated (`T1`/`T2`), manually-settled trade reaches its settlement window and awaits `POST .../settle`.
- [Trade settled](https://docs.openfx.com/v3/webhooks/trades/trade-settled.md): A trade reaches `EXECUTED`, immediately for `IMMEDIATE`/`T0` trades or once a future-dated trade settles.
- [Trade reversed](https://docs.openfx.com/v3/webhooks/trades/trade-reversed.md): `POST .../reverse` unwinds a `READY_TO_SETTLE` trade.
- [Account created](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-created.md): The account now exists via POST /v3/common/accounts; `data.status` reports its root standing as it stood when the event was emitted, ordinarily `PENDING`.
- [Account archived](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-archived.md): Client soft-archived the account via POST .../archive; `data.archivedAt` is now set.
- [Account activated](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-activated.md): Root `status` `PENDING` → `ACTIVE`: the account is in good standing, so a payout may now name it as `receiver` or as `sender`.
- [Account rejected](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-rejected.md): Root `status` → `REJECTED`: OpenFX's judgment went against the account, so it can no longer be paid, named as `sender`, or given new payout addresses, and the remedy is a replacement account.
- [Account requires information](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-requires-information.md): Root `status` → `REQUIRES_INFORMATION`: OpenFX has asked for information about the account, which travels through your operational channel rather than the API, and a payout is blocked exactly as under `PENDING` while it stands.
- [Account capability activated](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-capability-activated.md): One capability moved `PENDING` → `ACTIVE`, so it may now back its activity; `data.capability` names which capability.
- [Account capability rejected](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-capability-rejected.md): A setup act was declined, moving the capability to `REJECTED`; `data.capability` names which capability, and the remedy is to request a replacement capability.
- [Account capability requires information](https://docs.openfx.com/v3/webhooks/payments/accounts-webhooks/account-capability-requires-information.md): OpenFX has requested information for one capability's setup, moving it to `REQUIRES_INFORMATION`; it cannot back its activity while that stands, and `data.capability` names which capability.
- [Payout address created](https://docs.openfx.com/v3/webhooks/payments/addresses-webhooks/payout-address-created.md): Payout address created via POST /v3/payments/payout-addresses; `data.previousStatus` is null and `data.status` reports the rollup as it stood at emit, ordinarily `PENDING`.
- [Payout address activated](https://docs.openfx.com/v3/webhooks/payments/addresses-webhooks/payout-address-activated.md): Readiness `status` `PENDING` → `ACTIVE`, every setup act returned and none of them blocks.
- [Payout address rejected](https://docs.openfx.com/v3/webhooks/payments/addresses-webhooks/payout-address-rejected.md): Readiness `status` `PENDING` → `REJECTED`, a setup act returned a blocking result.
- [Payout address requires information](https://docs.openfx.com/v3/webhooks/payments/addresses-webhooks/payout-address-requires-information.md): Readiness `status` → `REQUIRES_INFORMATION`: OpenFX has requested information the address's setup needs, through your operational channel, so it cannot back payouts while that stands.
- [Payout address verification resolved](https://docs.openfx.com/v3/webhooks/payments/addresses-webhooks/payout-address-verification-resolved.md): An act in `data.verifications` resolved.
- [Payout address archived](https://docs.openfx.com/v3/webhooks/payments/addresses-webhooks/payout-address-archived.md): Client soft-archived the address via POST .../archive; `data.archivedAt` is now set.
- [Payout created](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-created.md): Payout created via POST /v3/payments/payouts; `data.status` reports where it stood at emit, ordinarily `REQUIRES_CONFIRMATION`.
- [Payout accepted](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-accepted.md): `REQUIRES_CONFIRMATION` → `ACCEPTED`: every entry in `confirmations[]` stands acknowledged, ordinarily via POST .../confirm; funds not yet debited.
- [Payout processing](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-processing.md): `ACCEPTED` → `PROCESSING` (funds debited) or `IN_REVIEW` → `PROCESSING` (review resolved favorably), disambiguate via `data.previousStatus`.
- [Payout in review](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-in-review.md): `PROCESSING` → `IN_REVIEW` (manual/compliance hold); funds remain debited.
- [Payout processed](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-processed.md): `PROCESSING` → `PROCESSED` (settled).
- [Payout returned](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-returned.md): `PROCESSING`, `IN_REVIEW`, or `PROCESSED` → `RETURNED` (any post-debit unwind), see `data.return`.
- [Payout failed](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-failed.md): `REQUIRES_CONFIRMATION` → `FAILED` (a pre-confirm failure) or `ACCEPTED` → `FAILED` (settlement failed after acceptance), each before funds reached the rail; read `data.previousStatus` for the origin.
- [Payout cancelled](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-cancelled.md): `REQUIRES_CONFIRMATION` → `CANCELLED` via POST .../cancel.
- [Payout expired](https://docs.openfx.com/v3/webhooks/payments/payouts-webhooks/payout-expired.md): `REQUIRES_CONFIRMATION` → `EXPIRED`, the applied quote expired before confirmation.

## OpenAPI Specs

- [openapi-v3-payments](/api-reference/openapi-v3-payments.json)
- [openapi-v3](/api-reference/openapi-v3.json)