Cotizar una dispersión

POST/quotesProbar

ServidorURL base

API key x-api-keyRecordar la clave en este navegador (localStorage, no sale de aquí)Cuerpo de la petición (JSON)

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

POST

/quotes

const url = 'http://localhost:3000/v1/quotes';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: '{"deliver":{"asset":"BS","amount":5000000}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:3000/v1/quotes \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "deliver": { "asset": "BS", "amount": 5000000 } }'

Scope quotes:write. Fija el importe de la dispersión y nuestra comisión, y garantiza el resultado hasta expires_at. POST /payouts no acepta ningún monto: lo toma de aquí.

Fijas un lado y te devolvemos los dos. Mandas amount en UNO de los dos lados —nunca en los dos, nunca en ninguno—:

1 · Fijas deliver (lo que RECIBE el beneficiario). Lo recibe exacto y la comisión se suma encima, así que spend = deliver + fee. Es la forma recomendada para dispersar bolívares. Hoy sólo se admite importe exacto en BS, y hay que pagar en el mismo activo.

2 · Fijas spend (lo que GASTAS tú) más deliver.asset. Lo que llega sale de la tasa, menos comisión. Los dos activos tienen que ser distintos: sin conversión se fija deliver.amount.

La respuesta es la MISMA en los dos casos —fixed, spend, deliver, fee y rate, con los mismos nombres—: el importe entregado se lee siempre en deliver.amount. fixed dice qué lado fijaste tú.

rate es null cuando no hay conversión; cuando la hay llega en decimal (value, market, spread_bps).

Todavía no se puede fijar deliver.amount pagando en otro activo («entrega 1.500,00 Bs exactos y cóbramelo en dólares»): se rechaza con 400.

Cotizar es gratis: no reserva saldo, no consume límites y no genera consumo facturable. Cotiza tantas veces como quieras y consume la última; las que no uses caducan solas y se borran.

La cotización es de UN SOLO USO y su TTL es corto (por defecto ~60 segundos): cotiza justo antes de dispersar. Consumirla dos veces devuelve 409 quote_already_consumed; pasarla caducada, 422 quote_expired.

Los cinco rechazos, todos 400 validation_failed y con el mensaje que dice qué mandar en su lugar:

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)».
fijas spend sin deliver.asset → «Falta deliver.asset: si fijas lo que gastas, hay que decir en qué activo se entrega».
fijas spend con 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».
fijas deliver pagando en otro activo → «Todavía no se puede fijar el importe a entregar pagando en otro activo (USD → BS). Fija spend y te decimos cuánto llega».

Authorizations

ApiKeyAuth

Request Body^required

application/json

object

deliver

Lo que recibe el beneficiario. Con amount fijas este lado y lo recibe exacto, con la comisión cobrada encima; sin amount sólo dices en qué activo se entrega (obligatorio si fijas spend).

object

asset

required

string

Allowed values: BS USD USDC VESC

amount

Minor units de lo que RECIBE el beneficiario. 5000000 = 50.000,00 Bs. Va aquí o en spend, nunca en los dos.

integer

>= 100

spend

Lo que se te cobra a ti. Con amount fijas este lado y el importe entregado sale de la tasa, menos comisión.

object

asset

required

string

Allowed values: BS USD USDC VESC

amount

Minor units de lo que pones tú. 100000 = 1.000,00 USD. Va aquí o en deliver, nunca en los dos.

integer

>= 100

customerId

Opcional: a qué usuario TUYO corresponde. Para tu trazabilidad y para los límites por usuario.

string format: uuid

Examples

deliver — entrega exactamente 50.000,00 Bs (recomendado)

{
  "deliver": {
    "asset": "BS",
    "amount": 5000000
  }
}

spend — pon 1.000,00 USD y dime cuántos Bs llegan

{
  "spend": {
    "asset": "USD",
    "amount": 100000
  },
  "deliver": {
    "asset": "BS"
  }
}

Responses

201

Cotización creada

application/json

Una sola forma de cotización, fijes el lado que fijes. Los mismos campos con los mismos nombres tanto si fijaste deliver como si fijaste spend: lo que recibe el beneficiario se lee siempre en deliver.amount, y lo que se te cobra en spend.amount.

No hay un tercer importe: el bruto es siempre deliver + fee.

Todos los importes van en minor units y llegan como string.

object

Lo que mandas en quoteId al dispersar

string format: uuid

fixed

Qué lado fijaste tú; el otro lo calculamos nosotros. En una pantalla con los dos importes editables es lo que te dice cuál de los dos NO repintar, para no moverle el cursor al usuario mientras escribe.

string

Allowed values: deliver spend

spend

Lo que se te cobra a ti, comisión incluida.

object

asset

string

Allowed values: BS USD USDC VESC

amount

Minor units

string

deliver

Lo que cobra el beneficiario.

object

asset

string

Allowed values: BS USD USDC VESC

amount

Minor units

string

fee

Nuestra comisión, siempre en el activo que se entrega. Sin conversión se cobra encima (spend = deliver + fee); con conversión se descuenta de lo convertido.

object

asset

string

Allowed values: BS USD USDC VESC

amount

Minor units

string

rate

La tasa aplicada, ya en decimal: no hay escalas que dividir ni punto fijo que interpretar. null cuando no hubo conversión (mismo activo en los dos lados).

object

value

La tasa que se te aplicó, con nuestro margen ya dentro

string

market

La tasa de referencia, antes del margen

string

spread_bps

La diferencia entre las dos, en puntos básicos. 50 = 0,50 %

integer

status

string

Allowed values: open consumed expired

expires_at

string format: date-time

created_at

string format: date-time

Examples

fixed: deliver — 50.000,00 Bs entregados, 500,00 Bs de comisión

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

fixed: spend — misma forma, con la tasa rellena

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

400

Error con código estable

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error provider_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

422

Error con código estable

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error provider_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

503

Error con código estable

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error provider_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}

Cotizar una dispersión

Authorizations

Request Bodyrequired

Examples

Responses

201

Examples

400

Example

422

Example

503

Example

Request Body^required