OTC

Todos los endpoints requieren Authorization: Bearer <token> y están delimitados por el tenant (clientId) resuelto desde OAuth.

Visión general

La API de OTC permite que tu tenant solicite y ejecute operaciones de compra/venta de cripto (ej.: USDT/BRL) totalmente vía API. Una sola llamada cotiza, registra y ejecuta la operación.

Cómo funciona la ejecución:

• Pata fiat: tu cuenta bancaria (registrada en el BaaS, resuelta por tu clientId) mueve el BRL con nuestra cuenta de liquidación.
• Pata cripto: la cripto va hacia/desde la dirección de wallet que informas en la solicitud.
• Precio: ya viene con el precio final aplicable a tu tenant — solo informas qué quieres negociar.

Sides:

• BUY — compras cripto y pagas en BRL. La cripto se envía a la walletAddress informada.
• SELL — vendes cripto y recibes BRL. La cripto sale de tu custodia y el BRL se acredita en tu cuenta.

Flujo típico:

1. Cotizar (GET /v1/otc/quote) — opcional, para mostrar precio/volumen al usuario.
2. Solicitar la operación (POST /v1/otc/trades) — cotiza + crea + ejecuta.
3. Seguir (GET /v1/otc/trades/{id}) el status hasta SETTLED.

---

GET /v1/otc/quote

Devuelve el precio aplicable y el volumen/valor resultante. No persiste nada.

Query params:

Param	Type	Required	Description
coin	string	Yes	Activo, ej.: USDT
side	string	Yes	BUY | SELL
mode	string	Yes	BY_FIAT (fijas el BRL) | BY_CRYPTO (fijas el volumen del activo)
amount	number	Yes	BRL cuando BY_FIAT; volumen del activo cuando BY_CRYPTO

Response 200 OK:

{
  "data": {
    "side": "BUY",
    "mode": "BY_FIAT",
    "asset": "USDT",
    "price": 5.5825,
    "volume": 17912.5,
    "fiatAmount": 100000
  }
}

Field	Description
price	Precio por unidad del activo (BRL) que se aplicará
volume	Cantidad del activo
fiatAmount	Valor total en BRL

---

POST /v1/otc/trades

Cotiza, registra y ejecuta la operación. La cuenta bancaria de origen es la de tu tenant; la wallet es la informada aquí.

Headers:

Header	Value
Authorization	Bearer <token>
Content-Type	application/json

Request Body:

{
  "asset": "USDT",
  "side": "BUY",
  "mode": "BY_FIAT",
  "amount": 100000,
  "walletAddress": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "walletNetwork": "TRON"
}

Field	Type	Required	Description
asset	string	Yes	Activo negociado (ej.: USDT). También acepta coin.
side	string	Yes	BUY | SELL
mode	string	Yes	BY_FIAT | BY_CRYPTO
amount	number	Yes	BRL (BY_FIAT) o volumen (BY_CRYPTO)
walletAddress	string	Yes	Dirección cripto (destino en BUY, origen en SELL)
walletNetwork	string	Yes	TRON | EVM | POLYGON | ETHEREUM
bankingAccountId	string	No	Cuenta del tenant; por defecto usa la cuenta activa más reciente

Response 200 OK:

{
  "data": {
    "id": "a1b2c3d4-...",
    "side": "BUY",
    "asset": "USDT",
    "quoteCurrency": "BRL",
    "volume": 17912.5,
    "unitPrice": 5.5825,
    "totalAmount": 100000,
    "walletAddress": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "walletNetwork": "TRON",
    "status": "PROCESSING",
    "txHash": null,
    "createdAt": "2026-06-10T12:00:00.000Z",
    "executedAt": null
  }
}

La ejecución es asíncrona e idempotente: sigue status hasta SETTLED.

Errores comunes: 400 (faltan campos / falta clientId), 404 (sin cotización para el activo / sin cuenta bancaria activa para el tenant).

---

GET /v1/otc/trades

Lista las operaciones de tu tenant (solo las originadas por tu clientId).

Query params: limit, offset (opcionales).

Response 200 OK: array de operaciones (mismo shape que el POST).

---

GET /v1/otc/trades/{id}

Detalle de la operación. Devuelve 404 si la operación no pertenece a tu tenant.

Response 200 OK:

{
  "data": {
    "id": "a1b2c3d4-...",
    "side": "BUY",
    "asset": "USDT",
    "totalAmount": 100000,
    "walletAddress": "TXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "walletNetwork": "TRON",
    "status": "SETTLED",
    "txHash": "0xabc...",
    "createdAt": "2026-06-10T12:00:00.000Z",
    "executedAt": "2026-06-10T12:03:00.000Z"
  }
}

Estados de la operación (status)

Status	Significado
PENDING	Recibido, aún no iniciado
PROCESSING	En proceso (liquidación fiat y/o cripto en curso)
SETTLED	Concluido
FAILED	Falló
CANCELLED	Cancelado

Cuando status es SETTLED en un BUY, el campo txHash trae el hash de la transacción on-chain del envío de la cripto.