API reference

List balances

GET/balances

Returns one balance per currency wallet. In the Sandbox, every organization starts with simulated test funds; these are flagged with test_data: true and have no monetary value. Live balances are unavailable until a provider is authorized.

Required scope: balances:read
Idempotency-Key: Not used
Environments: Sandbox and Live

Example request

curl "https://api.gloresend.com/sandbox/v1/balances" \
  -H "Authorization: Bearer $GLORESEND_TEST_KEY"

Response · 200

200 · application/json

{
  "object": "list",
  "data": [
    {
      "object": "balance",
      "currency": "XOF",
      "available": 1000000,
      "reserved": 0,
      "total": 1000000,
      "test_data": true
    }
  ]
}

Response fields

objectenumrequired
"list"
dataarray of objectrequired
data[].objectenumrequired
"balance"
data[].currencyenumrequired
ISO 4217 currency code.
"USD", "EUR", "GBP", "XOF", "XAF", "NGN", "GHS", "KES"
data[].availableintegerrequired
Funds that can be used for new transfers, in minor units.
data[].reservedintegerrequired
Funds held for transfers that are still processing, in minor units.
data[].totalintegerrequired
available + reserved, in minor units.
data[].test_databooleanrequired
true for every Sandbox object. Sandbox balances are simulated and have no monetary value.

Errors

401authentication_requiredNo credentials were supplied. Send Authorization: Bearer <api key>.
401invalid_api_keyThe API key is unknown, revoked or expired.
401environment_mismatchThe API key belongs to a different environment than the base URL you called. Sandbox keys (gs_test_) only work against the Sandbox base URL, Live keys (gs_live_) only against the Live base URL.
429rate_limitedToo many requests. Wait for the number of seconds in the Retry-After header.
403insufficient_scopeThe API key does not have the scope required for this endpoint.
503live_operations_disabledLive money movement is not enabled on this deployment. No provider has been authorized yet.