> ## Documentation Index
> Fetch the complete documentation index at: https://public-openfx.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cheat sheet

> Every endpoint at a glance. Method, path, auth, idempotency, pagination, response shape.

A single-page reference for everything callable in v3. For the narrative version of any row, follow the link.

## Endpoints

| Method | Path | Description | Auth scope | Idempotency-Key | Paginated | Returns |
| - | - | - | - | - | - | - |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/pairs`](/v3/api-reference/trade/list-currency-pairs) | List tradable currency pairs | `read` | — | Bounded | `{data: {pairs: Pair[]}}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/fx/quotes`](/v3/api-reference/trade/create-quote) | Lock a rate (`quoteForSeconds`: <span class="ofx-enum">3</span>, <span class="ofx-enum">15</span>, <span class="ofx-enum">30</span>, <span class="ofx-enum">45</span>, or <span class="ofx-enum">60</span>) | `read` | Required | — | `{data: Quote}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/quotes/{id}`](/v3/api-reference/trade/get-quote-by-id) | Retrieve one quote (pre-trade verification) | `read` | — | — | `{data: Quote}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/fx/trades`](/v3/api-reference/trade/execute-trade) | Execute a quote | `write` | Required | — | `{data: Trade}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/fx/trades/{id}/reverse-quote`](/v3/api-reference/trade/generate-reverse-quote) | Preview the amounts for reversing a trade | `write` | Required | — | `{data: ReverseQuote}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/fx/trades/{id}/reverse`](/v3/api-reference/trade/reverse-trade) | Reverse a trade against a reverse quote | `write` | Required | — | `{data: TradeReversal}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/fx/trades/{id}/settle`](/v3/api-reference/trade/settle-trade) | Settle a trade | `write` | Required | — | `{data: TradeSettlement}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/trades/{id}`](/v3/api-reference/trade/get-trade) | Retrieve one trade | `read` | — | — | `{data: Trade}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/trades`](/v3/api-reference/trade/list-trades) | List trades, newest-first | `read` | — | ✓ cursor | `{data: Trade[], pagination}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/balances`](/v3/api-reference/trade-settlement/list-balances) | Per-currency balance | `read` | — | Bounded | `{data: Balance[]}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/exposures`](/v3/api-reference/exposure/get-exposure-summary) | Exposure summary | `read` | — | — | `{data: ExposureSummary}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/deposits`](/v3/api-reference/trade-settlement/list-deposits) | List deposits, newest-first | `read` | — | ✓ cursor | `{data: Deposit[], pagination}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/deposits/{id}`](/v3/api-reference/trade-settlement/get-deposit) | Retrieve one deposit | `read` | — | — | `{data: Deposit}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/fx/withdrawals`](/v3/api-reference/trade-settlement/create-withdrawal) | Submit a withdrawal (fiat or stablecoin) | `write` | Required | — | `{data: Withdrawal}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/withdrawals/{id}`](/v3/api-reference/trade-settlement/get-withdrawal) | Retrieve one withdrawal | `read` | — | — | `{data: Withdrawal}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/withdrawals`](/v3/api-reference/trade-settlement/list-withdrawals) | List withdrawals, newest-first | `read` | — | ✓ cursor | `{data: Withdrawal[], pagination}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/fx/withdrawal-accounts`](/v3/api-reference/trade-settlement/list-withdrawal-accounts) | List verified withdrawal accounts | `read` | — | ✓ cursor | `{data: WithdrawalAccount[], pagination}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/common/accounts`](/v3/api-reference/payments/accounts/create-account) | Create an account for a recipient or a sender, with the capabilities it needs | `write` | Required | — | `{data: Account}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/common/accounts`](/v3/api-reference/payments/accounts/list-accounts) | List accounts, newest-first | `read` | — | ✓ cursor | `{data: Account[], pagination}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/common/accounts/{accountId}`](/v3/api-reference/payments/accounts/get-account) | Retrieve one account | `read` | — | — | `{data: Account}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/common/accounts/{accountId}/archive`](/v3/api-reference/payments/accounts/archive-account) | Archive an account | `write` | Required | — | `{data: Account}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/common/financial-accounts`](/v3/api-reference/payments/accounts/list-financial-accounts) | List which of your balances can fund a given payout | `read` | — | Bounded | `{data: FinancialAccount[]}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/payments/payout-addresses`](/v3/api-reference/payments/addresses/create-payout-address) | Register where the money lands | `write` | Required | — | `{data: PayoutAddress}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/payments/payout-addresses`](/v3/api-reference/payments/addresses/list-payout-addresses) | List payout addresses, newest-first | `read` | — | ✓ cursor | `{data: PayoutAddress[], pagination}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/payments/payout-addresses/verify`](/v3/api-reference/payments/addresses/verify-payout-address) | Verify a payout address | `write` | Required | — | `{data: PayoutAddressVerification}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/payments/payout-addresses/{payoutAddressId}`](/v3/api-reference/payments/addresses/get-payout-address) | Retrieve one payout address | `read` | — | — | `{data: PayoutAddress}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/payments/payout-addresses/{payoutAddressId}/archive`](/v3/api-reference/payments/addresses/archive-payout-address) | Archive a payout address | `write` | Required | — | `{data: PayoutAddress}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/payments/payout-quotes`](/v3/api-reference/payments/payouts/create-payout-quote) | Price a payout without moving funds | `write` | Required | — | `{data: PayoutQuote}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/payments/payouts`](/v3/api-reference/payments/payouts/create-payout) | Create a payout, inline-priced or from a quote | `write` | Required | — | `{data: Payout}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/payments/payouts`](/v3/api-reference/payments/payouts/list-payouts) | List payouts, newest-first | `read` | — | ✓ cursor | `{data: Payout[], pagination}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/payments/payouts/{payoutId}/confirm`](/v3/api-reference/payments/payouts/confirm-payout) | Accept the priced payout | `write` | Required | — | `{data: Payout}` |
| <span className="ofx-method-pill ofx-method-pill--post">POST</span> | [`/v3/payments/payouts/{payoutId}/cancel`](/v3/api-reference/payments/payouts/cancel-payout) | Decline a payout before acceptance | `write` | Required | — | `{data: Payout}` |
| <span className="ofx-method-pill ofx-method-pill--get">GET</span> | [`/v3/payments/payouts/{payoutId}`](/v3/api-reference/payments/payouts/get-payout) | Look up a single payout | `read` | — | — | `{data: Payout}` |

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](/v3/authentication#api-key-scopes) for the permission rules. A key without the scope a call needs returns `403` <span class="ofx-enum">AUTH\_INSUFFICIENT\_SCOPE</span>.

## Request headers

| Header | When | Value |
| - | - | - |
| `Authorization` | Always | `Bearer <jwt>`: ES256, 60s TTL, single-use (server-enforced nonce uniqueness) |
| `X-Request-Signature` | Always | ES256 (IEEE P-1363 base64url) over `METHOD\nCANONICAL_PATH\nCANONICAL_QUERY\nNONCE\nSHA256_HEX(body)`. See [Authentication → Request signing](/v3/authentication#request-signing). |
| `X-App-Mode` | Required for Live; optional for Sandbox | <span class="ofx-enum">LIVE</span> or <span class="ofx-enum">SANDBOX</span>, matching the key's environment. Defaults to <span class="ofx-enum">SANDBOX</span> when omitted, so send <span class="ofx-enum">LIVE</span> explicitly with a Live key. Any other value returns `400` <span class="ofx-enum">INVALID\_APP\_MODE</span>. See [Environments](/v3/environments). |
| `Idempotency-Key` | Writes (POST) | Client-generated. Pattern `^[a-zA-Z0-9_-]{1,255}$` (UUID recommended) |
| `Content-Type` | Writes (POST) | `application/json` |

## Response headers

Always set, every response (success and error):

| Header | Meaning |
| - | - |
| `X-Trace-Id` | Per-request ID. Echo back in support tickets. |
| `X-Request-Timestamp` | Server time the request reached the API (RFC 3339, ms) |
| `RateLimit-Limit` | Max requests in current window |
| `RateLimit-Reset` | Seconds until window resets (a duration, not an epoch time) |

Sometimes set:

| Header | When |
| - | - |
| `Idempotency-Replayed` | `true`/`false` on every POST: whether the response was replayed from the idempotency cache |
| `Retry-After` | Seconds to wait. On `429` <span class="ofx-enum">RATE\_LIMIT\_EXCEEDED</span> and `409` <span class="ofx-enum">IDEMPOTENCY\_IN\_FLIGHT</span> only |
| `Sunset` + `Link: rel="successor-version"` | On 410 (v1 endpoints after Dec 31 2026) |

## 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.

See [Resource IDs](/v3/resource-ids) for the prefix table, foreign-key surface, and stability contract.

## Status enums

| Resource | Values |
| - | - |
| `Quote.status` | <span class="ofx-status-pill ofx-status-pill--green">ACTIVE</span> · <span class="ofx-status-pill ofx-status-pill--gray">EXPIRED</span> · <span class="ofx-status-pill ofx-status-pill--gray">CONSUMED</span> |
| `Trade.status` | <span class="ofx-status-pill ofx-status-pill--blue">PENDING</span> · <span class="ofx-status-pill ofx-status-pill--blue">LOCKED</span> · <span class="ofx-status-pill ofx-status-pill--blue">READY\_TO\_SETTLE</span> · <span class="ofx-status-pill ofx-status-pill--green">EXECUTED</span> · <span class="ofx-status-pill ofx-status-pill--red">REVERSED</span> |
| `Deposit.status` | <span class="ofx-status-pill ofx-status-pill--blue">PENDING</span> · <span class="ofx-status-pill ofx-status-pill--green">COMPLETED</span> · <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span> · <span class="ofx-status-pill ofx-status-pill--yellow">ERROR</span> |
| `Withdrawal.status` | <span class="ofx-status-pill ofx-status-pill--blue">PENDING</span> · <span class="ofx-status-pill ofx-status-pill--green">COMPLETED</span> · <span class="ofx-status-pill ofx-status-pill--gray">CANCELLED</span> |
| `Payout.status` | <span class="ofx-status-pill ofx-status-pill--blue">REQUIRES\_CONFIRMATION</span> · <span class="ofx-status-pill ofx-status-pill--blue">ACCEPTED</span> · <span class="ofx-status-pill ofx-status-pill--blue">PROCESSING</span> · <span class="ofx-status-pill ofx-status-pill--yellow">IN\_REVIEW</span> · <span class="ofx-status-pill ofx-status-pill--green">PROCESSED</span> · <span class="ofx-status-pill ofx-status-pill--red">RETURNED</span> · <span class="ofx-status-pill ofx-status-pill--red">FAILED</span> · <span class="ofx-status-pill ofx-status-pill--gray">CANCELLED</span> · <span class="ofx-status-pill ofx-status-pill--gray">EXPIRED</span> |
| `Account.status` | <span class="ofx-status-pill ofx-status-pill--blue">PENDING</span> · <span class="ofx-status-pill ofx-status-pill--green">ACTIVE</span> · <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span> · <span class="ofx-status-pill ofx-status-pill--yellow">REQUIRES\_INFORMATION</span> |
| `PayoutAddress.status` | <span class="ofx-status-pill ofx-status-pill--blue">PENDING</span> · <span class="ofx-status-pill ofx-status-pill--green">ACTIVE</span> · <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span> · <span class="ofx-status-pill ofx-status-pill--yellow">REQUIRES\_INFORMATION</span> |
| `AccountCapability.status` | <span class="ofx-status-pill ofx-status-pill--blue">PENDING</span> · <span class="ofx-status-pill ofx-status-pill--green">ACTIVE</span> · <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span> · <span class="ofx-status-pill ofx-status-pill--yellow">REQUIRES\_INFORMATION</span> |

* Quotes terminate at <span class="ofx-status-pill ofx-status-pill--gray">EXPIRED</span> or <span class="ofx-status-pill ofx-status-pill--gray">CONSUMED</span>.
* Trades terminate at <span class="ofx-status-pill ofx-status-pill--green">EXECUTED</span> or <span class="ofx-status-pill ofx-status-pill--red">REVERSED</span>.
* Deposits terminate at <span class="ofx-status-pill ofx-status-pill--green">COMPLETED</span>, <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span>, or <span class="ofx-status-pill ofx-status-pill--yellow">ERROR</span>.
* Withdrawals terminate at <span class="ofx-status-pill ofx-status-pill--green">COMPLETED</span> or <span class="ofx-status-pill ofx-status-pill--gray">CANCELLED</span>.
* Payouts terminate at <span class="ofx-status-pill ofx-status-pill--red">RETURNED</span>, <span class="ofx-status-pill ofx-status-pill--red">FAILED</span>, <span class="ofx-status-pill ofx-status-pill--gray">CANCELLED</span>, or <span class="ofx-status-pill ofx-status-pill--gray">EXPIRED</span>. <span class="ofx-status-pill ofx-status-pill--green">PROCESSED</span> is not terminal: reconcile it as delivered, pending the return window.
* Accounts, payout addresses, and capabilities share one four-state machine. <span class="ofx-status-pill ofx-status-pill--green">ACTIVE</span> is not terminal, and <span class="ofx-status-pill ofx-status-pill--red">REJECTED</span> has no documented exit.

See [Status enums reference](/v3/glossary#status-enums).

## Amount precision

| Currency type | Max decimals | Example | Over-precision error |
| - | - | - | - |
| Fiat | 2 | `"1000.00"` | `422` <span class="ofx-enum">WITHDRAWAL\_INVALID\_AMOUNT\_PRECISION</span> |
| Crypto | 6 | `"1000.000001"` | `422` <span class="ofx-enum">WITHDRAWAL\_INVALID\_AMOUNT\_PRECISION</span> |

Amounts are JSON **strings**, never numbers. Regex: `^-?[0-9]+(\.[0-9]{1,8})?$`. See [Amounts](/v3/amounts).

## Idempotency TTLs

| Endpoint | TTL | Reason |
| - | - | - |
| `POST /v3/fx/quotes` | 30 min | Duplicates are cheap (re-quote) |
| `POST /v3/fx/trades` | 24 h | Duplicates move thousands of dollars |
| `POST /v3/fx/trades/{id}/reverse-quote` | 30 min | Duplicates are cheap (re-quote) |
| `POST /v3/fx/trades/{id}/reverse` | 24 h | Duplicates move thousands of dollars |
| `POST /v3/fx/trades/{id}/settle` | 24 h | Duplicates move thousands of dollars |
| `POST /v3/fx/withdrawals` | 7 days | Sized for long-running rails (SWIFT, weekend ACH, end-of-month batches) |

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](/v3/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.

| Param | Type |
| - | - |
| `limit` | int 1–100 |
| `startingAfter` | opaque cursor string (older than) |
| `endingBefore` | opaque cursor string (newer than) |

See [Pagination](/v3/pagination) for cursor handling.

## Error response shape

```json theme={"theme":{"light":"poimandres","dark":"poimandres"}}
{
  "error": {
    "code": "QUOTE_EXPIRED",
    "type": "CONFLICT",
    "message": "The quoted rate has expired. Request a new quote.",
    "retryStrategy": "FIX_AND_RESUBMIT",
    "details": {
      "quoteId": "qte_3FfGK34vwMvVFDedyb2nkf",
      "expiredAt": "2026-04-28T10:00:00.000Z"
    }
  }
}
```

`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](/v3/errors).

## HTTP status × type quick map

| Status | Typical `type` | Meaning |
| - | - | - |
| 400 | <span class="ofx-enum">VALIDATION\_ERROR</span> | Malformed JSON, wrong types |
| 401 | <span class="ofx-enum">AUTHENTICATION\_ERROR</span> | Token missing/invalid/expired |
| 403 | <span class="ofx-enum">AUTHORIZATION\_ERROR</span> | Auth ok, not allowed |
| 404 | <span class="ofx-enum">NOT\_FOUND</span> | Resource missing (also covers cross-org leakage prevention) |
| 409 | <span class="ofx-enum">CONFLICT</span> | State-driven conflict (insufficient balance, in-flight key) |
| 422 | <span class="ofx-enum">VALIDATION\_ERROR</span> / <span class="ofx-enum">CONFLICT</span> | Semantic violation; idempotency-mismatch |
| 428 | <span class="ofx-enum">VALIDATION\_ERROR</span> | Missing `Idempotency-Key` on a write |
| 429 | <span class="ofx-enum">RATE\_LIMITED</span> | Throttled |
| 500 | <span class="ofx-enum">INTERNAL\_ERROR</span> | <span class="ofx-enum">INTERNAL\_ERROR</span> catch-all; write-path 500s (<span class="ofx-enum">TRADE\_EXECUTION\_FAILED</span>, <span class="ofx-enum">WITHDRAWAL\_INITIATION\_FAILED</span>) echo `details.resourceId` for safe check-state-then-retry |

## What's next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="https://public-assets.openfx.com/docs/icons/quickstart.svg" href="/v3/quickstart">
    5-minute round trip from JWT to executed trade.
  </Card>

  <Card title="API reference" icon="code" href="/v3/api-reference/trade/list-currency-pairs">
    Full schemas with the interactive playground.
  </Card>

  <Card title="Errors" icon="https://public-assets.openfx.com/docs/icons/errors.svg" href="/v3/errors">
    Every documented error code with retry semantics.
  </Card>
</CardGroup>