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
| Header | Value | Sent |
|---|---|---|
Authorization | Bearer nbk_test_... | Required |
No Idempotency-Key is needed: a read changes nothing, so it is safe to send again.
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);// 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
| Status | Meaning | Body |
|---|---|---|
| OK200 | Rates. 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 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 rates object
| Field | Description |
|---|---|
| Gram usdgram_ | |
| Pairgram_ | One of GRAM/USD. |
| Availablegram_ | |
| Usd per gramgram_ | |
| Usd micros per gramgram_ | |
| Numeratorgram_ | Pattern ^[1-9][0-9]{0,30}$. |
| Denominatorgram_ | Pattern ^[1-9][0-9]{0,30}$. |
| Source timegram_ | Format date-time. |
| Valid untilgram_ | Format date-time. |
| Quotablegram_ | Whether a quote may be priced at it now; false means stale. |
| Displaydisplay · array of DisplayRate · required | |
| Pairdisplay[]. | One of USD/EUR, USD/GBP. |
| Availabledisplay[]. | |
| Per usddisplay[]. | |
| Ratedisplay[]. | |
| Numeratordisplay[]. | Pattern ^[1-9][0-9]{0,30}$. |
| Denominatordisplay[]. | Pattern ^[1-9][0-9]{0,30}$. |
| Source timedisplay[]. | Format date-time. |
| Valid untildisplay[]. | Format date-time. |
| Display onlydisplay[]. | One of true. |
| Statedisplay[]. | fresh: 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[]. | agreeing: 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[]. | Whether 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[]. | Either shape 1: per_usd, rate, label, source_time; or shape 2: . |
| Tolerance bpsdisplay[]. | How far apart the sources may be. At least 0. |
| Deviation bpsdisplay[]. | The 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).
{ "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 } ]}{ "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": []}{ "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 | The same reference rates a real quote would use. A figure appears only when it is fresh and its sources agree. |
| 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.
