Skip to content

Create sandbox gram deposit

POST/sandbox/funding/depositsChanges your balance

Simulate a GRAM deposit to your address (sandbox host only; 404 in production).

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

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

Synthetic money, on no chain. The deposit is judged by the same rules as a real one (below the minimum it needs attention and is not credited), then booked by the same journal. A retry with the same Idempotency-Key returns the original deposit and credits nothing.

Careful. This operation changes your balance, which is synthetic money in the sandbox and real money on live. The Idempotency-Key header is required and is bound permanently to the operation it creates; reuse it on every retry of the same request. See Idempotency and safe retries.

Request

HeaderValueSent
AuthorizationBearer nbk_test_...Required
Content-Typeapplication/jsonRequired
Idempotency-Key3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0dRequired

Parameters

FieldDescription
Idempotency keyIdempotency-Key · header string · requiredBound permanently to the operation it created (an order, a simulated funding). Reuse it on every retry of the same request. Pattern ^[A-Za-z0-9_-]{16,64}$.

Body

Unknown fields are rejected.

FieldDescription
Amount nanogramamount_nanogram · string · requirednanoGRAM: 1 to 1,000 GRAM (1000000000000) per simulated deposit. Pattern ^[1-9][0-9]{0,12}$.
The request in cURL, JavaScript and Python
POST /v1/sandbox/funding/depositsSandbox, test keyIdempotency-Key required
// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');const response = await fetch('https://sandbox-api.nasfampay.com/v1/sandbox/funding/deposits', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,    'Content-Type': 'application/json',    'Idempotency-Key': idempotencyKey,  },  body: JSON.stringify({ amount_nanogram: '5000000000' }),});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
POST /v1/sandbox/funding/depositsSandbox, test key
// npm install axiosimport axios from 'axios';// One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.const idempotencyKey = process.env.IDEMPOTENCY_KEY;if (!idempotencyKey) throw new Error('Set IDEMPOTENCY_KEY once for this purchase (a new UUID) and keep it for every retry');try {  const { status, data: deposit } = await axios.post(    'https://sandbox-api.nasfampay.com/v1/sandbox/funding/deposits',    { amount_nanogram: '5000000000' },    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,        'Idempotency-Key': idempotencyKey,      },    },  );  console.log(status, deposit);} 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
OK200Replay of an earlier request with the same Idempotency-Key. Nothing new is credited. 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. ), Idempotent-Replayed.GramDeposit object
Created201Simulated deposit, waiting for its booking. 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. ).GramDeposit object
Content too large413The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id.Problem 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 gram deposit object

FieldDescription
Objectobject · string · requiredOne of gram_deposit.
IDid · string · requiredPattern ^dep_[0-9A-HJKMNP-TV-Z]{26}$.
Statusstatus · string · requiredconfirming: seen, not yet finalised and confirmed by two sources; on_hold: received and held for review, not yet credited and not on your balance: it cannot be spent, shows only in pending_nanogram, and becomes credited on release; needs_attention: not native GRAM, below the minimum, or sources disagree. Tolerate new values. One of confirming, credited, on_hold, needs_attention.
Assetasset · string · requiredOne of GRAM.
Amount nanogramamount_nanogram · string · requiredPattern ^[0-9]{1,19}$.
Networknetwork · string · requiredOne of TON, TON testnet, simulated.
Tx hashtx_hash · string · requiredPattern ^[0-9a-f]{64}$.
Explorer URLexplorer_url · string or null · requiredFormat uri.
Sender maskedsender_masked · string · required
Observed atobserved_at · string · requiredFormat date-time.
Credited atcredited_at · string or null · requiredFormat date-time.
Hold reasonhold_reason · string or null · required
Conversionconversion · object, one of 2Set once this deposit has become USD credits. Either shape 1: rate, spread_bps, rate_applied, credited_usd_micros, converted_at, policy_version; or shape 2: .

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
201 CreatedSynthetic sandbox data
{  "object": "gram_deposit",  "id": "dep_01K7SAMP000000000000000001",  "status": "confirming",  "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": null,  "hold_reason": null,  "conversion": null}
Code for Responses
Response
JSON
201 CreatedSynthetic sandbox data
{  "object": "gram_deposit",  "id": "dep_01K7SAMP000000000000000090",  "status": "confirming",  "asset": "GRAM",  "amount_nanogram": "5000000000",  "network": "simulated",  "tx_hash": "0000000000000000000000000000000000000000000000000000000000000000",  "explorer_url": null,  "sender_masked": "0:000000...0000",  "observed_at": "2026-10-10T10:14:00.000Z",  "credited_at": null,  "hold_reason": 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.
IdempotencyRequired, and bound permanently to what the first request made. Reuse it on every retry: a retry answers with the same operation, never a second one.
In the sandboxCredits synthetic GRAM, on no network. Read your deposit address first, or it answers not_found.
On LiveDoes not exist: the request answers 404 there.
FundingNone: this adds test money, and a workspace on USD credits has it converted as a real deposit is.
Status changesThe same as a real deposit: below the minimum it is needs_attention and not credited.
Webhook eventsNone.

Error responses

This operation can also answer with not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, payload_too_large, unknown_field.

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.