Skip to content

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

FieldDescription
Assetasset · string · requiredThe 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 · requiredThe network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another.
Amountamount · string · requiredWhat 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 · requiredThe destination address, 32 to 80 printable characters: one of your workspace's approved destinations.
Memomemo · stringThe text comment the transfer carries, where the destination needs one. Part of the destination's identity.
Max total chargemax_total_charge · stringThe 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.

Code for What you send
# 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:

FieldDescription
IDid · string · requiredThe quote: pyq_ and 26 characters.
Objectobject · string · requiredpayout_quote.
Assetasset · string · requiredThe 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 · requiredThe network the transfer is made on, one GET /v1/payout-networks lists. An address approved on one network authorises nothing on another.
Amountamount · string · requiredWhat the recipient receives, as asked.
Amount unitsamount_units · string · requiredThe same amount in the asset's smallest unit.
Decimalsdecimals · integer · requiredThe asset's decimal places.
Addressaddress · string · requiredThe address as the network's rules normalise it.
Memomemo · string or null · requiredAs asked.
Destination IDdestination_id · string · requiredThe approved destination it pays.
Raterate · object · requiredThe rate the charge is priced at.
Pairrate.pair · string · requiredThe pair, the asset against USD.
Usd per unitrate.usd_per_unit · string · requiredUSD per one whole unit of the asset, cut to 12 places for display. The charge was computed from the exact reading.
Read atrate.read_at · string · requiredWhen the rate was read.
Chargecharge · object · requiredWhat your USD balance will be charged, disclosed apart from the amount.
Currencycharge.currency · string · requiredUSD.
Payout value microscharge.payout_value_micros · string · requiredWhat the recipient amount is worth at the quote's rate.
Platform fee microscharge.platform_fee_micros · string · requiredNasfam's fee for sending it.
Network fee microscharge.network_fee_micros · string · requiredThe network's fee, Nasfam's own estimate for the network. A request never supplies one.
Conversion fee microscharge.conversion_fee_micros · string · requiredThe spread on the rate.
Total microscharge.total_micros · string · requiredWhat your USD balance is charged in all: the sum of the four.
Max total chargemax_total_charge · string · requiredThe ceiling it was priced under, in micro-dollars (1000000000000000 when none was named).
Expires atexpires_at · string · requiredUntil when the rate and every fee are locked: for up to 60 seconds.
Created atcreated_at · string · requiredWhen 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.

CodeWhen, and what to do
Idempotency key requiredidempotency_key_required · 400A quote or a payout was sent with no Idempotency-Key. Send one key per new quote or payout.
Price changedprice_changed · 409The total charge would be above max_total_charge. Nothing is made or held. Quote again, or raise the ceiling.
Network not supportednetwork_not_supported · 422The pair is not one GET /v1/payout-networks lists here. Read GET /v1/payout-networks.
Destination not approveddestination_not_approved · 422The address is not one of your workspace's approved, usable destinations for this asset and network. Approve it as a destination first.
Payouts unavailablepayouts_unavailable · 503Crypto payouts are not switched on in this environment. Nothing is written. Do not retry until payouts open here.
Pricing unavailablepricing_unavailable · 503No fresh rate, network fee estimate or fee policy to price with. Nothing is held. Retry after Retry-After.