Account · Account and suppliers

List balances

Current balance for each currency the agency holds.

GET/api/v1/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.

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 --request GET \
  --url https://api.fx-port.com/api/v1/balances \
  --header 'Authorization: Bearer fxp_test_YOUR_KEY'

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");

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.

{
  "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):

{
  "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)