Reference · Balances

Read balance activity

Read the committed ledger postings behind one exact account, endpoint, and holding balance.

GET/v1/balances/activity

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

BalancePostedActivityRead

Parameters

afterLineRefquery · optional

holdingRefquery · required

sortDirectionquery · optional

accountRefquery · required

afterReceiptRefquery · optional

pageSizequery · optional

afterPostedAtquery · optional

endpointRefquery · required

Sharp edges

Treat afterPostedAt, afterReceiptRef, afterLineRef, and sortDirection as one cursor. Resume with every value returned by nextCursor; never mix cursor parts or change direction mid-page.
This is balance provenance, not transfer history, statements, search, export, or an event subscription.

Wire receipt

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

Read the committed posting behind the balance; the same account, endpoint, and holding now carry auditable ledger provenance.

Request

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

Response · 200

{
  "status": 200,
  "body": {
    "value": {
      "accountRef": "f420a7a0-db4c-39e4-b9de-a76aa76a1ea7",
      "endpointRef": "14fd5416-ef87-3487-9132-2c49f5884884",
      "holdingRef": "018f605c-ef4d-31a0-87be-60ac7467610c",
      "entries": [
        {
          "postedAt": "2026-07-13T20:08:19.628931Z",
          "receiptRef": "8c682fc2-a2f6-5394-9981-63f4bb4eae54",
          "journalRef": "849f5118-4fc8-55fb-81a4-799ef3f0c4c8",
          "lineRef": "baf04a4a-f52c-50e5-b4f4-a74de7ddd53e",
          "journalKind": "transfer_settlement",
          "postingSide": "credit",
          "balanceEffect": "increase",
          "amountMinorUnits": "2500",
          "valueUnit": {
            "kind": "fiat",
            "currency": "NGN"
          },
          "ledgerPartition": "customer_liability",
          "ledgerNormalSide": "credit_normal"
        }
      ],
      "sortDirection": "newest_first"
    },
    "freshness": "Current",
    "visibility": "Full",
    "evidence": []
  },
  "evidence": []
}

captured 2026-07-13 · gateway 0.1.0 · First credit · Trace the credit

generated from openapi.json · gateway 0.1.0 · sandbox