Account · Balances

List balances

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

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.

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

Response200

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

Response200

{
  "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,
      "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"
  }
}

Request

This endpoint takes no parameters.

Response

200The balances of your agency, ordered by currency.

successboolean

true when the balances were returned.

dataarray of object

One balance per currency your agency holds, ordered by currency. Always empty in the sandbox.

ShowHide 7 attributes

idstring (uuid)

The id of the balance. Send it as balance_id to read its history.

agency_idstring (uuid)

The id of your agency.

currency_codestringdeprecated

Legacy name, still accepted. Use currency instead.

The currency of the balance (ISO 4217), for example DZD or EUR. The older name of currency: same value, use currency.

currencystring

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_balancenumber

The amount you can spend, in this currency.

created_atstring

When the balance was created: ISO 8601, UTC.

updated_atstring

When the balance last moved: ISO 8601, UTC.

metaobject

Facts about the answer.

ShowHide 6 attributes

agencyIdstring (uuid)deprecated

Legacy name, still accepted. Use agency_id instead.

The id of your agency, resolved from the key. The older name of agency_id: same value, use agency_id.

agency_idstring (uuid)

The id of your agency, resolved from the key. The snake_case twin of agencyId, with the same value: use this name.

environmentstring

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.

financialOperationsEnabledbooleandeprecated

Legacy name, still accepted. Use financial_operations_enabled instead.

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_enabledboolean

Sandbox only, always false: the sandbox has no balance ledger. The snake_case twin of financialOperationsEnabled, with the same value: use this name.

messagestring

Sandbox only: why data is empty.

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.

The shape of the error body depends on the endpoint. See Errors for every shape and code.

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

{ "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, "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" } }

Response

200The balances of your agency, ordered by currency.

successboolean

true when the balances were returned.

dataarray of object

One balance per currency your agency holds, ordered by currency. Always empty in the sandbox.

ShowHide 7 attributes

idstring (uuid)

The id of the balance. Send it as balance_id to read its history.

agency_idstring (uuid)

The id of your agency.

currency_codestringdeprecated

Legacy name, still accepted. Use currency instead.

The currency of the balance (ISO 4217), for example DZD or EUR. The older name of currency: same value, use currency.

currencystring

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_balancenumber

The amount you can spend, in this currency.

created_atstring

When the balance was created: ISO 8601, UTC.

updated_atstring

When the balance last moved: ISO 8601, UTC.

metaobject

Facts about the answer.

ShowHide 6 attributes

agencyIdstring (uuid)deprecated

Legacy name, still accepted. Use agency_id instead.

The id of your agency, resolved from the key. The older name of agency_id: same value, use agency_id.

agency_idstring (uuid)

The id of your agency, resolved from the key. The snake_case twin of agencyId, with the same value: use this name.

environmentstring

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.

financialOperationsEnabledbooleandeprecated

Legacy name, still accepted. Use financial_operations_enabled instead.

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_enabledboolean

Sandbox only, always false: the sandbox has no balance ledger. The snake_case twin of financialOperationsEnabled, with the same value: use this name.

messagestring

Sandbox only: why data is empty.

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.

The shape of the error body depends on the endpoint. See Errors for every shape and code.

Request

Response

Errors

Related guides

Request

Response

Errors

Related guides