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
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
Content-Type | application/json | Required |
Idempotency-Key | 3f1c9a52-7d4e-4b8a-9c21-5e6f7a8b9c0d | Required |
Parameters
| Field | Description |
|---|---|
| Idempotency keyIdempotency-Key · header string · required | Bound 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.
| Field | Description |
|---|---|
| Amount nanogramamount_ | nanoGRAM: 1 to 1,000 GRAM (1000000000000) per simulated deposit. Pattern ^[1-9][0-9]{0,12}$. |
// 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);// 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
| Status | Meaning | Body |
|---|---|---|
| OK200 | Replay 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 |
| Created201 | Simulated 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 large413 | The request body is over 16 KB (payload_too_large). Refused before authentication; nothing is read further. Headers: Request-Id. | Problem 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 gram deposit object
| Field | Description |
|---|---|
| Objectobject · string · required | One of gram_deposit. |
| IDid · string · required | Pattern ^dep_[0-9A-HJKMNP-TV-Z]{26}$. |
| Statusstatus · string · required | confirming: 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 · required | One of GRAM. |
| Amount nanogramamount_ | Pattern ^[0-9]{1,19}$. |
| Networknetwork · string · required | One of TON, TON testnet, simulated. |
| Tx hashtx_ | Pattern ^[0-9a-f]{64}$. |
| Explorer URLexplorer_ | Format uri. |
| Sender maskedsender_ | |
| Observed atobserved_ | Format date-time. |
| Credited atcredited_ | Format date-time. |
| Hold reasonhold_ | |
| Conversionconversion · object, one of 2 | Set 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).
{ "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}{ "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}{ "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 | Required, 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 sandbox | Credits synthetic GRAM, on no network. Read your deposit address first, or it answers not_found. |
| On Live | Does not exist: the request answers 404 there. |
| Funding | None: this adds test money, and a workspace on USD credits has it converted as a real deposit is. |
| Status changes | The same as a real deposit: below the minimum it is needs_attention and not credited. |
| Webhook events | None. |
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.
