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

# Balances

> How to read the balances response: the org-wide aggregate, the per-currency rows, and what moves each amount.

[`GET /v3/fx/balances`](/v3/api-reference/trade-settlement/list-balances) returns your organization's funds in two parts: an `aggregate` for the whole organization, and one row per currency in `balances`. Each part answers a different question, and each carries amounts that mean different things. Read this page before you gate a trade or withdrawal on a balance.

<Note title="Why this matters">
  `totalBalance` and `withdrawableBalance` are not the same number, and neither
  one is "what you can trade". Check `withdrawableBalance` for the currency you
  are selling, and use `aggregate` as the ceiling across all currencies.
</Note>

## The response

A successful response wraps the balances in `data`. There is no pagination: the response is the complete set, one row per currency you hold.

```bash cURL theme={"theme":{"light":"poimandres","dark":"poimandres"}}
curl https://api.openfx.com/v3/fx/balances \
  -H "Authorization: Bearer $OPENFX_JWT" \
  -H "X-Request-Signature: $OPENFX_SIGNATURE"
```

```json theme={"theme":{"light":"poimandres","dark":"poimandres"}}
{
  "aggregate": {
    "currency": "USD",
    "withdrawableBalance": "85000.00"
  },
  "balances": [
    {
      "currency": "USD",
      "withdrawableBalance": "50000.00",
      "totalBalance": "60000.00"
    },
    {
      "currency": "USDC",
      "withdrawableBalance": "25000.00",
      "totalBalance": "25000.00"
    },
    {
      "currency": "EUR",
      "withdrawableBalance": "0",
      "totalBalance": "-1200.50"
    }
  ]
}
```

Amounts are decimal strings. Parse them as decimals, never as floats. See [Amounts](/v3/amounts).

## Aggregate

`aggregate` is your organization's net equity across every currency, converted to USD. It is the ceiling on what you can withdraw in total.

| Field | Type | Meaning |
| - | - | - |
| `currency` | string | The currency `withdrawableBalance` is denominated in. Always <span class="ofx-enum">USD</span> today |
| `withdrawableBalance` | decimal string | Net equity in USD. Never negative: it is `0` when your net position is negative |

Read `aggregate` rather than deriving it. It is converted across currencies by OpenFX, so adding the per-currency rows yourself will not reproduce it.

## Per-currency balances

Each entry in `balances` describes one currency you hold.

| Field | Type | Meaning |
| - | - | - |
| `currency` | string | The currency both amounts are denominated in |
| `withdrawableBalance` | decimal string | Available now to withdraw or trade. Never negative |
| `totalBalance` | decimal string | Full ledger balance, including amounts reserved for pending withdrawals and trades. Can be negative |

### Withdrawable and total

The two amounts relate in one of three ways.

| Situation | `withdrawableBalance` | `totalBalance` | Why |
| - | - | - | - |
| Nothing pending | Equal to `totalBalance` | Zero or positive | All of the balance is available |
| Amounts reserved | Less than `totalBalance` | Positive | The difference is held for pending withdrawals or trades |
| You owe a settlement | `0` | Negative | The currency is in deficit |

In the example above, USD shows `50000.00` withdrawable of `60000.00` total, so `10000.00` is reserved. EUR shows a negative total with `0` withdrawable, meaning the organization owes a settlement in EUR.

A negative `totalBalance` in one currency does not make the whole response negative. `aggregate` nets your currencies, so check it separately.

## What changes a balance

| Event | Effect |
| - | - |
| A [deposit](/v3/deposits) reaches <span class="ofx-enum">COMPLETED</span> | Credits the deposited currency |
| A [trade](/v3/trades) reaches <span class="ofx-enum">EXECUTED</span> | Debits the sell currency and credits the buy currency |
| A trade is [reversed](/v3/trades#reverse-a-trade) | Applies `reversalDetails.differentialAmount` in `reversalDetails.currency`, in the `direction` given |
| A [withdrawal](/v3/withdrawals) is pending | Holds the amount in `totalBalance` and out of `withdrawableBalance` |

## Check a balance before you act

Balances are real-time, so the response is a snapshot. Two checks use it.

* **Before a trade.** Compare the sell amount against `withdrawableBalance` for the sell currency. OpenFX checks the sell-side balance at execution, and a shortfall returns `409` <span class="ofx-enum">TRADE\_INSUFFICIENT\_BALANCE</span> with `requiredAmount` and `availableAmount` in `error.details`.
* **Before a withdrawal.** Compare the amount against `withdrawableBalance` for that currency. A shortfall returns `409` <span class="ofx-enum">WITHDRAWAL\_INSUFFICIENT\_BALANCE</span>.

A balance can change between your read and your write, so treat the check as a guard and handle the error on the write.

To reconcile, re-read balances when a [deposit](/v3/webhooks/deposits/deposit-completed) or [trade](/v3/webhooks/trades/trade-settled) webhook arrives rather than polling on a timer.

## Common mistakes

* **Gating on `totalBalance`.** It includes reserved amounts. Use `withdrawableBalance` to decide what you can spend.
* **Summing the rows to get the aggregate.** The rows are in different currencies. Read `aggregate`.
* **Treating a negative `totalBalance` as an error.** It means you owe a settlement in that currency. `withdrawableBalance` is `0` for it.
* **Expecting a row for every currency.** The response lists only currencies you hold.
* **Parsing amounts as floats.** Use a decimal type.

## What's next

<CardGroup cols={2}>
  <Card title="Trades" icon="https://public-assets.openfx.com/docs/icons/trades.svg" href="/v3/trades">
    When a trade moves funds, and what you can do while it waits.
  </Card>

  <Card title="Settlement models" icon="https://public-assets.openfx.com/docs/icons/settlement-models.svg" href="/v3/settlement-models">
    Deposits, balances, and withdrawals in one flow.
  </Card>

  <Card title="Exposure" icon="https://public-assets.openfx.com/docs/icons/exposure.svg" href="/v3/exposure">
    Exposure-limit usage, separate from your balances.
  </Card>

  <Card title="Amounts" icon="https://public-assets.openfx.com/docs/icons/amounts.svg" href="/v3/amounts">
    Decimal strings and precision rules.
  </Card>
</CardGroup>