Skip to content

Get rates

GET/rates

The GRAM/USD reference rate GRAM quotes are priced at, and display rates.

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

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

gram_usd is the newest judgement of the GRAM/USD reference rate, as an exact fraction of USD micros per GRAM, with its source time. A quote is priced only while quotable is true (before valid_until); otherwise quotes are refused 503 pricing_unavailable. display rates are indicative and never charged. Each display rate is judged from two independent sources (draft.6): shown is true only when it is fresh and they agree within tolerance_bps, and judged is then the figure to show, with its source and label. A page shows no figure when shown is false.

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/ratesSandbox, test key
const response = await fetch('https://sandbox-api.nasfampay.com/v1/rates', {  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/ratesSandbox, test key
// npm install axiosimport axios from 'axios';try {  const { status, data: rates } = await axios.get(    'https://sandbox-api.nasfampay.com/v1/rates',    {      headers: {        Authorization: `Bearer ${process.env.NASFAM_SANDBOX_KEY}`,      },    },  );  console.log(status, rates);} 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
OK200Rates. 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. ).Rates 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 rates object

FieldDescription
Gram usdgram_usd · MarketRate object · required
Pairgram_usd.pair · string · requiredOne of GRAM/USD.
Availablegram_usd.available · boolean · required
Usd per gramgram_usd.usd_per_gram · string
Usd micros per gramgram_usd.usd_micros_per_gram · Fraction object
Numeratorgram_usd.usd_micros_per_gram.numerator · stringPattern ^[1-9][0-9]{0,30}$.
Denominatorgram_usd.usd_micros_per_gram.denominator · stringPattern ^[1-9][0-9]{0,30}$.
Source timegram_usd.source_time · stringFormat date-time.
Valid untilgram_usd.valid_until · stringFormat date-time.
Quotablegram_usd.quotable · booleanWhether a quote may be priced at it now; false means stale.
Displaydisplay · array of DisplayRate · required
Pairdisplay[].pair · string · requiredOne of USD/EUR, USD/GBP.
Availabledisplay[].available · boolean · required
Per usddisplay[].per_usd · string
Ratedisplay[].rate · Fraction object
Numeratordisplay[].rate.numerator · stringPattern ^[1-9][0-9]{0,30}$.
Denominatordisplay[].rate.denominator · stringPattern ^[1-9][0-9]{0,30}$.
Source timedisplay[].source_time · stringFormat date-time.
Valid untildisplay[].valid_until · stringFormat date-time.
Display onlydisplay[].display_only · booleanOne of true.
Statedisplay[].state · stringfresh: every source used is within its own freshness window. stale: one is older than that but not yet dropped. unavailable: no source is usable. Only fresh and agreeing is ever shown as a figure. One of fresh, stale, unavailable.
Agreementdisplay[].agreement · stringagreeing: at least two independent sources, every one within the pair's tolerance of the primary. A single source or a disagreement shows no figure. One of agreeing, disagreeing, single_source, no_source.
Showndisplay[].shown · booleanWhether a figure may be shown for this pair: only when it is fresh and two independent sources agree. When false a page shows no figure, whatever per_usd says (per_usd is the newest single reading, kept for older clients).
Judgeddisplay[].judged · object, one of 2Either shape 1: per_usd, rate, label, source_time; or shape 2: .
Tolerance bpsdisplay[].tolerance_bps · integerHow far apart the sources may be. At least 0.
Deviation bpsdisplay[].deviation_bps · integer or nullThe widest gap between the primary and a check, rounded up. At least 0.

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
{  "gram_usd": {    "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    }  ]}
Code for Responses
Response
JSON
200 OKSynthetic sandbox data
{  "gram_usd": {    "pair": "GRAM/USD",    "available": true,    "usd_per_gram": "1.225300",    "source_time": "2026-10-10T10:14:00.000Z",    "valid_until": "2026-10-10T10:24:00.000Z",    "quotable": true  },  "display": []}
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 sandboxThe same reference rates a real quote would use. A figure appears only when it is fresh and its sources agree.
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.