List balance transactions
GET/balance/transactions
Every movement on the balance.
Sandbox: test money only. No request moves real money.
Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_..
Request
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.
Parameters
| Field | Description |
|---|---|
| Limitlimit · query integer | 1 to 100. Default 20. |
| Cursorcursor · query string | Up to 256 characters. |
const response = await fetch( 'https:// sandbox-api. nasfampay. com/ v1/ balance/ transactions', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, },});if ( !response. ok) { const problem = await response. json(); throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}const result = await response. json();console. log( response. status, result);// npm install axiosimport axios from 'axios';try { const { status, data: transactions } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ balance/ transactions', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, transactions);} catch ( error) { if ( !axios. isAxiosError( error) || !error. response) throw error; const problem = error. response. data; throw new Error( `${problem. status} ${problem. code}: ${problem. title} ( request ${problem. request_ id})`);}Responses
| Status | Meaning | Body |
|---|---|---|
| OK200 | Balance transactions, newest first. Headers: RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>.
), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent.
). | object |
| Too many requests429 | Too many requests (rate_limited), or your queued orders are at your cap (queue_limit). A bucket that cannot be read at once because of contention is answered here too, never waited on. Honour Retry-After.
. Headers: Request-Id, Retry-After (seconds to wait before retrying), RateLimit (draft-ietf-httpapi-ratelimit-headers-11. the same buckets, each "<bucket>";r=<whole requests remaining, never negative>;t=<seconds until the quota is fully available again>.
), RateLimit-Policy (draft-ietf-httpapi-ratelimit-headers-11. a structured field list with one item per bucket the request drew on (orders, quotes, quotes_daily, reads, webhooks, lookups, lookups_org, lookups_daily), each "<bucket>";q=<quota>;w=<window seconds>. no partition key (pk) is sent.
). | Problem object |
| Any other statusdefault | Error (RFC 9457). A 503 service_unavailable with Retry-After means the request was not processed: the rate limiter or the database could not answer, and the API refuses rather than serve unlimited (reads included). For a money-moving operation, retrying with the same Idempotency-Key is always safe.
. Headers: Request-Id, Retry-After (on 429 and some 503 responses). | Problem object |
Fields of the 200 body
| Field | Description |
|---|---|
| Has morehas_ | |
| Next cursornext_ | |
| Datadata · array of BalanceTransaction · required | |
| IDdata[]. | Pattern ^btx_[0-9A-HJKMNP-TV-Z]{26}$. |
| Typedata[]. | One of funding_credit, order_reserve, order_capture, order_release, adjustment, reversal, gram_conversion. |
| Amountdata[]. | The signed change to the available balance. An order_capture moves held funds and shows 0. |
| Amountdata[]. | -100000000000 to 100000000000. |
| Currencydata[]. | One of USD. |
| Available afterdata[]. | |
| Amountdata[]. | USD, in cents. 0 to 100000000000. |
| Currencydata[]. | USD. One of USD. |
| Amount microsdata[]. | USD: the exact change in micro-dollars (amount is it in cents, toward zero). Pattern ^-?(0|[1-9][0-9]{0,18})$. |
| Available after microsdata[]. | USD: the exact available balance after, in micro-dollars. Pattern ^(0|[1-9][0-9]{0,18})$. |
| Order IDdata[]. | |
| Funding IDdata[]. | |
| Created atdata[]. | Format date-time. |
| Displaydata[]. | amount in the reader's display currency at the display rates in force at created_at, never recalculated: a later rate never changes it, and a change of display currency changes only the currency it is looked up in. |
| Currencydata[]. | A currency a figure may be shown in, indicatively (0300). Display only: never a balance, a price, a quote, a charge or a settlement. The served list is the server's configuration; a client ignores a value it does not know. One of USD, EUR, GBP. |
| Chosen bydata[]. | The member's own choice, then the workspace default, then the currency of the declared country, then USD. One of member, workspace, suggested, default. |
| Indicativedata[]. | One of true. |
| Ofdata[]. | The authoritative figure this is an equivalent of, in its ledger currency and minor unit. |
| Currencydata[]. | USD in micro-dollars, or TON (GRAM) in nanogram. One of TON, USD. |
| Amount minordata[]. | Pattern ^-?(0|[1-9][0-9]{0,30})$. |
| Showndata[]. | |
| Statedata[]. | One of fresh, stale, unavailable, same_currency. |
| Agreementdata[]. | One of agreeing, disagreeing, single_source, no_source, not_needed. |
| Amountdata[]. | Decimal in the display currency, rounded toward zero to its minor unit. Null unless shown. Pattern ^-?[0-9]+\.[0-9]{2}$. |
| Amount minordata[]. | The same in the display currency's minor unit (cents, pence). Pattern ^-?(0|[1-9][0-9]{0,30})$. |
| Per unitdata[]. | Display currency per one unit of the figure's currency, decimal, 9 places, rounded down. Null unless shown. |
| Roundingdata[]. | One of toward_zero_to_the_minor_unit. |
| Labeldata[]. | For example "Indicative, at the reference rate of 28 Oct 2026". Null unless converted and shown. |
| As ofdata[]. | The oldest source time among the rates used. Null when none is usable. Format date-time. |
| Legsdata[]. | |
| Pairdata[]. | One of GRAM/USD, USD/EUR, USD/GBP. |
| Inverteddata[]. | true when the figure is divided by the rate. |
| Statedata[]. | fresh: every source used is within its own freshness window. stale: one is older than that but not yet dropped. unavailable: no source is usable. Only fresh and agreeing is ever shown as a figure. One of fresh, stale, unavailable. |
| Agreementdata[]. | agreeing: at least two independent sources, every one within the pair's tolerance of the primary. A single source or a disagreement shows no figure. One of agreeing, disagreeing, single_source, no_source. |
| Showndata[]. | |
| Labeldata[]. | |
| Source timedata[]. | Format date-time. |
Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).
{ "data": [ { "id": "btx_ 01K7SAMP000000000000000001", "type": "order_ reserve", "amount": { "amount": -750, "currency": "USD" }, "available_ after": { "amount": 1750, "currency": "USD" }, "amount_ micros": "-7500000", "available_ after_ micros": "17500000", "order_ id": "ord_ 01K7SAMP000000000000000001", "funding_ id": null, "created_ at": "2026-10-10T10:05:02Z", "display": { "currency": "USD", "chosen_ by": "member", "indicative": true, "of": { "currency": "USD", "amount_ minor": "-7500000" }, "shown": true, "state": "same_ currency", "agreement": "not_ needed", "amount": "-7.50", "amount_ minor": "-750", "per_ unit": "1.000000000", "rounding": "toward_ zero_ to_ the_ minor_ unit", "label": null, "as_ of": null, "legs": [] } } ], "has_ more": false, "next_ cursor": null}{ "data": [ { "id": "btx_ 01K7SAMP000000000000000091", "type": "order_ reserve", "amount": { "amount": -75, "currency": "USD" }, "available_ after": { "amount": 9925, "currency": "USD" }, "order_ id": "ord_ 01K7SAMP000000000000000090", "funding_ id": null, "created_ at": "2026-10-10T10:15:02.000Z" }, { "id": "btx_ 01K7SAMP000000000000000090", "type": "funding_ credit", "amount": { "amount": 10000, "currency": "USD" }, "available_ after": { "amount": 10000, "currency": "USD" }, "order_ id": null, "funding_ id": "fnd_ 01K7SAMP000000000000000090", "created_ at": "2026-10-10T10:14:00.000Z" } ], "has_ more": false, "next_ cursor": null}{ "type": "about:blank", "title": "Too many requests", "status": 429, "code": "rate_ limited", "category": "rate_ limit", "detail": "Too many requests. Retry after the time in Retry-After. ", "param": null, "request_ id": "req_ 01K7SAMP000000000000000090"}How it behaves
| What to expect | |
|---|---|
| Authentication | Your key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host. |
| Idempotency | Not needed: a GET changes nothing, so it is safe to send again. |
| In the sandbox | Served, on your own test records. |
| On Live | The same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live. |
| Funding | None. It lists each order_reserve, order_capture and order_release with its order_id. |
| Status changes | None. |
| Webhook events | None. |
Error responses
Any request can answer with invalid_request, invalid_api_key, key_expired, key_environment_mismatch, insufficient_scope, rate_limited, service_unavailable, internal_error. Errors says what to do about each one.
