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

# Trade Settlement

> Account-side flows in the Trade product: deposits land funds in your balances; withdrawals send them out to verified withdrawal accounts. One endpoint covers fiat and stablecoin.

Trade Settlement surfaces the three things you do with funds: receive (deposits), see (balances), send (withdrawals). Fiat and stablecoin share a single withdrawal endpoint; the rail is inferred from the verified withdrawal account.

<CardGroup cols={2}>
  <Card title="Fiat" icon="landmark">
    The withdrawal account is a bank account on a rail (wire, SEPA, ACH, FPS,
    SPEI). Settlement is T+0 or T+1 depending on the rail and the submission
    cut-off. Rail is bound to the verified withdrawal account; you don't pick it
    on the request.
  </Card>

  <Card title="Stablecoin" icon="coins">
    The withdrawal account is a wallet on a blockchain (EVM chains, Solana).
    Settlement is typically minutes, gated by on-chain confirmations. The chain
    is bound to the verified withdrawal account and reported on `network`.
  </Card>
</CardGroup>

<Note title="Why this matters">
  One `POST /v3/fx/withdrawals` shape covers both fiat and stablecoin because
  the asset family is inferred from `withdrawalAccountId`. Your client code
  branches on the verified withdrawal account, not on the endpoint — you write
  one withdrawal path and let OpenFX route it.
</Note>

## The fund-movement flow

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Inter, system-ui, sans-serif','fontSize':'13px','actorBkg':'#ffffff','actorBorder':'#299f68','actorTextColor':'#114330','actorLineColor':'#a7d6bb','signalColor':'#114330','signalTextColor':'#114330','noteBkgColor':'#d7f4e1','noteBorderColor':'#299f68','noteTextColor':'#114330','labelBoxBkgColor':'#114330','labelBoxBorderColor':'#114330','labelTextColor':'#ffffff','activationBkgColor':'#d7f4e1','activationBorderColor':'#299f68'}}}%%
sequenceDiagram
  participant Client
  participant OpenFX as 🟢 OpenFX
  participant Bank as 🏦 Bank / Chain

  Bank->>+OpenFX: Fiat wire / on-chain deposit
  OpenFX-->>-Client: Webhook (deposit event)

  Client->>+OpenFX: GET /v3/fx/deposits
  OpenFX-->>-Client: Deposit list (newest first)

  Client->>+OpenFX: GET /v3/fx/balances
  OpenFX-->>-Client: Updated balances

  Client->>+OpenFX: POST /v3/fx/withdrawals<br/>(withdrawalAccountId · withdrawalAmount · currency · NEW Idempotency-Key)
  OpenFX-->>-Client: Withdrawal (status: PENDING)

  Note over OpenFX,Bank: Settlement<br/>(chain for stablecoin · rail for fiat)

  Client->>+OpenFX: GET /v3/fx/withdrawals/{id}
  OpenFX-->>-Client: Withdrawal (status: COMPLETED)
```

## Endpoints

| Path                                                                                            | Description                                                                 | Idempotency-Key         |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------- |
| [`GET /v3/fx/balances`](/v3/api-reference/trade-settlement/list-balances)                       | Per-currency `availableBalance` / `totalBalance`                            | —                       |
| [`GET /v3/fx/deposits`](/v3/api-reference/trade-settlement/list-deposits)                       | Paginated list of deposits, newest first                                    | —                       |
| [`GET /v3/fx/deposits/{id}`](/v3/api-reference/trade-settlement/get-deposit)                    | Look up a single deposit                                                    | —                       |
| [`POST /v3/fx/withdrawals`](/v3/api-reference/trade-settlement/create-withdrawal)               | Initiate a fiat or stablecoin withdrawal                                    | Required, **7-day TTL** |
| [`GET /v3/fx/withdrawals/{id}`](/v3/api-reference/trade-settlement/get-withdrawal)              | Look up a single withdrawal                                                 | —                       |
| [`GET /v3/fx/withdrawals`](/v3/api-reference/trade-settlement/list-withdrawals)                 | Paginated list (fiat + stablecoin together; split client-side by `network`) | —                       |
| [`GET /v3/fx/withdrawal-accounts`](/v3/api-reference/trade-settlement/list-withdrawal-accounts) | List verified withdrawal accounts                                           | —                       |

## The verified-account model

Every withdrawal references a `withdrawalAccountId`, a verified withdrawal account configured ahead of time. The withdrawal account can be:

* A fiat bank account on a specific rail. See [Settlement times](/v3/settlement-times) for per-rail submission cut-offs by currency.
* A stablecoin wallet on a specific blockchain. See [Supported networks](/v3/supported-networks) for the per-stablecoin chain matrix.

You don't need to declare the type or rail when withdrawing; OpenFX infers both from the verified withdrawal account. This means **one endpoint** (`POST /v3/fx/withdrawals`) covers both fiat and stablecoin with the same request shape.

<Note>
  **v2 had two account surfaces and two withdrawal endpoints; v3 collapses them
  into one.** [`GET /v2/brokerage/{orgId}
      /withdrawal_addresses`](/v2/api-reference/withdrawals/list-withdrawal-wallets)
  (stablecoin wallets) and [`GET /v2/brokerage/{orgId}
      /fiat_withdrawal_addresses`](/v2/api-reference/withdrawals/list-fiat-withdrawal-accounts)
  (fiat bank accounts) both fold into `GET /v3/fx/withdrawal-accounts`.
  Likewise, [`POST
      /v2/.../withdrawal`](/v2/api-reference/withdrawals/initiate-stablecoin-withdrawal)
  and [`POST
      /v2/.../fiat_withdrawal`](/v2/api-reference/withdrawals/initiate-fiat-withdrawal)
  become a single `POST /v3/fx/withdrawals`.
</Note>

<Warning>
  **Verified accounts are dashboard-managed.** Add accounts via the [OpenFX
  dashboard](https://app.openfx.com); your integration reads them via [`GET
      /v3/fx/withdrawal-accounts`](/v3/api-reference/trade-settlement/list-withdrawal-accounts).
</Warning>

<Note>
  **One account record = one address × one network × one asset.** If you want to
  withdraw USDC and USDT to the same Ethereum address, you add **two** verified
  accounts via the dashboard — one per `(address, network, asset)` combination.
  Likewise, the same address on Ethereum mainnet vs Polygon is two separate
  accounts. This is intentional: it protects clients who fund from exchanges
  (where the same nominal address may not actually be controlled across all
  chains, and tokens may have distinct deposit addresses even on the same chain)
  from accidentally configuring an unreachable destination. If you control all
  your custody and the same address works for every chain × asset combination,
  you still add each tuple explicitly — there is no bulk-add.
</Note>

Each verified withdrawal account carries a `displayName` — the customer-set label captured at verification (for example `"Acme Corp checking"` for fiat, `"Treasury wallet"` for stablecoin) — that's safe to render directly in your UI.

<Warning>
  **Do not parse `displayName`.** The format is not guaranteed. Render it as-is
  for human display; use the structured fields (`type`, `currency`, `network`,
  `address`) for any logic, filtering, or routing.
</Warning>

## Balances

Balances are returned per currency, with two amounts:

* `availableBalance`: usable for new trades or withdrawals right now
* `totalBalance`: total held in the currency, including any amount earmarked against pending operations (`availableBalance` ≤ `totalBalance`)

Some funds may be held against pending operations, so `availableBalance` can be lower than `totalBalance`. The held portion is the difference `totalBalance − availableBalance`; it is not broken out as a separate field in v3 (a richer breakdown may be added later). After a trade, the bought currency's `availableBalance` rises. After a withdrawal completes, the held funds leave the balance entirely and `totalBalance` drops to match `availableBalance`.

See [Amounts](/v3/amounts) for the string-encoding rules.

## Resource lifecycles

Both deposits and withdrawals have multi-step lifecycles. Track them with the dedicated pages:

<CardGroup cols={2}>
  <Card title="Withdrawal lifecycle" icon="arrow-up-from-bracket" href="/v3/withdrawal-lifecycle">
    State machine + polling pattern.
  </Card>

  <Card title="Deposit lifecycle" icon="arrow-down-to-bracket" href="/v3/deposit-lifecycle">
    How deposits are detected + completed.
  </Card>
</CardGroup>

## Common errors

<Note>
  For status codes and machine-readable error codes returned by these endpoints, see the [Withdrawal](/v3/errors#error-code-catalog) catalog in [Errors](/v3/errors). One withdrawal-specific recovery rule to know:

  * **`WITHDRAWAL_PENDING_DEPOSIT_REQUIRED`**: an outstanding settlement deposit must clear before any new withdrawal goes out. Resolve the upstream deposit, then retry as a new operation with a NEW idempotency key.
</Note>

## What's next

<CardGroup cols={2}>
  <Card title="Trade" icon="arrows-rotate" href="/v3/trading">
    Quote and execute FX trades — the other half of the product.
  </Card>

  <Card title="Verified accounts" icon="shield-check" href="/v3/setup/verified-accounts">
    Register the destinations you'll withdraw to before going live.
  </Card>

  <Card title="Webhooks setup" icon="webhook" href="/v3/webhooks/setup">
    Receive deposit and withdrawal events without polling.
  </Card>

  <Card title="Idempotency" icon="repeat" href="/v3/idempotency">
    7-day TTL on withdrawal keys (carried forward from v2); crash-safe retry
    pattern.
  </Card>
</CardGroup>