List prices
GET/prices
The USD price book in effect, with indicative GRAM figures.
Sandbox: test money only. No request moves real money.
Authenticate with your sandbox key as a bearer token: Authorization: Bearer nbk_test_..
The packages GRAM is sold in, each with its USD price. indicative_nanogram is the package at the newest good GRAM/USD
rate, labelled indicative: what an order charges is its quote's settlement. display_currency adds an estimated price
in that currency at a display rate, never charged. A database with no book of its own answers available: false.
price_basis says how these prices are set and when they can change; a quote carries its own.
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.
Parameters
| Field | Description |
|---|---|
| Display currencydisplay_ | One of EUR, GBP. |
const response = await fetch( 'https:// sandbox-api. nasfampay. com/ v1/ prices', { 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: prices } = await axios. get( 'https:// sandbox-api. nasfampay. com/ v1/ prices', { headers: { Authorization: `Bearer ${process. env. NASFAM_ SANDBOX_ KEY}`, }, }, ); console. log( status, prices);} 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 | The price book in effect. 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.
). | PriceList 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 price list object
| Field | Description |
|---|---|
| Availableavailable · boolean · required | false: no price book is set in this environment, and GRAM quotes are refused. |
| Versionversion · integer | At least 1. |
| Labellabel · string | |
| Active fromactive_ | Format date-time. |
| Raterate · MarketRate object | |
| Pairrate. | One of GRAM/USD. |
| Availablerate. | |
| Usd per gramrate. | |
| Usd micros per gramrate. | |
| Numeratorrate. | Pattern ^[1-9][0-9]{0,30}$. |
| Denominatorrate. | Pattern ^[1-9][0-9]{0,30}$. |
| Source timerate. | Format date-time. |
| Valid untilrate. | Format date-time. |
| Quotablerate. | Whether a quote may be priced at it now; false means stale. |
| Displaydisplay · object, one of 2 | Either shape 1: pair, available, per_usd, rate, source_time, valid_until, display_only, state, agreement, shown, judged, tolerance_bps, deviation_bps; or shape 2: . |
| Price basisprice_ | How a USD price is set. usd_fixed: the price changes only when a new price book is published. usd_cost_plus: the price is the provider's cost in USD plus a fixed margin and a per-order fee, and changes only when that cost moves by more than reprice_threshold_bps. Either way a quote's price never changes once given, for quote_valid_seconds. New kinds may be added; treat an unknown kind as "the quote's own price is the price". |
| Kindprice_ | One of usd_fixed, usd_cost_plus. |
| Currencyprice_ | One of USD. |
| Updatesprice_ | The same, in words, for a person. |
| Reprice threshold bpsprice_ | usd_cost_plus only: the cost move, in basis points, that changes a price. At least 1. |
| Quote valid secondsprice_ | At least 0. |
| Quantitiesprice_ | usd_cost_plus on the price list only: the whole quantities each product is priced for. A quantity in range is quoted with POST /v1/quotes. |
| Productprice_ | telegram_premium is a Telegram Premium subscription for 3, 6 or 12 months, given to the account at the username. An order succeeds only when the provider's own record of our one purchase for it, found by our reference, says it was delivered; a purchase answer, a timeout or an undocumented status is never taken as delivery. Until then the order is processing (or under_review, when people must decide) and its amount stays held. It fails, and the amount is released, only on the provider's documented failure or a two-person decision. One of telegram_stars, telegram_premium. |
| Minprice_ | At least 1. |
| Maxprice_ | At least 1. |
| Datadata · array of PricePackage · required | |
| Productdata[]. | telegram_premium is a Telegram Premium subscription for 3, 6 or 12 months, given to the account at the username. An order succeeds only when the provider's own record of our one purchase for it, found by our reference, says it was delivered; a purchase answer, a timeout or an undocumented status is never taken as delivery. Until then the order is processing (or under_review, when people must decide) and its amount stays held. It fails, and the amount is released, only on the provider's documented failure or a two-person decision. One of telegram_stars, telegram_premium. |
| Package keydata[]. | |
| Selectiondata[]. | |
| Quantitydata[]. | |
| Monthsdata[]. | |
| Pricedata[]. | |
| Amountdata[]. | USD, in cents. 0 to 100000000000. |
| Currencydata[]. | USD. One of USD. |
| Price usd microsdata[]. | Pattern ^[1-9][0-9]{0,12}$. |
| Availabledata[]. | false: this package cannot be quoted right now (its price would fall outside the approved range); a quote is refused 503 pricing_unavailable. |
| Indicative nanogramdata[]. | Indicative only; the charge is the quote's. Either shape 1: ; or shape 2: . |
| Display amountdata[]. | Estimated, in display_currency, never charged. |
Responses are extensible: ignore fields, enum values and event types you do not know. Any other status is a Problem (see Errors).
{ "available": true, "version": 1, "label": "string", "active_ from": "2026-10-10T10:05:02Z", "rate": { "pair": "GRAM/ USD", "available": true, "usd_ per_ gram": "1.500000", "usd_ micros_ per_ gram": { "numerator": "1500000", "denominator": "1" }, "source_ time": "2026-10-10T10:05:02Z", "valid_ until": "2026-10-10T10:05:02Z", "quotable": true }, "display": { "pair": "USD/ EUR", "available": true, "per_ usd": "string", "rate": { "numerator": "1500000", "denominator": "1" }, "source_ time": "2026-10-10T10:05:02Z", "valid_ until": "2026-10-10T10:05:02Z", "display_ only": true, "state": "fresh", "agreement": "agreeing", "shown": true, "judged": { "per_ usd": "string", "rate": { "numerator": "1500000", "denominator": "1" }, "label": "string", "source_ time": "2026-10-10T10:05:02Z" }, "tolerance_ bps": 0, "deviation_ bps": null }, "price_ basis": { "kind": "usd_ fixed", "currency": "USD", "updates": "string", "reprice_ threshold_ bps": 1, "quote_ valid_ seconds": 0, "quantities": [ { "product": "telegram_ stars", "min": 1, "max": 1000 } ] }, "data": [ { "product": "telegram_ stars", "package_ key": "string", "selection": { "quantity": 50, "months": 3 }, "price": { "amount": 750, "currency": "USD" }, "price_ usd_ micros": "7500000", "available": true, "indicative_ nanogram": "5000000000", "display_ amount": null } ]}{ "available": false, "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 | |
|---|---|
| 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 | Prices are synthetic. Where no price book is set, the answer is available: false. |
| 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. This request does not touch your balance. |
| 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.
