OTC

Todos os endpoints exigem Authorization: Bearer <token> e são escopados pelo tenant (clientId) resolvido do OAuth.

Visão geral

A API de OTC permite que o seu tenant solicite e execute trades de compra/venda de cripto (ex.: USDT/BRL) inteiramente via API. Uma única chamada cota, registra e executa a operação.

Como funciona a execução:

• Perna fiat: a sua conta bancária (registrada na BaaS, resolvida pelo seu clientId) movimenta o BRL com a nossa conta de liquidação.
• Perna cripto: a cripto vai/vem do endereço de wallet que você informa na requisição.
• Preço: já vem com o preço final aplicável ao seu tenant — você informa apenas o que quer negociar.

Sides:

• BUY — você compra cripto e paga em BRL. A cripto é enviada para a walletAddress informada.
• SELL — você vende cripto e recebe BRL. A cripto sai da sua custódia e o BRL é creditado na sua conta.

Fluxo típico:

1. Cotar (GET /v1/otc/quote) — opcional, para mostrar preço/volume ao usuário.
2. Solicitar o trade (POST /v1/otc/trades) — cota + cria + executa.
3. Acompanhar (GET /v1/otc/trades/{id}) o status até SETTLED.

---

GET /v1/otc/quote

Retorna o preço aplicável e o volume/valor resultante. Não persiste nada.

Query params:

Param	Type	Required	Description
coin	string	Yes	Ativo, ex.: USDT
side	string	Yes	BUY | SELL
mode	string	Yes	BY_FIAT (você fixa o BRL) | BY_CRYPTO (você fixa o volume do ativo)
amount	number	Yes	BRL quando BY_FIAT; volume do ativo quando BY_CRYPTO

Response 200 OK:

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

Field	Description
price	Preço por unidade do ativo (BRL) que será praticado
volume	Quantidade do ativo
fiatAmount	Valor total em BRL

---

POST /v1/otc/trades

Cota, registra e executa o trade. A conta bancária de origem é a do seu tenant; a wallet é a informada aqui.

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	Ativo negociado (ex.: USDT). Aceita também coin.
side	string	Yes	BUY | SELL
mode	string	Yes	BY_FIAT | BY_CRYPTO
amount	number	Yes	BRL (BY_FIAT) ou volume (BY_CRYPTO)
walletAddress	string	Yes	Endereço de cripto (destino no BUY, origem no SELL)
walletNetwork	string	Yes	TRON | EVM | POLYGON | ETHEREUM
bankingAccountId	string	No	Conta do tenant; por padrão usa a conta ativa mais recente

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

A execução é assíncrona e idempotente: acompanhe status até SETTLED.

Erros comuns: 400 (faltam campos / falta clientId), 404 (sem cotação para o ativo / sem conta bancária ativa para o tenant).

---

GET /v1/otc/trades

Lista os trades do seu tenant (apenas os originados pelo seu clientId).

Query params: limit, offset (opcionais).

Response 200 OK: array de trades (mesmo shape do POST).

---

GET /v1/otc/trades/{id}

Detalhe do trade. Retorna 404 se o trade não pertencer ao seu 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 do trade (status)

Status	Significado
PENDING	Recebido, ainda não iniciado
PROCESSING	Em processamento (liquidação fiat e/ou cripto em andamento)
SETTLED	Concluído
FAILED	Falhou
CANCELLED	Cancelado

Quando status for SETTLED em um BUY, o campo txHash traz o hash da transação on-chain do envio da cripto.