USD, USDT, USDC,
BTC, GOLD, SILVER y PLATINUM — de forma síncrona e instantánea, sin que la plata salga
de tu cuenta. Cualquier par funciona (también BTC ↔ GOLD directo,
y USD ↔ USDT a 1:1 exacto); el fiat local (BOB, MXN, ARS) aún
no es intercambiable (invalid_pair). La
tasa que ves en la cotización es la tasa a la que se ejecuta: no hay
comisiones aparte — cotizado = recibido.
1. Cotiza (opcional, gratis)
POST (los precios de BTC y GOLD se mueven). Para pares entre
stablecoins (USDT ↔ USDC) la tasa es estable.
2. Ejecuta el swap
amount va en la moneda de origen (from_asset), con hasta sus
decimales (6 para USDT/USDC/GOLD/SILVER/PLATINUM, 8 para BTC).
Respuesta 201 — el swap es síncrono, tu saldo cambia al instante:
idempotency_key → 200 con el swap original y
idempotency_hit: true — jamás se re-ejecuta.
3. Consulta e historial
GET /v1/movements) y en la
cartola el swap aparece como swap_out en la moneda
de origen y swap_in en la de destino, cada uno cuadrando en su sección.
Reglas y límites
- Misma cuenta: la plata nunca sale de tu cuenta — solo cambia de moneda. Por eso no pide OTP.
- Cualquier par entre
USDT,USDC,BTCyGOLD(origen ≠ destino). - Tasa de ejecución del momento: para BTC y GOLD se usa el precio de
ejecución en vivo; si el precio no está disponible o está desactualizado,
el swap se rechaza con
503 pricing_unavailable(nunca se ejecuta con un precio viejo). - Límites para monedas volátiles (BTC/GOLD/SILVER/PLATINUM, compartidos con payouts y
compras con tarjeta): tope por operación y tope de volumen por cuenta en
24 h móviles (
GET /v1/settlementmuestra los tuyos). USDT ↔ USDC no tiene límite. - Requiere tu verificación de identidad aprobada y el
servicio
swapshabilitado.
Protección de precio BTC
Para swaps BTC de USD 1.000 o más, CBPay compara la referencia de ejecución con el libro de mercado antes del swap. Si la divergencia supera el umbral configurado, responde422 guard_diverged; espera la convergencia o divide la
operación y reintenta con la misma idempotency_key. Si el mercado no está
disponible temporalmente, el swap puede continuar con una alerta operativa y
siguen aplicando las protecciones del precio de ejecución. Esta protección no
aplica a conversiones internas de checkout/payin ni a flujos OTC.
Errores
Preguntas frecuentes
¿Por qué la tasa del swap difiere del precio de mercado que veo en otros lados?
¿Por qué la tasa del swap difiere del precio de mercado que veo en otros lados?
La tasa cotizada es la tasa de ejecución de tu cuenta: incluye el costo
de proveer la conversión instantánea y garantizada (liquidez inmediata, sin
slippage, sin salir de tu cuenta). Es la misma filosofía de las tasas de
payouts y payins: lo cotizado es exactamente lo que recibes, sin comisiones
sorpresa después.
¿La cotización del quote está garantizada?
¿La cotización del quote está garantizada?
No — es indicativa. BTC y GOLD se mueven, así que la ejecución usa el
precio del momento del POST. Entre stablecoins (USDT ↔ USDC) la diferencia
es imperceptible. Si necesitas certeza absoluta del monto recibido, revisa
el
to_amount de la respuesta del swap (esa es la cifra final, ya
acreditada).¿Puedo deshacer un swap?
¿Puedo deshacer un swap?
No hay “deshacer”: un swap ejecutado es final (tu saldo ya cambió). Puedes
hacer el swap inverso cuando quieras, a la tasa vigente de ese momento.
¿Por qué mi swap BTC→GOLD fue rechazado por límite si era mi primer swap del día?
¿Por qué mi swap BTC→GOLD fue rechazado por límite si era mi primer swap del día?
Los límites de monedas volátiles son compartidos entre swaps, payouts
pagados desde BTC/GOLD/SILVER/PLATINUM y compras con tarjeta desde BTC/GOLD/SILVER/PLATINUM — todos suman
al mismo volumen de 24 h móviles de tu cuenta. Consulta tus topes en
GET /v1/settlement.¿Qué gano teniendo saldo en GOLD o BTC?
¿Qué gano teniendo saldo en GOLD o BTC?
GOLD representa gramos de oro fino y BTC bitcoin: exposición al precio del
activo sin salir del ecosistema. Puedes pagar payouts, comisiones y compras
con tarjeta directo desde esos saldos (settlement multi-asset), y volver a
USDT/USDC cuando quieras con un swap.
USD como activo principal del ledger
Las cuentas usanUSD como valor predeterminado de settlement_asset y
payin_settlement_asset; cámbialo cuando quieras con PUT /v1/settlement.
Las operaciones en vuelo nunca se vuelven a cotizar.
Los montos del ledger en USD usan centavos (dos decimales). Los créditos y
d débitos directos, las comisiones y los flujos de payout, checkout, POS y
tarjetas usan USD solo cuando el campo de activo de ese flujo lo acepta. Los
swaps entre USD y USDT usan paridad 1:1 y no consultan un oráculo FX. BOB,
MXN y ARS siguen siendo activos fiat separados del ledger; en v1 el pricing
de money-out para esos activos sigue no disponible.
Un payin acreditado directamente a una cuenta USD-principal expone
credit_asset: USD y el monto fiat acreditado en centavos; usdt_credited
sigue siendo el equivalente USD para reportes. El hold de una controversia
sigue el activo acreditado: los créditos USD usan hold_asset: USD. disputed y held usan las
unidades del activo retenido; disputed_usdt y held_usdt son equivalentes
normalizados.
El swap puede tener una cobertura interna de back-office. Esto no cambia el
request ni la respuesta de POST /v1/swaps, la tasa de ejecución ni el
contrato del ledger de la cuenta.