Skip to content

Get deposit address

GET/funding/deposit-address

Your organisation's Gram (GRAM) deposit address on the TON network.

Sandbox: test money only. No request moves real money.

Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_....

One address per organisation, allocated on the first request and never changed. It is preparing until the server has recomputed it independently from the custody key and found it unused on chain, and only then shown, in its non-bounceable form (UQ on mainnet, 0Q on testnet). Send only native GRAM on TON: tokens, NFTs and other networks are not credited. A deposit is credited once the TON network has finalised it 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/funding/deposit-addressSandbox, test key
const response = await fetch('https://sandbox-api.nasfampay.com/v1/funding/deposit-address', {  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/funding/deposit-addressSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: address } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/funding/deposit-address',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, address);} 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
OK200The deposit address. 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. ).DepositAddress 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 deposit address object

FieldDescription
Objectobject · string · requiredOne of deposit_address.
IDid · string · requiredPattern ^dad_[0-9A-HJKMNP-TV-Z]{26}$.
Assetasset · string · requiredGram, the native coin of the TON network (formerly Toncoin). Never a jetton of the same name. One of GRAM.
Networknetwork · string · requiredOne of TON, TON testnet.
Statestate · string · requiredpreparing: allocated, not yet independently verified; the address is not shown until active. One of preparing, active.
Addressaddress · string or null · requiredThe non-bounceable user-friendly form; null while preparing. Pattern ^(UQ|0Q)[A-Za-z0-9_-]{46}$.
Minimum nanogramminimum_nanogram · string · requiredSmaller deposits are recorded and need attention; they are not credited. Pattern ^[0-9]{1,19}$.
Confirmationconfirmation · string · required
Warningswarnings · array of string · required
Assetsassets · array of DepositAsset
Assetassets[].asset · stringOne of GRAM.
Availableassets[].available · booleanfalse: do not send this asset here yet; it is not credited.
Minimum minorassets[].minimum_minor · stringnanogram for GRAM. Pattern ^[0-9]{1,19}$.
Unitassets[].unit · stringOne of nanogram.
Credit ruleassets[].credit_rule · string

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
{  "object": "deposit_address",  "id": "dad_01K7SAMP000000000000000001",  "asset": "GRAM",  "network": "TON",  "state": "preparing",  "address": null,  "minimum_nanogram": "0",  "confirmation": "string",  "warnings": [    "string"  ],  "assets": [    {      "asset": "GRAM",      "available": true,      "minimum_minor": "0",      "unit": "nanogram",      "credit_rule": "string"    }  ]}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "object": "deposit_address",  "id": "dad_01K7SAMP000000000000000090",  "asset": "GRAM",  "network": "TON testnet",  "state": "preparing",  "address": null,  "minimum_nanogram": "1000000000",  "confirmation": "Credited once the TON network has finalised the transfer.",  "warnings": [    "Send only Gram (GRAM) on the TON network."  ]}
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 sandboxA test address on the TON test network: real GRAM sent to it is never credited. It answers service_unavailable while GRAM funding is switched off for the environment.
On LiveYour organisation's own address on the TON network, once it is active in Live and may receive GRAM. Until then it answers account_restricted, and service_unavailable while GRAM funding is switched off. An address offered to you from anywhere else is not ours. The same request, on the Live host with a live key, which exists only for a workspace activated for Live. See Go live.
FundingNone. This request does not touch your balance.
Status changesThe address is preparing, then active. It never changes after that.
Webhook eventsNone.

Error responses

This operation can also answer with account_restricted.

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.