Skip to content

Pricing and costs

What each request costs, where the price of an order comes from, and what to do when your balance is short.

A request costs nothing by itself. What you pay for is an order: it charges what its quote says, set by the server, and it comes out of your balance.

Prices are set in USD, and an order charges USD from your balance. In the sandbox every price is synthetic.

What each request costs

RequestWhat it does to your balance
POST /ordersReserves the order's amount from available. The amount is taken if the order succeeds and returned if it fails.
POST /sandbox/funding/depositsAdds test GRAM, judged as a real deposit. It exists on the sandbox host only.
POST /sandbox/depositsAdds a test deposit that names its asset, judged as a real deposit.
Every other requestNothing.

The statement says the same: a movement on the balance is one of funding_credit, order_reserve, order_capture, order_release, adjustment, reversal, gram_conversion, and none of them is a charge for a request. Requests are limited, not charged; see Rate limits.

Where a price comes from

The server prices every quote from its own configuration. These pages print no price: any figure in an example is a sample. GET /products says what you may select, and GET /prices lists the price book in effect, or answers available: false where none is set.

What a quote charges is its settlement (amount_usd_micros), the same figure as breakdown.total and payment: show your customer that. amount is the product line before any service fee. Every quote and every order carries pricing_version, the version of the server's pricing its amount came from, so you can tell which prices an order was made at. A sandbox price is synthetic: it is not a price for Live.

The public price list

The current prices are public, with no key and no account. The pricing page on the Nasfam Business website reads them from the server's public price list, which says what each Stars package and each Premium term is charged now, in USD, and what any one quantity of Stars is charged, and nothing a price is made of.

It is a list to read, not a price to charge by: an order charges what its own quote says. These docs print no price, so they never go out of date.

Quotes

Create a quote to see the price for a recipient and a selection. It holds that price for up to 60 seconds and is used once; past that, an order from it is refused with quote_expired. To order without a quote, send a max_amount: the most you will pay. If the current price is above it, the order is refused with price_changed. See Orders and statuses.

Prices in USD

Availability: Available. Live and verified in production.

Prices are set in USD, in one versioned price book on the server. GET /prices reads it.

A workspace on USD credits is charged USD, with no rate and no conversion: payment on the quote says what the order will charge, and settlement is a UsdSettlement.

A workspace that still spends GRAM is priced this way:

  • A quote converts the USD price to GRAM at a fresh, checked reference rate (GET /rates), rounds it up to the next nanoGRAM, and holds that amount for up to 60 seconds. settlement carries the GRAM charged, the USD price and the rate with its time.
  • The order reserves exactly the quoted GRAM, then takes it if the order succeeds or returns it if the order fails. The order record keeps the same settlement.
  • Without a fresh rate, no new quote is made; see Balances and reference rates.

The same USD price can cost a different amount of GRAM from one quote to the next, as the rate moves. The quote is the only figure to charge by. A GRAM order is made from a quote; a direct GRAM order is not served.

When your balance is short

An order that costs more than your available balance is refused with insufficient_funds. Nothing is reserved and no order is created. Money held by orders in progress, and pending_funding not yet credited, does not count.

  1. Read GET /balance.
  2. Add funds. In the sandbox, Add test funds in your dashboard adds synthetic money.
  3. Send the same order again, with the same Idempotency-Key: the refused request created nothing, so the key is still free. If its quote expired in the meantime, quote again and order from the new quote.

Before a batch of orders, read GET /balance, so the batch never runs short halfway.

Common mistakes

  • Hard-coding a price. Read it from a quote every time. It is the server's, and it changes.
  • Ordering on an expired quote. A quote holds its price for up to 60 seconds. Quote again past that.
  • Counting held or pending money as available. Only available pays for an order.