Vender dólares con tu tasa

Este modelo es para empresas que venden dólares a sus clientes: el cliente te paga en USDT y el beneficiario recibe bolívares en su banco. El precio lo pones tú. Nosotros entregamos los Bs desde tu cuenta en nuestro aliado de pago y cobramos un fee semanal sobre lo que vendiste. No hay comisión por pago.


Tasa	La tuya: tu tasa de venta del día, sin spread nuestro
Desde dónde se paga	Tu cuenta en nuestro aliado de pago, en bolívares
Qué cobramos	Un % semanal sobre lo vendido en USD. Nada por pago
Qué cobra el aliado	Su comisión, en Bs, de tu misma cuenta. No es nuestra

Los fondos

Dispersas con los bolívares de tu cuenta. Para cada pago necesitas tener el importe más la comisión del aliado. Antes de enviarlo comprobamos tu saldo real: si no alcanza, el pago se rechaza y no sale nada.

Esos bolívares los consigues cambiando dólares en tu propia cuenta. Cada cambio se registra con su tasa, y lo ves en el panel, en «Tus cambios de USD a Bs».

El día a día

Fija tu tasa de venta
Sección titulada «Fija tu tasa de venta»

Una vez al día, o cada vez que cambies tu precio:
Ventana de terminal
```
curl -s $BASE/v1/treasury/sell-rate \
  -H "x-api-key: $KEY" -H 'content-type: application/json' \
  -d '{"asset":"USDT","rate":"1010.50"}'
```
201 Created
```
{ "asset": "USDT", "rate": "1010.50000000", "setAt": "2026-10-14T12:00:03.114Z", "isToday": true }
```
Vale hasta que fijes otra. Si al día siguiente no la cambias, se sigue usando la de ayer: isToday llega en false y el panel te avisa. Sin ninguna tasa fijada, cotizar en USDT da 422 sell_rate_missing.

Puedes acordar con Bolívar Connect que tu tasa la fijemos nosotros al aceptar cada fondeo (la tasa acordada). Desde ese momento esta llamada responde 403 sell_rate_managed_by_platform y tu tasa vigente la ves en GET /v1/treasury/sell-rate y en tu panel. Si no lo acordaste, nada cambia: la fijas tú como siempre.
Cotiza
Sección titulada «Cotiza»

Lo normal es fijar los bolívares que recibe el beneficiario y que te digamos cuántos USDT le cobras a tu cliente:
Ventana de terminal
```
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
```
{
  "fixed": "deliver",
  "deliver": { "asset": "BS",   "amount": "123435" },
  "spend":   { "asset": "USDT", "amount": "1221524" },
  "fee":     { "asset": "BS",   "amount": "0" },
  "rate": { "value": "1010.5", "market": "1010.5", "spread_bps": 0 }
}
```
El beneficiario recibe exactamente 1.234,35 Bs y tú cobras 1,221524 USDT. USDT lleva 6 decimales, así que cualquier importe en bolívares se alcanza sin redondear. Los USDT se redondean hacia arriba al micro-USDT: nunca vendes por debajo de tu tasa.

Si tu cuenta no tiene saldo para el pago y la comisión de la red de pago, la dispersión responde 201 con status: "failed" y reason: "payout_insufficient_balance", sin enviar nada.

También puedes fijar los USDT que paga tu cliente ({"spend":{"asset":"USDT","amount":100000000},"deliver":{"asset":"BS"}}): 100 USDT a 1.010,50 entregan 101.050,00 Bs.
Dispersa
Sección titulada «Dispersa»

Con el id de la cotización, igual que cualquier dispersión. El pago queda guardado con los USDT que vendiste y la tasa a la que los vendiste.

Cuando entra un fondeo nuevo

Si al aceptar un fondeo se fija una tasa de venta nueva, los bolívares que ya tenías se siguen vendiendo a la tasa anterior hasta agotarse, y solo después se vende a la nueva. Si llegan varios fondeos seguidos, se venden en el orden en que entraron.

Una cotización que cruza el límite lleva un desglose (rate_breakdown), del más viejo al más nuevo:

{
  "spend":   { "asset": "USDT", "amount": "95000000" },
  "deliver": { "asset": "BS",   "amount": "9725000" },
  "rate": { "value": "1023.68421053", "market": "1023.68421053", "spread_bps": 0 },
  "rate_breakdown": [
    { "rate": "1000", "spend_amount": "50000000", "deliver_amount": "5000000", "source": "earlier_funding" },
    { "rate": "1050", "spend_amount": "45000000", "deliver_amount": "4725000", "source": "current_rate" }
  ]
}

rate.value sigue siendo la tasa de toda la cotización (spend × rate.value = deliver, truncado) y las patas suman los dos montos. Sin desglose la cotización es la de siempre y la clave no aparece. El precio es el de la cotización: GET /v1/treasury/sell-rate trae earlierTranches con los bolívares que quedan a cada tasa anterior. Si fijas tu tasa a mano, los tramos anteriores se cierran y todo pasa a tu tasa nueva.

El fee semanal

Se calcula sobre lo que vendiste, de lunes a domingo en hora de Venezuela. Consúltalo cuando quieras:

curl -s "$BASE/v1/treasury/volume?from=2026-10-12&to=2026-10-18" -H "x-api-key: $KEY"

Las reglas, para que puedas rehacer la cuenta con tus propios registros:

Cuenta lo liquidado. Un pago que falla no cuenta.
Cada pago vale lo que vendiste: los USDT exactos de su cotización. Un pago sin conversión (Bs → Bs) vale lo que te costaron esos bolívares.
Cada pago paga el % vigente el día que se liquidó. Si el % cambia a mitad de semana, el reporte trae un tramo por cada % (tiers) y el fee es la suma. Un cambio de % nunca mueve una semana ya reportada.
Una devolución del banco resta en la semana en que ocurre, al % que pagó.
Sin redondeos intermedios. Los USDT se suman exactos y el fee de cada tramo se redondea una sola vez al centavo.

Ejemplo con un cambio de % a mitad de semana:

Tramo	Vendido	% (ejemplo)	Fee
Hasta el miércoles	149,662881 USD	1,25 %	1,87
Desde el miércoles	109,936934 USD	1,00 %	1,10
Semana	259,599815 USD		2,97

lines trae cada pago con sus Bs, sus USDT, su tasa y su %, y suma exactamente los totales. El panel lo descarga en CSV con las mismas cifras. La comisión del aliado llega aparte (networkFeeBs): es lo que explica que tu saldo baje algo más que lo que pagaste, pero no es un cobro nuestro. En el sandbox la comisión simulada de la red es 0,3 % (networkFeeBs); en real la fija la red de pago y te llega en el reporte.

El % que te aplicamos y desde cuándo rige: GET /v1/treasury/volume-fee.

En tu cuenta de pruebas

Con tu sk_test_ de la cuenta de pruebas recorres todo esto sin dinero real: POST /v1/test-helpers/seed deja una tasa USDT de ejemplo y 1.000.000,00 Bs en tu inventario, y POST /v1/test-helpers/fundings anota más cambios (con sellRate, el cambio fija tu tasa USDT como un fondeo aceptado y puedes ver el cruce de tasas). Cada pago queda submitted y se liquida solo en unos 20 s, baja tu inventario por el importe más la comisión, y entra en GET /v1/treasury/volume. Ver Entorno de pruebas.