Skip to content

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

HeaderValueSent
AuthorizationBearer nbk_test_...Required

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

The request in cURL, JavaScript and Python
GET /v1/balanceSandbox, test key
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);
Code for Request
GET /v1/balanceSandbox, test key
// 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

StatusMeaningBody
OK200Balance. 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 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

The balance object

FieldDescription
Availableavailable · Money object · required
Amountavailable.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencyavailable.currency · string · requiredUSD. One of USD.
Heldheld · Money object · required
Amountheld.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencyheld.currency · string · requiredUSD. One of USD.
Pending fundingpending_funding · Money object · required
Amountpending_funding.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencypending_funding.currency · string · requiredUSD. One of USD.
Totaltotal · objectAvailable plus held, rounded down once from the exact units. Never includes on_hold or incoming.
Amounttotal.amount · integerUSD, in cents. 0 to 100000000000.
Currencytotal.currency · stringUSD. One of USD.
On holdon_hold · objectCredited and not spendable yet. The same figure as pending_funding, which keeps its meaning.
Amounton_hold.amount · integerUSD, in cents. 0 to 100000000000.
Currencyon_hold.currency · stringUSD. One of USD.
Incomingincoming · BalanceIncoming objectChain deposits seen and not yet credited, counted and summed per asset in its own unit (nanogram for GRAM). Never in available or total.
Countincoming.count · integerAt least 0.
By assetincoming.by_asset · array of object
Assetincoming.by_asset[].asset · stringOne of GRAM.
Countincoming.by_asset[].count · integerAt least 1.
Amount minorincoming.by_asset[].amount_minor · stringPattern ^[0-9]{1,30}$.
Updated atupdated_at · string · requiredFormat date-time.
Gramgram · GramBalance objectPresent 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.currency · stringOne of TON.
Assetgram.asset · stringOne of GRAM.
Available nanogramgram.available_nanogram · stringAn integer number of nanogram (1 GRAM = 1,000,000,000), as a string. Pattern ^(0|[1-9][0-9]{0,15})$.
Held nanogramgram.held_nanogram · stringAn integer number of nanogram (1 GRAM = 1,000,000,000), as a string. Pattern ^(0|[1-9][0-9]{0,15})$.
Pending nanogramgram.pending_nanogram · objectDeposits received and held for review; not spendable.
Estimated usdgram.estimated_usd · EstimatedUsd objectAn 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.estimated_usd.available · boolean
Amount microsgram.estimated_usd.amount_micros · object, one of 2Rounded down. Either shape 1: ; or shape 2: .
Amountgram.estimated_usd.amount · string or nullUSD, rounded down to the cent. Pattern ^[0-9]+\.[0-9]{2}$.
Usd per gramgram.estimated_usd.usd_per_gram · string or null
Rate timegram.estimated_usd.rate_time · string or nullFormat date-time.
Spending currencyspending_currency · stringWhat 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 objectUSD 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.currency · stringOne of USD.
Available microsusd.available_micros · stringAn 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.held_micros · objectReserved for orders in progress.
Pending microsusd.pending_micros · objectReceived and held for review, not yet credited and not on your balance: it cannot be spent, and becomes credited on release.
Availableusd.available · stringUSD, rounded down to the cent: never more than is spendable. Pattern ^[0-9]+\.[0-9]{2}$.
Heldusd.held · stringPattern ^[0-9]+\.[0-9]{2}$.
Pendingusd.pending · stringPattern ^[0-9]+\.[0-9]{2}$.
Roundedusd.rounded · stringOne of down.
Headlineheadline · BalanceHeadline objectThe 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.currency · stringOne of USD.
Amount microsheadline.amount_micros · stringAn 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.amount · stringUSD, rounded down to the cent. Pattern ^[0-9]+\.[0-9]{2}$.
Is estimateheadline.is_estimate · boolean
Completeheadline.complete · boolean
Compositionheadline.composition · array of BalancePart
Assetheadline.composition[].asset · stringUSD credits (fixed, the ledger figure) or GRAM at its estimate. One of USD, GRAM.
Amount microsheadline.composition[].amount_micros · object, one of 2Null for GRAM with no good rate. Either shape 1: ; or shape 2: .
Is estimateheadline.composition[].is_estimate · boolean
Activityactivity · BalanceActivity objectThe 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.deposits · array of Deposit
Usageactivity.usage · array of UsageDeduction
Order IDactivity.usage[].order_id · stringPattern ^ord_[0-9A-HJKMNP-TV-Z]{26}$.
Stateactivity.usage[].state · stringreserved: held for an order in progress; charged: delivered; returned: not delivered, given back. One of reserved, charged, returned.
Currencyactivity.usage[].currency · stringUSD in micro-dollars, or TON (GRAM) in nanogram. One of USD, TON.
Amount minoractivity.usage[].amount_minor · stringPattern ^[1-9][0-9]{0,18}$.
Atactivity.usage[].at · stringFormat date-time.
Displaydisplay · objectThe 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.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 bydisplay.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.
Indicativedisplay.indicative · booleanOne of true.
Ofdisplay.of · objectThe authoritative figure this is an equivalent of, in its ledger currency and minor unit.
Currencydisplay.of.currency · stringUSD in micro-dollars, or TON (GRAM) in nanogram. One of TON, USD.
Amount minordisplay.of.amount_minor · stringPattern ^-?(0|[1-9][0-9]{0,30})$.
Showndisplay.shown · boolean
Statedisplay.state · stringOne of fresh, stale, unavailable, same_currency.
Agreementdisplay.agreement · stringOne of agreeing, disagreeing, single_source, no_source, not_needed.
Amountdisplay.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 minordisplay.amount_minor · string or nullThe same in the display currency's minor unit (cents, pence). Pattern ^-?(0|[1-9][0-9]{0,30})$.
Per unitdisplay.per_unit · string or nullDisplay currency per one unit of the figure's currency, decimal, 9 places, rounded down. Null unless shown.
Roundingdisplay.rounding · stringOne of toward_zero_to_the_minor_unit.
Labeldisplay.label · string or nullFor example "Indicative, at the reference rate of 28 Oct 2026". Null unless converted and shown.
As ofdisplay.as_of · string or nullThe oldest source time among the rates used. Null when none is usable. Format date-time.
Legsdisplay.legs · array of DisplayLeg
Pairdisplay.legs[].pair · stringOne of GRAM/USD, USD/EUR, USD/GBP.
Inverteddisplay.legs[].inverted · booleantrue when the figure is divided by the rate.
Statedisplay.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.
Agreementdisplay.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.
Showndisplay.legs[].shown · boolean
Labeldisplay.legs[].label · string or null
Source timedisplay.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
{  "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": []  }}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "available": {    "amount": 10000,    "currency": "USD"  },  "held": {    "amount": 0,    "currency": "USD"  },  "pending_funding": {    "amount": 0,    "currency": "USD"  },  "updated_at": "2026-10-10T10:15:00.000Z"}
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 sandboxTest money, in the currency each amount names.
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 reads what POST /orders will pay from.
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.