Quote in bolívares

The amount of a payout is not sent in POST /payouts: the quote fixes it, together with the fee, and it is guaranteed until expires_at. You fix one side —what the beneficiary receives or what you spend— and we return both, with the same fields in either case.

Quoting is free

It does not reserve balance, does not consume limits and does not generate billable usage. Quote as many times as you like and consume the latest one. See the two-field converter.

Fixing what the beneficiary receives (deliver)

The beneficiary receives the exact amount and the fee is added on top: spend comes out higher than deliver.

curl -s $BASE/v1/quotes \
  -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -d '{"deliver":{"asset":"BS","amount":5000000}}'

201 Created

{
  "id": "70ec44b5-c1df-45b1-86fe-8f92c3959689", "fixed": "deliver",
  "spend":   { "asset": "BS", "amount": "5050000" },
  "deliver": { "asset": "BS", "amount": "5000000" },
  "fee":     { "asset": "BS", "amount":   "50000" },
  "rate": null, "status": "open",
  "expires_at": "2026-08-31T20:22:36.022Z", "created_at": "2026-08-31T20:21:36.022Z"
}

There is no conversion, so rate is null.

Fixing what you spend (spend)

You state how much you put in and which asset is delivered. The fee is deducted from the converted amount: deliver comes out lower than the gross conversion.

curl -s $BASE/v1/quotes \
  -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -d '{"spend":{"asset":"USD","amount":100000},"deliver":{"asset":"BS"}}'

201 Created

{
  "id": "9f2c1d84-0a37-4d5e-b6c1-71f0a2e4c9d3", "fixed": "spend",
  "spend":   { "asset": "USD", "amount":  "100000" },
  "deliver": { "asset": "BS",  "amount": "3743190" },
  "fee":     { "asset": "BS",  "amount":   "37810" },
  "rate": { "value": "37.81", "market": "38", "spread_bps": 50 },
  "status": "open",
  "expires_at": "2026-08-31T20:22:36.022Z", "created_at": "2026-08-31T20:21:36.022Z"
}

The numbers in the example are illustrative

The 0.50% spread (spread_bps: 50) and the 1% fee in this example are only there to show the calculation: they are not a published price. Your price depends on your commercial agreement and your volume: the fee schedule we apply to you is at GET /v1/fee-schedules and, if you sell at your own rate, your fee on what you sold is at GET /v1/treasury/volume-fee.

Fix spend only when there is a conversion: with the same asset on both sides it is rejected with 400.

The response, field by field

It is the same in both cases: deliver.amount is read without branching.

Field	What it is
id	What you send as quoteId when paying out
fixed	"deliver" or "spend": which side you fixed
spend	{ asset, amount } — what you are charged
deliver	{ asset, amount } — what the beneficiary receives
fee	{ asset, amount } — our fee. Always in the delivered asset
rate	The rate, or null if there is no conversion
status	open · consumed · expired
expires_at · created_at	ISO-8601. Past expires_at it is no longer usable

There are two amounts: deliver is what the beneficiary receives and spend what you are charged. They come in minor units, as a string: "5000000" is Bs 50,000.00. See amounts and bolívares.

The rate

rate is null when both sides are the same asset. With a conversion it carries { "value": "37.81", "market": "38", "spread_bps": 50 }, as decimals:

Field	What it is
value	The rate applied to you, including our margin
market	The reference rate, before the margin
spread_bps	The difference between the two, in basis points. 50 = 0.50%

The two-editable-field converter

Two fields, bolívares and foreign currency, and typing in one updates the other. Since quoting is free, you quote on every typing pause with POST /v1/quotes: there is no preview endpoint.

1. Remember which field the user touched last. That one rules; the other is calculated. Treating them as symmetric inputs falls into a mutual update loop.

2. While typing, quote with a ~250 ms debounce, fixing the appropriate side. Discard the response if a newer one arrived or if the user switched fields.

   Typed in…	Quote with
   bolívares	{"deliver":{"asset":"BS","amount":<Bs>},"spend":{"asset":"USDT"}}
   foreign currency	{"spend":{"asset":"USDT","amount":<currency>},"deliver":{"asset":"BS"}}

   If your user pays in Bs (no conversion), deliver alone is enough for bolívares.

3. Repaint only the field the user did not fix. fixed tells you which of the two not to touch. And do not recalculate either number: the fee does not fall on the same side in both directions.

4. On confirm, use the latest quote: its two numbers, and the 60 s countdown until expires_at.

5. If it expires, quote again. With an expired one, POST /payouts returns 422 quote_expired.

The ones you do not consume expire after 60 s and are deleted on their own.

Exact delivery paying in another currency

“Deliver exactly Bs 1,234.35 and tell me how many USDT that is”: fix deliver with an amount and put only the asset in spend.

curl -s $BASE/v1/quotes \
  -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -d '{"deliver":{"asset":"BS","amount":123435},"spend":{"asset":"USDT"}}'

201 Created (rate 945, 0.50% spread and 1.25% fee, illustrative)

{
  "fixed": "deliver",
  "deliver": { "asset": "BS",   "amount": "123435" },
  "spend":   { "asset": "USDT", "amount": "1329367" },
  "fee":     { "asset": "BS",   "amount": "1562" },
  "rate": { "value": "940.275", "market": "945", "spread_bps": 50 }
}

The beneficiary receives exactly deliver.amount, and spend.amount is the minimum that has to be spent for it to arrive: 1.329367 USDT.

In USD, with 2 decimals, fixing spend you cannot reach that number: each cent moves ~Bs 9.40. With USD 1.32 you get Bs 1,225.65, and with 1.33 you get Bs 1,234.93. With the inverse quote it does arrive exactly.

Rounding goes to the fee, in plain sight

The amount spent is rounded up to the asset’s minimum unit: one cent in USD and one millionth in USDT/USDC. Whatever that adds (at most the value of one unit: ~Bs 9.40 in USD, nothing in USDT) is added to fee, so deliver + fee = spend × rate.value holds, just as in the direct quote.

Rules for the two sides

All of them return 400 validation_failed. The error.message is returned in Spanish; program against error.code.

What you send	error.message, verbatim	Meaning
amount on both sides	«Fija UN lado: manda amount en deliver o en spend, no en los dos. El otro lo calculamos nosotros»	Fix ONE side; we calculate the other
amount on neither	«Falta el importe: manda amount en deliver (lo que recibe el beneficiario) o en spend (lo que se te cobra)»	The amount is missing
spend with an amount, without deliver.asset	«Falta deliver.asset: si fijas lo que gastas, hay que decir en qué activo se entrega»	If you fix what you spend, say which asset is delivered
spend with an amount and the same asset on both sides	«Sin conversión, fija deliver.amount: así el beneficiario recibe el importe exacto y la comisión se cobra encima»	Without conversion, fix deliver.amount
deliver with an amount and another asset in spend	—	It is quoted the other way round: we tell you how much to spend. See exact delivery paying in another currency
deliver with an amount in an asset we do not pay out	—	Exact amounts are only quoted in BS

amount is an integer in minor units, minimum 100 (Bs 1.00). That is not the payment network’s minimum: that one is set in tokens, moves with the rate and is checked at payout time. See limits and minimums.

Quote lifecycle

open ──consumed by POST /payouts──► consumed
  │
  └──expires_at passes──────────────► expired

State	What it means	If you use it
open	Valid and unused	The payout goes ahead
consumed	Another payout already used it	409 quote_already_consumed
expired	expires_at has passed	422 quote_expired

Quote right before paying out

The default TTL is ~60 seconds and the quote is single use. Do not keep it in a queue or reuse it across retries: if the payout fails, request a new one.

GET /quotes/{id} returns the same shape, with an updated status:

curl -s $BASE/v1/quotes/70ec44b5-c1df-45b1-86fe-8f92c3959689 -H "x-api-key: $KEY"

Errors

error.code	HTTP	When
validation_failed	400	Both sides with an amount, neither, or deliver.asset missing
invalid_amount	400	Amount below the floor, or so small the fee would eat all of it
quote_not_found	404	It does not exist, or it belongs to another program
quote_expired	422	At payout time: it expired
quote_already_consumed	409	At payout time: it was already used
no_route_available	503	Only with a conversion: there is no rate for that pair right now

Next step

With the quote id you can now pay out, to a registered beneficiary or to an inline one.