Cotizar en bolívares

El importe de una dispersión no se manda en POST /payouts: lo fija la cotización, junto con la comisión, y queda garantizado hasta expires_at. Fijas un lado —lo que recibe el beneficiario o lo que gastas tú— y te devolvemos los dos, con los mismos campos en ambos casos.

Fijar lo que recibe el beneficiario (`deliver`)

El beneficiario recibe el importe exacto y la comisión se suma encima: spend sale más alto que deliver.

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

{
  "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"
}

No hay conversión, así que rate es null.

Fijar lo que gastas tú (`spend`)

Indicas cuánto pones y en qué activo se entrega. La comisión se descuenta de lo convertido: deliver sale más bajo que la conversión bruta.

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

{
  "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"
}

Fija spend sólo cuando haya conversión: con el mismo activo en los dos lados se rechaza con 400.

La respuesta, campo a campo

Es la misma en los dos casos: deliver.amount se lee sin ramificar.

Campo	Qué es
`id`	Lo que mandas en `quoteId` al dispersar
`fixed`	`"deliver"` o `"spend"`: qué lado fijaste tú
`spend`	`{ asset, amount }` — lo que se te cobra
`deliver`	`{ asset, amount }` — lo que cobra el beneficiario
`fee`	`{ asset, amount }` — nuestra comisión. Siempre en el activo entregado
`rate`	La tasa, o `null` si no hay conversión
`status`	`open` · `consumed` · `expired`
`expires_at` · `created_at`	ISO-8601. Pasada `expires_at` no sirve

Los importes son dos: deliver es lo que cobra el beneficiario y spend lo que se te cobra a ti. Van en unidades menores, como string: "5000000" son 50.000,00 Bs. Ver importes y bolívares.

La tasa

rate es null cuando los dos lados son el mismo activo. Con conversión trae { "value": "37.81", "market": "38", "spread_bps": 50 }, en decimal:

Campo	Qué es
`value`	La tasa que se te aplicó, con nuestro margen
`market`	La tasa de referencia, antes del margen
`spread_bps`	La diferencia entre las dos, en puntos básicos. `50` = 0,50 %

El conversor de dos campos editables

Dos campos, bolívares y divisa, y al teclear en uno se actualiza el otro. Como cotizar es gratis, se cotiza en cada pausa de tecleo con POST /v1/quotes: no hay endpoint de previsualización.

Recuerda cuál tocó el usuario el último. Ése manda; el otro es calculado. Tratarlos como entradas simétricas entra en un bucle de actualización mutua.
Al teclear, cotiza con un debounce de ~250 ms, fijando el lado que toque. Descarta la respuesta si llegó otra más reciente o si el usuario cambió de campo.

Escribió en… Cotiza con

bolívares {"deliver":{"asset":"BS","amount":<Bs>}}

divisa {"spend":{"asset":"USD","amount":<divisa>},"deliver":{"asset":"BS"}}
Repinta sólo el campo que no fijó el usuario. fixed dice cuál de los dos no tocar. Y no recalcules ninguno de los dos números: la comisión no cae del mismo lado en los dos sentidos.
Al confirmar, usa la última cotización: sus dos números, y el contador de 60 s hasta expires_at.
Si caduca, vuelve a cotizar. Con una vencida, POST /payouts devuelve 422 quote_expired.

Escribió en…	Cotiza con
bolívares	`{"deliver":{"asset":"BS","amount":<Bs>}}`
divisa	`{"spend":{"asset":"USD","amount":<divisa>},"deliver":{"asset":"BS"}}`

Las que no consumes caducan a los 60 s y se borran solas.

Limitación conocida: fijar lo entregado y pagar en otro activo

Todavía no se puede. «Entrega 1.500,00 Bs exactos y cóbramelo en dólares» da 400:

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

{ "error": {
    "code": "validation_failed",
    "message": "Todavía no se puede fijar el importe a entregar pagando en otro activo (USD → BS). Fija `spend` y te decimos cuánto llega" } }

Alternativas: fija spend y acepta el importe que salga, o fondea en Bs y fija deliver.

Reglas de los dos lados

Todas devuelven 400 validation_failed.

Lo que mandas	`error.message`, literal
`amount` en los dos lados	«Fija UN lado: manda `amount` en `deliver` o en `spend`, no en los dos. El otro lo calculamos nosotros»
`amount` en ninguno	«Falta el importe: manda `amount` en `deliver` (lo que recibe el beneficiario) o en `spend` (lo que se te cobra)»
`spend` con importe, sin `deliver.asset`	«Falta `deliver.asset`: si fijas lo que gastas, hay que decir en qué activo se entrega»
`spend` con importe y el mismo activo en los dos lados	«Sin conversión, fija `deliver.amount`: así el beneficiario recibe el importe exacto y la comisión se cobra encima»
`deliver` con importe y otro activo en `spend`	«Todavía no se puede fijar el importe a entregar pagando en otro activo (USD → BS). Fija `spend` y te decimos cuánto llega». Ver limitación conocida
`deliver` con importe en un activo que no dispersamos	Sólo se cotiza importe exacto en `BS`

amount es un entero en unidades menores, mínimo 100 (1,00 Bs). No es el mínimo del riel: ése está en tokens, se mueve con la tasa y se comprueba al dispersar. Ver límites y mínimos.

Ciclo de vida de una cotización

open ──consumida por POST /payouts──► consumed
  │
  └──pasa expires_at──────────────────► expired

Estado	Qué significa	Si la usas
`open`	Vigente y sin usar	Se dispersa
`consumed`	Ya la gastó otra dispersión	`409 quote_already_consumed`
`expired`	Pasó `expires_at`	`422 quote_expired`

GET /quotes/{id} devuelve la misma forma, con status actualizado:

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

Errores

`error.code`	HTTP	Cuándo
`validation_failed`	400	Los dos lados con importe, ninguno, falta `deliver.asset`, o el caso que todavía no se puede
`invalid_amount`	400	Importe por debajo del suelo, o tan pequeño que la comisión se lo comería entero
`quote_not_found`	404	No existe, o es de otro programa
`quote_expired`	422	Al dispersar: caducó
`quote_already_consumed`	409	Al dispersar: ya se usó
`no_provider_available`	503	Sólo con conversión: no hay tasa para ese par ahora mismo

Siguiente paso

Con el id de la cotización ya puedes dispersar, a un beneficiario registrado o a uno en línea.