# List balances

> List the balance of your agency in each currency it holds.

Endpoint: `GET /balances`

Source: https://fx-port.com/docs/api/list-balances

`GET /api/v1/balances`

Requires an API key with **Read** permission; a **Read+Write** key works too.

Keep the `id` of a balance: it is the `balance_id` of the balance history. Never send `agency_id`: the agency comes from the key and an API key that sends it is refused with `agency_id_not_allowed`.

The sandbox has no balances: `data` is empty and `meta` says so (`financialOperationsEnabled` is `false`). The live example below shows the shape of a live answer with made-up amounts.

## Request

### Example request

```bash
curl https://api.fx-port.com/api/v1/balances \
  -H "Authorization: Bearer fxp_test_YOUR_KEY"
```

## Response

### 200: The balances of your agency, ordered by currency.

- `success` (boolean): `true` when the balances were returned.
- `data` (array of object): One balance per currency your agency holds, ordered by currency. Always empty in the sandbox.
  - `id` (string (uuid)): The id of the balance. Send it as `balance_id` to read its history.
  - `agency_id` (string (uuid)): The id of your agency.
  - `currency_code` (string, deprecated): Legacy name: use `currency`. The currency of the balance (ISO 4217), for example `DZD` or `EUR`. The older name of `currency`: same value, use `currency`.
  - `currency` (string): The currency of the balance (ISO 4217), for example `DZD` or `EUR`. The snake_case twin of `currency_code`, with the same value: use this name.
  - `available_balance` (number): The amount you can spend, in this currency.
  - `created_at` (string): When the balance was created: ISO 8601, UTC.
  - `updated_at` (string): When the balance last moved: ISO 8601, UTC.
- `meta` (object): Facts about the answer.
  - `agencyId` (string (uuid), deprecated): Legacy name: use `agency_id`. The id of your agency, resolved from the key. The older name of `agency_id`: same value, use `agency_id`.
  - `agency_id` (string (uuid)): The id of your agency, resolved from the key. The snake_case twin of `agencyId`, with the same value: use this name.
  - `environment` (string): The environment of the key that made the call: `sandbox` for fxp_test_ keys, `live` for fxp_live_ keys. Present in every JSON body. One of `sandbox`, `live`.
  - `financialOperationsEnabled` (boolean, deprecated): Legacy name: use `financial_operations_enabled`. Sandbox only, always `false`: the sandbox has no balance ledger. The older name of `financial_operations_enabled`: same value, use `financial_operations_enabled`.
  - `financial_operations_enabled` (boolean): Sandbox only, always `false`: the sandbox has no balance ledger. The snake_case twin of `financialOperationsEnabled`, with the same value: use this name.
  - `message` (string): Sandbox only: why `data` is empty.

```json
{
  "environment": "sandbox",
  "success": true,
  "data": [],
  "meta": {
    "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "environment": "sandbox",
    "financialOperationsEnabled": false,
    "financial_operations_enabled": false,
    "message": "Sandbox bookings do not debit live balances; no sandbox balance ledger is exposed."
  }
}
```

## Errors

| Status | Code | Example message |
| --- | --- | --- |
| 400 | `agency_id_not_allowed` | External API keys resolve agency_id automatically; do not send agency_id as a query parameter. |
| 503 | `service_overloaded` | The service is temporarily overloaded; retry after the time given in the Retry-After header. |

See [Errors](https://fx-port.com/docs/errors.md) for every code and how to react.

## Related guides

- [List balances](https://fx-port.com/docs/account/balances.md)