Saltar al contenido principal

​
Cuatro saldos virtuales independientes

Cada cuenta mantiene cuatro saldos virtuales, uno por moneda. Son totalmente independientes entre sí: nunca se mezclan ni se convierten automáticamente.
MonedaQué esDecimalesCómo se fondea
USDTStablecoin USD — la moneda operativa6Payins fiat, depósitos on-chain (TRON/Ethereum), transferencias
USDCStablecoin USD6Depósitos on-chain (Ethereum), transferencias
BTCBitcoin8 (satoshis)Abonos del operador y transferencias internas
GOLDGramos de oro fino con respaldo en custodio6Abonos del operador y transferencias internas
GET /v1/balances devuelve siempre los cuatro (con ceros si no has operado esa moneda), como strings decimales: 
{
  "account_id": "…",
  "balances": [
    { "asset": "USDT", "available": "125.430000", "held": "10.000000" },
    { "asset": "USDC", "available": "50.000000", "held": "0.000000" },
    { "asset": "BTC", "available": "0.00060000", "held": "0.00000000" },
    { "asset": "GOLD", "available": "12.500000", "held": "0.000000" }
  ]
}
Internamente cada monto se almacena como entero en la unidad mínima de su moneda (micro-USDT, satoshis, micro-gramos) y se calcula con aritmética racional exacta. Nunca hay floats ni errores de redondeo acumulados.
USDT es la moneda operativa: los precios de payouts, payins fiat y comisiones de servicios se cotizan siempre en USDT. Pero el pago puede salir de cualquiera de los cuatro saldos — ver Elige desde qué saldo pagas. Los payins siempre acreditan al saldo USDT; los otros saldos se fondean con transferencias internas (siempre entre saldos de la misma moneda), depósitos on-chain (USDC) o abonos de tu operador (BTC y GOLD).

​
Elige desde qué saldo pagas

Los payouts y las comisiones de servicios (KYC, creación de wallets, banking) pueden debitarse desde cualquiera de tus cuatro saldos. El pipeline de pricing no cambia: la operación se cotiza en USDT como siempre, y al final el total se traduce al asset elegido con el precio efectivo de settlement del momento.
  • Predeterminado por cuenta: PUT /v1/settlement con {"default_settlement_asset": "BTC"}. Desde ahí, todo payout y toda comisión de servicio sale del saldo BTC (si alcanza; no hay cascadas a otros saldos).
  • Override por operación: envía settlement_asset en POST /v1/payouts (o en el confirm de QR) para pagar esa operación puntual desde otro saldo, sin tocar el predeterminado.
# Definir BTC como saldo de pago predeterminado
curl -X PUT "https://api.qbank.cl/platform/v1/settlement" \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"default_settlement_asset": "BTC"}'
Reglas del settlement multi-asset:
ReglaDetalle
Precio de ejecuciónBTC y GOLD usan un feed on-chain de ejecución (no el precio de referencia). Si el feed está viejo o no disponible, la operación devuelve 503 pricing_unavailable — nunca se ejecuta con un precio dudoso.
Débito, hold y reembolsoLos tres viven en el asset elegido. Si el payout falla, se reembolsa el settlement_amount exacto — jamás se re-cotiza.
IdempotenciaEl replay con la misma llave devuelve el monto original; el precio no se recalcula.
Límite por operaciónLos assets volátiles (BTC/GOLD) tienen un límite por operación (equivalente USDT, visible en GET /v1/settlement); si lo superas: 422 settlement_limit_exceeded.
Límite diario por cuentaLos assets volátiles también tienen un tope de volumen en 24 h móviles (volatile_daily_limit_usdt en GET /v1/settlement); al superarlo: 422 settlement_daily_limit_exceeded. Paga en USDT/USDC o reintenta más tarde.
USDTSigue siendo el camino por defecto y no cambia en nada para quien no toca esta configuración.
El bloque settlement de GET /v1/rates muestra el precio efectivo por asset (spread incluido) para estimar antes de operar, y la respuesta del payout registra settlement_asset, settlement_amount y settlement_rate para auditoría.

​
available y held

Cada saldo tiene sus dos contadores:
CampoSignificado
availableSaldo disponible para operar
heldReservado por operaciones en vuelo (payouts y retiros pendientes)
Cuando creas un payout o retiro, el débito (monto + comisión) sale de available y queda en held hasta que la operación llega a estado final:
  • completed → el hold se consume; el dinero salió.
  • failed → se reembolsa el débito completo (monto + comisión) a available.

​
Conversión FX (fiat ↔ USDT)

Las operaciones fiat se convierten a USDT con las tasas de tu cuenta al momento de ejecutar (las mismas que devuelve GET /v1/rates, base USD): rate para payouts y payin_rate para payins. La conversión redondea hacia arriba en los débitos y hacia abajo en los abonos, con una diferencia máxima de 1 micro-USDT. Ejemplo de un payout de 50.000 CLP con tasa 950.25: 
usdt_amount = ceil(50000 / 950.25 × 10^6) / 10^6 = 52.618258 USDT
total_debit = usdt_amount + fee
Ejemplo de un payin de 50.000 CLP con payin_rate 955.10: 
usdt_gross    = floor(50000 / 955.10 × 10^6) / 10^6 = 52.350539 USDT
usdt_credited = usdt_gross − fee
La tasa usada queda registrada en el objeto (fx_rate) para auditoría.

​
Precios de referencia y de settlement

GET /v1/rates incluye un bloque asset_prices con el precio USD de referencia de cada moneda (BTC por unidad, GOLD por gramo; USDT y USDC valen 1 por convención), para valorizar tus saldos en pantalla, y un bloque settlement con el precio efectivo al que se valoraría tu saldo si pagas una operación desde ese asset (spread incluido): 
{
  "asset_prices": {
    "USDT": { "currency": "USD", "unit": "usdt", "price": "1" },
    "USDC": { "currency": "USD", "unit": "usdc", "price": "1" },
    "BTC": { "currency": "USD", "unit": "btc", "price": "109853.24",
             "updated_at": "2026-07-07T11:59:41Z",
             "settlement_grade": true },
    "GOLD": { "currency": "USD", "unit": "gram", "price": "107.5341",
              "updated_at": "2026-07-07T09:12:05Z",
              "settlement_grade": true }
  },
  "settlement": {
    "default_asset": "USDT",
    "assets": [
      { "asset": "USDT", "available": true, "settlement_rate": "1" },
      { "asset": "USDC", "available": true, "settlement_rate": "0.99900000" },
      { "asset": "BTC", "available": true, "settlement_rate": "109029.34070000" },
      { "asset": "GOLD", "available": true, "settlement_rate": "106.99642950" }
    ]
  }
}
settlement_grade: true indica que el precio está lo bastante fresco para ejecutar operaciones; si baja a false, los pagos desde ese asset responden 503 pricing_unavailable hasta que el precio vuelva.

​
Ledger inmutable

Cada movimiento genera una entrada inmutable con saldo resultante (balance_after) en la moneda del movimiento. Tu historial completo está en GET /v1/movements (filtra por moneda con ?asset=):
typeQué representa
payin_creditAbono de un cobro fiat
payout_debit / payout_refundDébito de payout / reembolso si falló
transfer_in / transfer_outTransferencia interna recibida / enviada
fundingDepósito on-chain acreditado (USDT o USDC, cada uno en su saldo)
withdrawal_debit / withdrawal_refundRetiro on-chain / reembolso si falló
compliance_fee / compliance_refundCargo por servicio KYC/KYB / reembolso
wallet_creation_fee / wallet_creation_refundCargo por creación de wallet / reembolso
adjustmentAjuste manual de CBPay (auditado)
curl "https://api.qbank.cl/platform/v1/movements?type=payout_debit&from=2026-07-01&to=2026-07-07&page_size=20" \
  -H "Authorization: Bearer <token>"

# Solo los movimientos del saldo GOLD
curl "https://api.qbank.cl/platform/v1/movements?asset=GOLD&from=2026-07-01&to=2026-07-07" \
  -H "Authorization: Bearer <token>"
Todos los listados (/v1/movements, /v1/payouts, /v1/payins, /v1/crypto/transactions, /v1/banking/operations) aceptan paginación (page, page_size hasta 200) y filtros de fecha from/to (YYYY-MM-DD, UTC, inclusive).

​
Estados de operación

Payouts y retiros crypto siguen el mismo ciclo: Los estados finales (completed/failed) llegan por webhook; no es necesario hacer polling.
Última modificación el 12 de julio de 2026