Reference · Balances

Read a balance snapshot

Read the current balance for an account, endpoint, and holding at the moment of the read.

GET/v1/balances/current

Authorization: Bearer ak_test_… · Application API key

Try it

This read needs refs from objects you hold; the docs' own refs live in the exhibition, not your bench. Compose it in the playground against your own world.

Key capabilities

BalanceSnapshotRead

Parameters

accountRefquery · required

endpointRefquery · required

holdingRefquery · optional

Sharp edges

A snapshot is a point-in-time read, not a subscription. Re-read after a transfer reaches a terminal stage.

Wire receipt

Captured from the real gateway by the scenario suite; nothing here is composed by hand.

The balance is derived from the record, not stored beside it; the credit you simulated is now visible value.

Request

GET /v1/balances/current?accountRef=f420a7a0-db4c-39e4-b9de-a76aa76a1ea7&endpointRef=14fd5416-ef87-3487-9132-2c49f5884884&holdingRef=018f605c-ef4d-31a0-87be-60ac7467610c
Authorization: Bearer ak_test_…

Response · 200

{
  "status": 200,
  "body": {
    "value": {
      "accountRef": "f420a7a0-db4c-39e4-b9de-a76aa76a1ea7",
      "endpointRef": "14fd5416-ef87-3487-9132-2c49f5884884",
      "holdingBalances": [
        {
          "holdingRef": "018f605c-ef4d-31a0-87be-60ac7467610c",
          "valueUnit": {
            "kind": "fiat",
            "currency": "NGN"
          },
          "settledMinorUnits": "2500",
          "availableMinorUnits": "2500",
          "activeReservedMinorUnits": "0",
          "settledProjectionRef": "cac10249-8684-5e62-8e1f-b27812e23f65",
          "availableProjectionRef": "368f838d-4927-58f9-9022-17a2e03e3843",
          "activeReservationRefs": [],
          "projectionState": "Projected"
        }
      ],
      "projectionState": "Projected"
    },
    "freshness": "Current",
    "visibility": "Full",
    "evidence": []
  },
  "evidence": []
}

captured 2026-07-13 · gateway 0.1.0 · First credit · Read the balance

generated from openapi.json · gateway 0.1.0 · sandbox