Balances and reference rates
What your balance is, how a deposit becomes USD credits, and how fresh a reference rate must be.
Your balance is prepaid service credits in USD. Fund your account with crypto: each verified deposit becomes credits at the rate we record at the moment of crediting.
What your balance is
- USD credits. Your balance is prepaid service credits in USD. They pay only for our services on your own account. Section 12 of the terms says the rest.
- Funded with crypto. Each verified deposit becomes credits at the rate we record at the moment of crediting. The rate, its time and the credits are recorded with the deposit, and never recalculated.
- Fixed in USD. Your credits do not change when the price of the asset you deposited does.
- Spent on orders. Credits pay for orders, and cannot be withdrawn or transferred. An order is accepted only if your available balance covers it.
| Field | What it holds |
|---|---|
available, held, pending_funding | The three figures, each an integer in the minor unit of its currency: cents for USD. |
usd | The same three figures exactly, in integer micro-dollars: 1,000,000 to 1 USD. |
headline | The one figure to show first: your spendable USD credits, with is_estimate false. |
These are the fields of GET /balance. A figure in any other currency is for reading only, never a second balance.
Money fields
Every figure is exact, and its name says its unit. Show the readable decimal where the server sends one; keep the integer beside it as the record.
| Field | What it holds | Example |
|---|---|---|
A name ending _usd | USD as an exact decimal string with six places: the micro-dollar figure beside it, written out. Print it as it is. | "7.500000" is $7.50 |
A name ending _usd_estimate | An estimate of GRAM in USD, six places. Never a balance and never what an order costs. | "6.125000" |
A name ending _gram | GRAM as an exact decimal string with nine places. | "5.000000000" is 5 GRAM |
A name ending _micros | Exact micro-dollars: an integer, as a string. 1,000,000 is 1 USD. | "7500000" is $7.50 |
amount_minor beside currency | The integer in the unit currency names: micro-dollars for USD, nanogram for TON. Never cents. | "7500000" with USD is $7.50 |
A name ending _nanogram | Exact nanogram: an integer, as a string. 1,000,000,000 is 1 GRAM. | "5000000000" is 5 GRAM |
amount in { amount, currency } | Cents, as a JSON integer, rounded toward zero from the exact figure. A request's max_amount is in cents too. | 750 is $7.50 |
available, held and pending in usd, and amount in headline | USD as a decimal string with two places, rounded down: never more than is spendable. | "7.50" |
The readable fields come with readable amounts, which Nasfam turns on for each environment. They are not served in Sandbox or Live yet. Until then a response carries the integers, with settlement.amount_usd and settlement.amount_gram as it always has.
Display currency
Figures are shown in USD by default. A member can choose another display currency from the ones the server serves, where two reference sources agree.
A display currency is for reading only. Changing it changes no record, no balance and no price, and makes no trade. Each converted figure is marked with "โ" and carries the time of its rate.
Reference rates
GET /rates reads them. Every reference rate carries its time, and the GRAM to USD rate is checked against a second, independent source. quotable says whether it may price a quote now.
- A rate credits a deposit or prices a quote only while it is fresh and the two sources agree.
- Without a good rate, a deposit waits: it is never credited at a guessed rate.
- Without a fresh rate, a new quote that needs one is refused with
pricing_unavailableand nothing is charged. Send the request again later. - No rate is ever typed in by hand.
Common mistakes
- Calling credits money. They are prepaid service credits in USD, and they pay only for orders.
- Computing a figure yourself. Show the server's balance as it arrives. Never convert or add figures up in your code.
- Dropping the "โ" of an estimate. Where
is_estimateis true, the figure is an estimate and keeps its "โ". - Treating a display currency as a conversion. Changing it moves no money and changes no price.
Related guides
- Funding with GRAM: the deposit address, what to send, and when a deposit is credited.
- Pricing and costs: what an order costs, and how a quote fixes it.
- Funding your account: the balance and its three figures.
