Skip to content

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

HeaderValueSent
AuthorizationBearer nbk_test_...Required

No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.

Parameters

FieldDescription
Limitlimit · query integer1 to 100. Default 20.
Cursorcursor · query stringUp to 256 characters.
The request in cURL, JavaScript and Python
GET /v1/balance/transactionsSandbox, test key
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);
Code for Request
GET /v1/balance/transactionsSandbox, test key
// 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

StatusMeaningBody
OK200Balance 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 requests429Too 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 statusdefaultError (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

FieldDescription
Has morehas_more · boolean · required
Next cursornext_cursor · string or null · required
Datadata · array of BalanceTransaction · required
IDdata[].id · string · requiredPattern ^btx_[0-9A-HJKMNP-TV-Z]{26}$.
Typedata[].type · string · requiredOne of funding_credit, order_reserve, order_capture, order_release, adjustment, reversal, gram_conversion.
Amountdata[].amount · SignedMoney object · requiredThe signed change to the available balance. An order_capture moves held funds and shows 0.
Amountdata[].amount.amount · integer · required-100000000000 to 100000000000.
Currencydata[].amount.currency · string · requiredOne of USD.
Available afterdata[].available_after · Money object · required
Amountdata[].available_after.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencydata[].available_after.currency · string · requiredUSD. One of USD.
Amount microsdata[].amount_micros · stringUSD: the exact change in micro-dollars (amount is it in cents, toward zero). Pattern ^-?(0|[1-9][0-9]{0,18})$.
Available after microsdata[].available_after_micros · stringUSD: the exact available balance after, in micro-dollars. Pattern ^(0|[1-9][0-9]{0,18})$.
Order IDdata[].order_id · string or null
Funding IDdata[].funding_id · string or null
Created atdata[].created_at · string · requiredFormat date-time.
Displaydata[].display · objectamount 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[].display.currency · stringA 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[].display.chosen_by · stringThe member's own choice, then the workspace default, then the currency of the declared country, then USD. One of member, workspace, suggested, default.
Indicativedata[].display.indicative · booleanOne of true.
Ofdata[].display.of · objectThe authoritative figure this is an equivalent of, in its ledger currency and minor unit.
Currencydata[].display.of.currency · stringUSD in micro-dollars, or TON (GRAM) in nanogram. One of TON, USD.
Amount minordata[].display.of.amount_minor · stringPattern ^-?(0|[1-9][0-9]{0,30})$.
Showndata[].display.shown · boolean
Statedata[].display.state · stringOne of fresh, stale, unavailable, same_currency.
Agreementdata[].display.agreement · stringOne of agreeing, disagreeing, single_source, no_source, not_needed.
Amountdata[].display.amount · string or nullDecimal in the display currency, rounded toward zero to its minor unit. Null unless shown. Pattern ^-?[0-9]+\.[0-9]{2}$.
Amount minordata[].display.amount_minor · string or nullThe same in the display currency's minor unit (cents, pence). Pattern ^-?(0|[1-9][0-9]{0,30})$.
Per unitdata[].display.per_unit · string or nullDisplay currency per one unit of the figure's currency, decimal, 9 places, rounded down. Null unless shown.
Roundingdata[].display.rounding · stringOne of toward_zero_to_the_minor_unit.
Labeldata[].display.label · string or nullFor example "Indicative, at the reference rate of 28 Oct 2026". Null unless converted and shown.
As ofdata[].display.as_of · string or nullThe oldest source time among the rates used. Null when none is usable. Format date-time.
Legsdata[].display.legs · array of DisplayLeg
Pairdata[].display.legs[].pair · stringOne of GRAM/USD, USD/EUR, USD/GBP.
Inverteddata[].display.legs[].inverted · booleantrue when the figure is divided by the rate.
Statedata[].display.legs[].state · stringfresh: 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[].display.legs[].agreement · stringagreeing: 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[].display.legs[].shown · boolean
Labeldata[].display.legs[].label · string or null
Source timedata[].display.legs[].source_time · string or nullFormat date-time.

Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).

Every kind of response
200 OKSynthetic sandbox data
{  "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}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "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}
Error
JSON
429 Too Many RequestsSynthetic sandbox data
{  "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
AuthenticationYour key as a bearer token in the Authorization header: a nbk_test_ key on the sandbox host.
IdempotencyNot needed: a GET changes nothing, so it is safe to send again.
In the sandboxServed, on your own test records.
On LiveThe same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
FundingNone. It lists each order_reserve, order_capture and order_release with its order_id.
Status changesNone.
Webhook eventsNone.

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.