Get balance
GET/balance
Available, held and pending-funding balances.
Sandbox: test money only. No request moves real money.
Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_..
The authoritative figures are the ledger's, each in its own currency, and are unchanged by anything about display.
display adds an indicative equivalent of the available balance in the display currency (the workspace default for
an API key, then the declared country's currency when served, then USD), with the rates, sources and time it was
drawn from. It shows a figure only when every rate used is fresh and two independent sources agree.
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.
const response = await fetch( 'https:// sandbox-api. nasfampay. com/ v1/ balance', { 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: balance } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ balance', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, balance);} 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. 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.
). | Balance 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 |
The balance object
| Field | Description |
|---|---|
| Availableavailable · Money object · required | |
| Amountavailable. | USD, in cents. 0 to 100000000000. |
| Currencyavailable. | USD. One of USD. |
| Heldheld · Money object · required | |
| Amountheld. | USD, in cents. 0 to 100000000000. |
| Currencyheld. | USD. One of USD. |
| Pending fundingpending_ | |
| Amountpending_ | USD, in cents. 0 to 100000000000. |
| Currencypending_ | USD. One of USD. |
| Totaltotal · object | Available plus held, rounded down once from the exact units. Never includes on_hold or incoming. |
| Amounttotal. | USD, in cents. 0 to 100000000000. |
| Currencytotal. | USD. One of USD. |
| On holdon_ | Credited and not spendable yet. The same figure as pending_funding, which keeps its meaning. |
| Amounton_ | USD, in cents. 0 to 100000000000. |
| Currencyon_ | USD. One of USD. |
| Incomingincoming · BalanceIncoming object | Chain deposits seen and not yet credited, counted and summed per asset in its own unit (nanogram for GRAM). Never in available or total. |
| Countincoming. | At least 0. |
| By assetincoming. | |
| Assetincoming. | One of GRAM. |
| Countincoming. | At least 1. |
| Amount minorincoming. | Pattern ^[0-9]{1,30}$. |
| Updated atupdated_ | Format date-time. |
| Gramgram · GramBalance object | Present when the organisation holds GRAM accounts. GRAM is a deposited asset, shown in its own unit. While deposits convert to USD this is only what is held or still being spent. |
| Currencygram. | One of TON. |
| Assetgram. | One of GRAM. |
| Available nanogramgram. | An integer number of nanogram (1 GRAM = 1,000,000,000), as a string. Pattern ^(0|[1-9][0-9]{0,15})$. |
| Held nanogramgram. | An integer number of nanogram (1 GRAM = 1,000,000,000), as a string. Pattern ^(0|[1-9][0-9]{0,15})$. |
| Pending nanogramgram. | Deposits received and held for review; not spendable. |
| Estimated usdgram. | An indicative value in USD of a GRAM amount, at the newest good GRAM/USD rate (GET /v1/rates). An estimate, never a balance: GRAM stays GRAM. Null figures when no good rate is recent enough. |
| Availablegram. | |
| Amount microsgram. | Rounded down. Either shape 1: ; or shape 2: . |
| Amountgram. | USD, rounded down to the cent. Pattern ^[0-9]+\.[0-9]{2}$. |
| Usd per gramgram. | |
| Rate timegram. | Format date-time. |
| Spending currencyspending_ | What the organisation's orders are paid from. USD: USD credits, the balance every deposit converts into. TON: GRAM. It moves one way only, to USD, and never back. One of USD, TON. |
| Usdusd · UsdBalance object | USD credits, the spending balance of a USD organisation (ledger currency USD, in micro-dollars): stored obligations, never revalued. GRAM is credited here at the verified rate less the deposit spread when it is credited. These figures are the ledger's and never change with the display currency. |
| Currencyusd. | One of USD. |
| Available microsusd. | An integer number of micro-dollars (1 USD = 1,000,000), as a string. Every price is a whole number of cents. Pattern ^(0|[1-9][0-9]{0,15})$. |
| Held microsusd. | Reserved for orders in progress. |
| Pending microsusd. | Received and held for review, not yet credited and not on your balance: it cannot be spent, and becomes credited on release. |
| Availableusd. | USD, rounded down to the cent: never more than is spendable. Pattern ^[0-9]+\.[0-9]{2}$. |
| Heldusd. | Pattern ^[0-9]+\.[0-9]{2}$. |
| Pendingusd. | Pattern ^[0-9]+\.[0-9]{2}$. |
| Roundedusd. | One of down. |
| Headlineheadline · BalanceHeadline object | The one figure to show first. For a USD organisation it is its spendable USD credits, fixed. For an organisation that still spends GRAM it is the estimated value of its GRAM: is_estimate is then true, so show it with a ≈, and complete is false when no good rate exists, so the figure is 0. |
| Currencyheadline. | One of USD. |
| Amount microsheadline. | An integer number of micro-dollars (1 USD = 1,000,000), as a string. Every price is a whole number of cents. Pattern ^(0|[1-9][0-9]{0,15})$. |
| Amountheadline. | USD, rounded down to the cent. Pattern ^[0-9]+\.[0-9]{2}$. |
| Is estimateheadline. | |
| Completeheadline. | |
| Compositionheadline. | |
| Assetheadline. | USD credits (fixed, the ledger figure) or GRAM at its estimate. One of USD, GRAM. |
| Amount microsheadline. | Null for GRAM with no good rate. Either shape 1: ; or shape 2: . |
| Is estimateheadline. | |
| Activityactivity · BalanceActivity object | The newest deposits (at most 5) and the newest order charges (at most 5), as recorded. Never recalculated usage is left out for a caller who may not read orders, and deposits is empty for one who may not read transactions. |
| Depositsactivity. | |
| Usageactivity. | |
| Order IDactivity. | Pattern ^ord_[0-9A-HJKMNP-TV-Z]{26}$. |
| Stateactivity. | reserved: held for an order in progress; charged: delivered; returned: not delivered, given back. One of reserved, charged, returned. |
| Currencyactivity. | USD in micro-dollars, or TON (GRAM) in nanogram. One of USD, TON. |
| Amount minoractivity. | Pattern ^[1-9][0-9]{0,18}$. |
| Atactivity. | Format date-time. |
| Displaydisplay · object | The available balance of the organisation's spending currency (available, or gram.available_nanogram for a GRAM organisation) in the reader's display currency, indicative, at the newest rates. Every other field is unchanged. |
| Currencydisplay. | 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 bydisplay. | The member's own choice, then the workspace default, then the currency of the declared country, then USD. One of member, workspace, suggested, default. |
| Indicativedisplay. | One of true. |
| Ofdisplay. | The authoritative figure this is an equivalent of, in its ledger currency and minor unit. |
| Currencydisplay. | USD in micro-dollars, or TON (GRAM) in nanogram. One of TON, USD. |
| Amount minordisplay. | Pattern ^-?(0|[1-9][0-9]{0,30})$. |
| Showndisplay. | |
| Statedisplay. | One of fresh, stale, unavailable, same_currency. |
| Agreementdisplay. | One of agreeing, disagreeing, single_source, no_source, not_needed. |
| Amountdisplay. | Decimal in the display currency, rounded toward zero to its minor unit. Null unless shown. Pattern ^-?[0-9]+\.[0-9]{2}$. |
| Amount minordisplay. | The same in the display currency's minor unit (cents, pence). Pattern ^-?(0|[1-9][0-9]{0,30})$. |
| Per unitdisplay. | Display currency per one unit of the figure's currency, decimal, 9 places, rounded down. Null unless shown. |
| Roundingdisplay. | One of toward_zero_to_the_minor_unit. |
| Labeldisplay. | For example "Indicative, at the reference rate of 28 Oct 2026". Null unless converted and shown. |
| As ofdisplay. | The oldest source time among the rates used. Null when none is usable. Format date-time. |
| Legsdisplay. | |
| Pairdisplay. | One of GRAM/USD, USD/EUR, USD/GBP. |
| Inverteddisplay. | true when the figure is divided by the rate. |
| Statedisplay. | 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. |
| Agreementdisplay. | 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. |
| Showndisplay. | |
| Labeldisplay. | |
| Source timedisplay. | 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).
{ "available": { "amount": 1750, "currency": "USD" }, "held": { "amount": 750, "currency": "USD" }, "pending_ funding": { "amount": 0, "currency": "USD" }, "total": { "amount": 750, "currency": "USD" }, "on_ hold": { "amount": 750, "currency": "USD" }, "incoming": { "count": 0, "by_ asset": [ { "asset": "GRAM", "count": 1, "amount_ minor": "0" } ] }, "updated_ at": "2026-10-10T10:05:02Z", "gram": { "currency": "TON", "asset": "GRAM", "available_ nanogram": "0", "held_ nanogram": "0", "pending_ nanogram": "0", "estimated_ usd": { "available": true, "amount_ micros": "0", "amount": "0.00", "usd_ per_ gram": "1.500000", "rate_ time": "2026-10-10T10:05:02Z" } }, "spending_ currency": "USD", "usd": { "currency": "USD", "available_ micros": "17500000", "held_ micros": "7500000", "pending_ micros": "0", "available": "17.50", "held": "7.50", "pending": "0.00", "rounded": "down" }, "headline": { "currency": "USD", "amount_ micros": "17500000", "amount": "17.50", "is_ estimate": false, "complete": true, "composition": [ { "asset": "USD", "amount_ micros": "17500000", "is_ estimate": false } ] }, "activity": { "deposits": [ { "object": "gram_ deposit", "id": "dep_ 01K7SAMP000000000000000001", "status": "credited", "asset": "GRAM", "amount_ nanogram": "5000000000", "network": "TON", "tx_ hash": "0000000000000000000000000000000000000000000000000000000000000000", "explorer_ url": null, "sender_ masked": "string", "observed_ at": "2026-10-10T10:05:02Z", "credited_ at": "2026-10-10T10:05:02Z", "hold_ reason": null, "conversion": { "rate": { "usd_ per_ gram": "1.500000", "usd_ micros_ per_ gram": { "numerator": "1500000", "denominator": "1" }, "source_ time": "2026-10-10T10:05:02Z" }, "spread_ bps": 0, "rate_ applied": { "numerator": "1500000", "denominator": "1" }, "credited_ usd_ micros": "7500000", "converted_ at": "2026-10-10T10:05:02Z", "policy_ version": 1 } } ], "usage": [ { "order_ id": "ord_ 01K7SAMP000000000000000001", "state": "reserved", "currency": "USD", "amount_ minor": "7500000", "at": "2026-10-10T10:05:02Z" } ] }, "display": { "currency": "USD", "chosen_ by": "member", "indicative": true, "of": { "currency": "USD", "amount_ minor": "17500000" }, "shown": true, "state": "same_ currency", "agreement": "not_ needed", "amount": "17.50", "amount_ minor": "1750", "per_ unit": "1.000000000", "rounding": "toward_ zero_ to_ the_ minor_ unit", "label": null, "as_ of": null, "legs": [] }}{ "available": { "amount": 10000, "currency": "USD" }, "held": { "amount": 0, "currency": "USD" }, "pending_ funding": { "amount": 0, "currency": "USD" }, "updated_ at": "2026-10-10T10:15:00.000Z"}{ "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 | Test money, in the currency each amount names. |
| 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 reads what POST /orders will pay from. |
| 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.
