Skip to content

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

HeaderValueSent
AuthorizationBearer nbk_test_...Required

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

Parameters

FieldDescription
Display currencydisplay_currency · query stringOne of EUR, GBP.
The request in cURL, JavaScript and Python
GET /v1/pricesSandbox, test key
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);
Code for Request
GET /v1/pricesSandbox, test key
// 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

StatusMeaningBody
OK200The 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 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 price list object

FieldDescription
Availableavailable · boolean · requiredfalse: no price book is set in this environment, and GRAM quotes are refused.
Versionversion · integerAt least 1.
Labellabel · string
Active fromactive_from · stringFormat date-time.
Raterate · MarketRate object
Pairrate.pair · stringOne of GRAM/USD.
Availablerate.available · boolean
Usd per gramrate.usd_per_gram · string
Usd micros per gramrate.usd_micros_per_gram · Fraction object
Numeratorrate.usd_micros_per_gram.numerator · stringPattern ^[1-9][0-9]{0,30}$.
Denominatorrate.usd_micros_per_gram.denominator · stringPattern ^[1-9][0-9]{0,30}$.
Source timerate.source_time · stringFormat date-time.
Valid untilrate.valid_until · stringFormat date-time.
Quotablerate.quotable · booleanWhether a quote may be priced at it now; false means stale.
Displaydisplay · object, one of 2Either 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_basis · PriceBasis objectHow 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_basis.kind · stringOne of usd_fixed, usd_cost_plus.
Currencyprice_basis.currency · stringOne of USD.
Updatesprice_basis.updates · stringThe same, in words, for a person.
Reprice threshold bpsprice_basis.reprice_threshold_bps · integerusd_cost_plus only: the cost move, in basis points, that changes a price. At least 1.
Quote valid secondsprice_basis.quote_valid_seconds · integerAt least 0.
Quantitiesprice_basis.quantities · array of objectusd_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_basis.quantities[].product · stringtelegram_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_basis.quantities[].min · integerAt least 1.
Maxprice_basis.quantities[].max · integerAt least 1.
Datadata · array of PricePackage · required
Productdata[].product · string · requiredtelegram_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[].package_key · string · required
Selectiondata[].selection · Selection object · required
Quantitydata[].selection.quantity · integer
Monthsdata[].selection.months · integer
Pricedata[].price · Money object · required
Amountdata[].price.amount · integer · requiredUSD, in cents. 0 to 100000000000.
Currencydata[].price.currency · string · requiredUSD. One of USD.
Price usd microsdata[].price_usd_micros · string · requiredPattern ^[1-9][0-9]{0,12}$.
Availabledata[].available · booleanfalse: 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_nanogram · object, one of 2 · requiredIndicative only; the charge is the quote's. Either shape 1: ; or shape 2: .
Display amountdata[].display_amount · string or null · requiredEstimated, 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).

Every kind of response
200 OKSynthetic sandbox data
{  "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    }  ]}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "available": false,  "data": []}
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 sandboxPrices are synthetic. Where no price book is set, the answer is available: false.
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. This request does not touch your balance.
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.