Estimate a payout
A quote fixes what your balance will be charged for what the recipient receives, for up to 60 seconds. It holds nothing.
Sandbox: test money only. No request moves real money.
Sandbox. The payout operations are in the API's contract and built for the sandbox, where a payout is simulated and never a real transfer. Until Nasfam switches payouts on in an environment, every request there answers 503 payouts_unavailable and nothing is written or held. Live: not yet available.
Availability: Sandbox. Built for the sandbox, on synthetic money. Not live.
POST /payouts/quotes prices sending exactly amount to an approved destination, and locks the rate and every fee for up to 60 seconds, until expires_at: sooner when the market reading or the network fee estimate behind it expires. Nothing is held from your balance. It needs payouts:write and an Idempotency-Key.
What you send
| Field | Description |
|---|---|
| Assetasset · string · required | The asset the recipient receives, one GET /v1/payout-networks lists. Its issuer's own token on the named network, never a bridged one. |
| Networknetwork · string · required | The network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another. |
| Amountamount · string · required | What the recipient receives, as a decimal string in the asset's units ("100.5"), never a number. More decimal places than the pair's decimals is 400 invalid_request: nothing is rounded. Zero is refused. |
| Addressaddress · string · required | The destination address, 32 to 80 printable characters: one of your workspace's approved destinations. |
| Memomemo · string | The text comment the transfer carries, where the destination needs one. Part of the destination's identity. |
| Max total chargemax_ | The most it may charge your USD balance, in micro-dollars. Above it: 409 price_changed, and nothing is made or held. |
amount is what the recipient receives, never what you are charged. Send it as a decimal string in the asset's units: a number can lose digits on the way, and nothing is rounded. With max_total_charge, a total above it is refused with price_changed and no quote is made.
# One key per purchase: make it once, keep it with the purchase, and send the same key on every retry.: "${IDEMPOTENCY_ KEY:?Set IDEMPOTENCY_ KEY once for this purchase ( a new UUID) and keep it for every retry}"curl -X POST "https:// sandbox-api. nasfampay. com/ v1/ payouts/ quotes" \ -H "Authorization: Bearer $NASFAM_ SANDBOX_ KEY" \ -H "Content-Type: application/ json" \ -H "Idempotency-Key: $IDEMPOTENCY_ KEY" \ -d '{ "asset": "ASSET", "network": "network_ id", "address": "your-approved-destination-address", "amount": "10.00", "max_ total_ charge": "11000000" }'What it returns
201 Created with the quote:
| Field | Description |
|---|---|
| IDid · string · required | The quote: pyq_ and 26 characters. |
| Objectobject · string · required | payout_quote. |
| Assetasset · string · required | The asset the recipient receives, one GET /v1/payout-networks lists. Its issuer's own token on the named network, never a bridged one. |
| Networknetwork · string · required | The network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another. |
| Amountamount · string · required | What the recipient receives, as asked. |
| Amount unitsamount_ | The same amount in the asset's smallest unit. |
| Decimalsdecimals · integer · required | The asset's decimal places. |
| Addressaddress · string · required | The address as the network's rules normalise it. |
| Memomemo · string or null · required | As asked. |
| Destination IDdestination_ | The approved destination it pays. |
| Raterate · object · required | The rate the charge is priced at. |
| Pairrate. | The pair, the asset against USD. |
| Usd per unitrate. | USD per one whole unit of the asset, cut to 12 places for display. The charge was computed from the exact reading. |
| Read atrate. | When the rate was read. |
| Chargecharge · object · required | What your USD balance will be charged, disclosed apart from the amount. |
| Currencycharge. | USD. |
| Payout value microscharge. | What the recipient amount is worth at the quote's rate. |
| Platform fee microscharge. | Nasfam's fee for sending it. |
| Network fee microscharge. | The network's fee, Nasfam's own estimate for the network. A request never supplies one. |
| Conversion fee microscharge. | The spread on the rate. |
| Total microscharge. | What your USD balance is charged in all: the sum of the four. |
| Max total chargemax_ | The ceiling it was priced under, in micro-dollars (1000000000000000 when none was named). |
| Expires atexpires_ | Until when the rate and every fee are locked: for up to 60 seconds. |
| Created atcreated_ | When the quote was made. |
Show your customer amount and every part of charge before you send. charge.total_micros is the four parts added up. A payout made from the quote is charged exactly that total, or refused.
The same key again
The same key and the same body answers 200 with Idempotent-Replayed: true and the quote it made, unchanged: it may have expired since. A new quote needs a new key.
When it expires
After expires_at, a payout from it is refused with quote_expired; a quote already paid out is refused with quote_already_used. Nothing was held either way. Ask for a new quote.
| Code | When, and what to do |
|---|---|
| Idempotency key requiredidempotency_ | A quote or a payout was sent with no Idempotency-Key. Send one key per new quote or payout. |
| Price changedprice_ | The total charge would be above max_total_charge. Nothing is made or held. Quote again, or raise the ceiling. |
| Network not supportednetwork_ | The pair is not one GET /v1/payout-networks lists here. Read GET /v1/payout-networks. |
| Destination not approveddestination_ | The address is not one of your workspace's approved, usable destinations for this asset and network. Approve it as a destination first. |
| Payouts unavailablepayouts_ | Crypto payouts are not switched on in this environment. Nothing is written. Do not retry until payouts open here. |
| Pricing unavailablepricing_ | No fresh rate, network fee estimate or fee policy to price with. Nothing is held. Retry after Retry-After. |
Related guides
- Fees and limits: what
chargeholds. - Send a payout: the step after a quote.
- Retrying a payout safely: the quote's key.
