# List balances

> Current balance for each currency the agency holds.

Endpoint: `GET /api/v1/balances`

Source: https://fx-port.com/docs/account/balances

`GET /api/v1/balances`

**Permission:** Read

Returns the balance of your agency in each currency it holds, ordered by currency code. Keep the `id` of each
balance: it is the `balance_id` of the [balance history](https://fx-port.com/docs/account/balance-history.md).

Never send `agency_id`: the agency comes from the key, and an API key that sends it is refused with
`400 agency_id_not_allowed`.

**Sandbox:** the sandbox has no balances. `data` is empty and `meta` says so (see below).

## Request example


**cURL**

~~~bash
curl --request GET \
  --url https://api.fx-port.com/api/v1/balances \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY'
~~~

**Node.js**

~~~js
const response = await fetch("https://api.fx-port.com/api/v1/balances", {
  headers: { Authorization: "Bearer fxp_test_YOUR_KEY" },
});
const { data: balances } = await response.json();
const dzd = balances.find((balance) => balance.currency_code === "DZD");
~~~

**Python**

~~~python
import requests

response = requests.get(
    "https://api.fx-port.com/api/v1/balances",
    headers={"Authorization": "Bearer fxp_test_YOUR_KEY"},
    timeout=30,
)
balances = response.json()["data"]
~~~


## Response example

An agency can hold several currencies. Each row has its own `id`. These amounts are examples: the values of a live
answer are your own.

~~~json
{
  "environment": "live",
  "success": true,
  "data": [
    {
      "id": "db002f7a-c136-4f32-b19d-38a2542f2af9",
      "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "currency_code": "DZD",
      "currency": "DZD",
      "available_balance": 412500.0,
      "created_at": "2025-08-22T10:24:06.533800+00:00",
      "updated_at": "2026-10-17T04:45:15.697817+00:00"
    },
    {
      "id": "a71c9e34-2b18-40df-9c77-6b0a1f2e5d40",
      "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
      "currency_code": "EUR",
      "currency": "EUR",
      "available_balance": 18750.5,
      "created_at": "2025-08-22T10:24:06.533800+00:00",
      "updated_at": "2026-10-16T22:10:03.120400+00:00"
    }
  ],
  "meta": {
    "agencyId": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "agency_id": "0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
    "environment": "live"
  }
}
~~~

The same call with a **sandbox** key answers (an envelope with an empty list, not a bare array):

~~~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."
  }
}
~~~

## Field reference

| Field | Description |
|---|---|
| `id` | The balance UUID: send it as `balance_id` to the history endpoint |
| `agency_id` | Your agency UUID |
| `currency_code` | ISO 4217 currency code, for example `DZD`, `EUR`, `USD`. `currency` carries the same value (the name the other endpoints use) |
| `available_balance` | The amount you can spend, in this currency |
| `created_at` | When the balance row was created |
| `updated_at` | When the balance last moved |
| `meta.agencyId` | Your agency UUID. `meta.agency_id` carries the same value |
| `meta.financialOperationsEnabled` | Sandbox only, always `false`. `meta.financial_operations_enabled` carries the same value |
| `meta.message` | Sandbox only: why `data` is empty |

## Errors

| HTTP | `code` | Cause |
|---|---|---|
| `400` | `agency_id_not_allowed` | An API key sent `agency_id` |
| `401` | `authentication_required`, `invalid_api_key` | Missing or invalid API key |
| `429` | `rate_limit_exceeded` | Over 6,000 requests per minute for this key |
| `503` | `service_overloaded` | The service is shedding load for a moment (its database pool is full). Nothing was read: retry after the seconds in `Retry-After` (2 to 5) |