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

# Settlement models

> Netted and Per-Trade settlement models, plus the balances, deposits, and withdrawals flows they share.

Every OpenFX organization runs exactly one settlement model, an organization-level setting rather than a per-trade or per-request option. Both models coexist on the platform; neither replaces the other, and a trade's `settlementWindow` (<span class="ofx-enum">IMMEDIATE</span>, <span class="ofx-enum">T0</span>, <span class="ofx-enum">T1</span>, <span class="ofx-enum">T2</span>) is orthogonal to which one you're on.

<CardGroup cols={2}>
  <Card title="Netted Settlement" icon="clock">
    The default. A trade settles on its own: immediately for <span class="ofx-enum">IMMEDIATE</span>/<span class="ofx-enum">T0</span>, automatically once the window opens for <span class="ofx-enum">T1</span>/<span class="ofx-enum">T2</span>. No client action, ever.
  </Card>

  <Card title="Per-Trade Settlement" icon="list-check">
    Opt-in. A trade reaches <span class="ofx-enum">READY\_TO\_SETTLE</span> and waits: you call [`settle`](/v3/api-reference/trade/settle-trade) to complete it at the locked rate, or [`reverse`](/v3/api-reference/trade/reverse-trade) to unwind it instead.
  </Card>
</CardGroup>

The trade webhook payload (`fx.trade.*` events) reports the organization setting as `tradeSettlementMode`; the REST `Trade` resource doesn't include it. The values are <span class="ofx-enum">AUTO</span> for Netted Settlement and <span class="ofx-enum">MANUAL</span> for Per-Trade Settlement.

## Comparison

| | Netted Settlement | Per-Trade Settlement |
| - | - | - |
| Client action after execution | None | Call `settle` or `reverse` |
| Reachable trade states | `PENDING → EXECUTED`, or `PENDING → LOCKED → EXECUTED` | `PENDING → [LOCKED →] READY_TO_SETTLE → EXECUTED \| REVERSED` |
| Unique endpoints | None | [`settle`](/v3/api-reference/trade/settle-trade), [`reverse-quote`](/v3/api-reference/trade/generate-reverse-quote), [`reverse`](/v3/api-reference/trade/reverse-trade) |
| Trade webhooks | <span class="ofx-enum">fx.trade.settled</span> | <span class="ofx-enum">fx.trade.ready\_to\_settle</span>, <span class="ofx-enum">fx.trade.settled</span>, <span class="ofx-enum">fx.trade.reversed</span> |
| Fits | OTC desks running their own book | PSPs and intermediaries settling per end-client obligation |

## Deposits and withdrawals

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.

## The fund-movement flow

```mermaid theme={"theme":{"light":"poimandres","dark":"poimandres"}}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'Inter, system-ui, sans-serif','fontSize':'13px'}}}%%
sequenceDiagram
  participant Client
  participant OpenFX
  participant Bank as Bank or 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 `withdrawableBalance` / `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) | — |
| [`GET /v3/fx/withdrawal-accounts`](/v3/api-reference/trade-settlement/list-withdrawal-accounts) | List withdrawal accounts in any status; filter with `verified` when needed | — |

## Balances

[`GET /v3/fx/balances`](/v3/api-reference/trade-settlement/list-balances) returns an organization-wide `aggregate` and one row per currency, each with a `withdrawableBalance` and a `totalBalance`. [Balances](/v3/balances) explains every field and how they differ.

For how the two balances change across a trade, see [Amounts](/v3/amounts#balance-lifecycle-available-vs-total).

## What's next

<CardGroup cols={2}>
  <Card title="Quotes" icon="https://public-assets.openfx.com/docs/icons/quotes.svg" href="/v3/quotes">
    Quote and execute FX trades, plus the full settle/reverse reference.
  </Card>

  <Card title="Trades" icon="https://public-assets.openfx.com/docs/icons/trades.svg" href="/v3/trades">
    Statuses and actions for a trade under either model.
  </Card>

  <Card title="Exposure" icon="https://public-assets.openfx.com/docs/icons/exposure.svg" href="/v3/exposure">
    See how unsettled trades count against your organization's exposure limit, under either model.
  </Card>

  <Card title="Verified accounts" icon="https://public-assets.openfx.com/docs/icons/verified-accounts.svg" href="/v3/verified-accounts">
    Register first-party withdrawal destinations before going live.
  </Card>

  <Card title="Idempotency" icon="https://public-assets.openfx.com/docs/icons/idempotency.svg" href="/v3/idempotency">
    7-day TTL on withdrawal keys; crash-safe retry pattern.
  </Card>
</CardGroup>