Documentacao da API

Guia completo para integrar com a API do Lexxen Hub.

Copiar para IA (.md): copia uma referencia tecnica enxuta otimizada para LLMs (Claude Code, GPT, Cursor) — cole no chat para que a IA conheca os endpoints, schemas e webhooks da API.

Produtos Disponiveis

PIX — Envio de PIX (BRL)

Crypto — Envio de USDT (TRC20, ERC20, Polygon)

Dupla Autorizacao Obrigatoria

Todas as transacoes (PIX e Crypto) exigem dupla autorizacao. Primeiro crie a solicitacao, depois aprove para que seja processada. Nenhuma transacao e executada sem aprovacao explicita.

Indice

→ Autenticacao → Assinatura HMAC → Idempotencia → Dupla Autorizacao (Fluxo) → Taxas → Cotacao / Quote → Crypto Send → Saldo → OTC (Comprar/Vender) → Fiat (Deposito/Saque BRL) → PIX-to-Wallet (BRL → cripto → wallet) → Crypto Deposit → Webhooks → Codigos de Erro

Autenticacao

Todas as requisicoes devem incluir os seguintes headers:

Header	Descricao
`X-API-Key`	Sua chave de API
`X-Signature`	Assinatura HMAC SHA256 da requisicao
`X-Timestamp`	Timestamp Unix em segundos (valido por 5 minutos)
`Content-Type`	application/json
`Accept`	application/json

Gerando a Assinatura

A assinatura e gerada usando HMAC-SHA256 com a seguinte formula:

payload = METHOD + PATH + TIMESTAMP + BODY
signature = HMAC-SHA256(payload, api_secret)

Exemplo em PHP:

$timestamp = time();
$method = 'POST';
$path = '/api/v1/payouts';
$body = json_encode($data);

$payload = $method . $path . $timestamp . $body;
$signature = hash_hmac('sha256', $payload, $apiSecret);

Exemplo em Node.js:

const crypto = require('crypto');

const timestamp = Math.floor(Date.now() / 1000).toString();
const payload = method + path + timestamp + body;
const signature = crypto
  .createHmac('sha256', apiSecret)
  .update(payload)
  .digest('hex');

Idempotencia

Use o header Idempotency-Key em requisicoes POST/PUT para evitar duplicacoes.

Se uma requisicao com a mesma chave ja foi processada, a resposta original sera retornada com o header X-Idempotency-Replayed: true.

Fluxo de Dupla Autorizacao

Todas as transacoes (PIX e Crypto) seguem o fluxo de dupla autorizacao. Nenhuma transacao e enviada ao provider sem aprovacao explicita.

PENDING_APPROVAL Criar via API/Painel

APPROVED Aprovar via API/Painel

PROCESSING COMPLETED

1. CRIAR — Solicitacao criada via API ou painel. Status: PENDING_APPROVAL

2. APROVAR — Operador ou sistema aprova a solicitacao. Status: APPROVED

3. PROCESSAR — Sistema envia ao provider para execucao. Status: PROCESSING

4. CONCLUIR — Provider confirma a transacao. Status: COMPLETED ou FAILED

Alternativa: A solicitacao pode ser REJECTED a qualquer momento antes do processamento.

Taxas

As taxas sao calculadas automaticamente e retornadas no campo fee_amount da resposta de cada transacao.

PIX

Taxa fixa + percentual variavel, configurada pelo admin por tenant. Exemplo: R$ 1,00 fixo + 0,5% do valor.

Crypto

Taxa total unica (ex: 2 USDT) — ja inclui a taxa do provider. O lucro da Lexxen = taxa total - taxa do provider.

{
  "data": {
    "id": "uuid",
    "amount": 100.00,
    "fee_amount": 2.00,        // taxa cobrada
    "net_amount": 98.00,        // valor liquido
    "status": "PENDING_APPROVAL"
  }
}

A taxa e informada no momento da criacao da solicitacao para que voce possa confirmar antes de aprovar.

Cotacao / Quote

GET /api/v1/crypto/quote Obter cotacao em tempo real

Obtem cotacao em tempo real com simulacao de conversao BRL → Crypto.

Query Parameters:

Parametro	Obrigatorio	Descricao
`asset`	Sim	Ativo (ex: USDT)
`markup_percent`	Nao	Percentual de markup do cliente (0-100)
`amount_brl`	Nao	Valor em BRL para simular conversao
`network`	Nao	Rede: trx, eth, polygon
`quote_type`	Nao	Nivel de preco: market, lexxen, client_final

3 Niveis de Preco

market Preco puro da exchange — cotacao de mercado sem nenhum markup

lexxen Preco com spread da Lexxen — o que a Lexxen cobra (inclui custo operacional)

client_final Preco com markup do cliente em cima do lexxen — preco final para o usuario do cliente

Resposta (sem simulacao - sem amount_brl):

{
  "asset": "USDT",
  "prices": {
    "market": 5.85,
    "lexxen": 5.92,
    "client_final": 6.04
  },
  "markup_percent": 2,
  "quote_type": "client_final"
}

Resposta (com simulacao - amount_brl=1000):

{
  "asset": "USDT",
  "prices": {
    "market": 5.85,
    "lexxen": 5.92,
    "client_final": 6.04
  },
  "markup_percent": 2,
  "quote_type": "client_final",
  "simulation": {
    "amount_brl": 1000,
    "crypto_amount": 165.56,
    "price_used": 6.04,
    "fee_amount": 2.00,
    "net_crypto": 163.56,
    "network": "trx"
  }
}

Crypto

Apenas USDT e suportado. Redes disponiveis: TRC20, ERC20, Polygon.

POST /api/v1/crypto/send Enviar Crypto

Cria uma solicitacao de envio de USDT. Status inicial: PENDING_APPROVAL

Requer aprovacao via endpoint de approve antes de ser processada. Suporta 2 modos de envio:

Modo 1: Envio direto em crypto

Use o campo amount para especificar a quantidade de USDT a enviar.

{
  "amount": 5,                          // quantidade em USDT
  "asset": "USDT",
  "network": "trx",
  "destination": "TAddress...",
  "description": "Saque USDT"          // opcional
}

Modo 2: Envio via BRL (conversao automatica)

Use o campo amount_brl para especificar o valor em Reais. A conversao para USDT e feita automaticamente usando a cotacao em tempo real.

{
  "amount_brl": 1000,                   // valor em BRL
  "asset": "USDT",
  "network": "trx",
  "destination": "TAddress...",
  "markup_percent": 2,                 // markup do cliente (0-100)
  "quote_type": "client_final",        // market, lexxen, client_final
  "auto_convert": true,             // converter BRL->USDT se faltar saldo
  "description": "Saque via BRL"       // opcional
}

Campos adicionais (Modo 2):

`markup_percent`	Percentual de markup do cliente sobre o preco lexxen (0-100)
`quote_type`	Nivel de preco: market (exchange), lexxen (com spread), client_final (com markup)
`auto_convert`	Se `true` e nao houver saldo em USDT, a plataforma converte automaticamente o valor em BRL para USDT antes de enviar (uma etapa OTC adicional). Default: `false`. Exige `amount_brl >= 80,00`.

Como funciona o auto_convert

Calculamos quantos USDT precisamos enviar (com base em amount_brl, markup_percent e quote_type).
Se voce ja tem saldo em USDT suficiente, enviamos direto. Sem conversao.
Se falta USDT mas voce tem saldo em BRL, executamos uma cotacao OTC (generateQuoteOTC + consumeQuoteOTC) usando o amount_brl como total, debitando o BRL e creditando USDT. Em seguida enviamos.
Se nem USDT nem BRL forem suficientes, retornamos INSUFFICIENT_BALANCE.

Os detalhes da conversao (preco, quote_id, brl_spent, crypto_received) sao retornados no webhook transaction.completed dentro do campo auto_conversion.

Taxa de rede: A blockchain cobra uma taxa que e descontada do valor enviado (ex: TRC20 ~1.8 USDT, Polygon ~0.10 USDT). O valor liquido recebido pelo destinatario aparece em net_amount.

Redes suportadas:

trx (TRC20) eth (ERC20) polygon (Polygon)

POST /api/v1/payouts/{id}/approve Aprovar solicitacao crypto (dupla autorizacao)

Aprova uma solicitacao crypto pendente. A transacao so e processada apos a aprovacao.

Requer saldo disponivel suficiente (valor + taxa). Retorna erro se saldo insuficiente.

Resposta:

{
  "data": {
    "id": "uuid",
    "status": "APPROVED",
    "approved_by": "api"
  }
}

GET /api/v1/crypto/wallets Listar wallets

Retorna as wallets disponiveis para envio de crypto.

GET /api/v1/crypto/balance Saldo crypto

Retorna o saldo de USDT disponivel na sua conta.

GET /api/v1/crypto/status/{id} Status da transacao (hash blockchain)

Retorna o status de uma transacao crypto incluindo o hash da blockchain para verificacao on-chain.

Resposta:

{
  "data": {
    "id": "uuid",
    "status": "COMPLETED",
    "tx_hash": "abc123def456...",
    "network": "trx",
    "confirmations": 20
  }
}

Saldo Unificado

GET /api/v1/balance

Retorna o saldo unificado de PIX (BRL) e Crypto (USDT) em uma unica chamada.

OTC — Compra e Venda direta de cripto

A familia /v1/otc/* permite trocar BRL ↔ Cripto sem enviar para uma wallet externa. O resultado vai direto pro saldo do tenant.

• Fluxo em 2 passos: cotar (/quote) e executar (/execute)
• Cotacao expira em 5 segundos
• markup_percent e seu lucro — sempre na moeda destino (USDT na compra, BRL na venda)
• Valor minimo: R$ 80,00 (limite OTC do provider)
• Webhooks: otc.buy.completed, otc.sell.completed, otc.failed

Como o price e o price_with_markup se relacionam

Voce esta "subindo um nivel" em cima da Lexxen: a gente compra do provider, voce compra de nos, e seu usuario final compra de voce.

• price — o que a Lexxen cobra de voce por unidade (= nosso custo no provider, transparente).
• price_with_markup — price × (1 + markup_percent/100) = o que voce pode cobrar do seu usuario final por unidade.
• markup_amount — lucro absoluto na moeda destino (USDT na compra, BRL na venda).
• net_amount — o que efetivamente vai pro saldo do tenant depois de separar o markup.

Exemplo: price=5.85, markup_percent=1.5 → price_with_markup=5.93775. Com amount_brl=1000: lucro 2,564 USDT, liquido 168,376 USDT.

POST /api/v1/otc/buy/quote Cotar compra de cripto

Body:

{
  "asset": "USDT",
  "amount_brl": 1000.00,
  "markup_percent": 1.5
}

Resposta (201):

{
  "data": {
    "id": "uuid",
    "side": "buy",
    "asset": "USDT",
    "amount_brl": "1000.00",
    "amount_crypto": "170.94000000",
    "price": "5.85",                  // nosso custo (Lexxen -> tenant)
    "price_with_markup": "5.93775000",    // seu preco final (tenant -> usuario final)
    "markup_percent": "1.5",
    "markup_amount": "2.56410000",        // seu lucro em USDT
    "net_amount": "168.37590000",         // USDT liquido entregue ao tenant
    "destination_currency": "USDT",
    "status": "pending",
    "expires_at": "2026-04-15T12:34:56+00:00"
  }
}

POST /api/v1/otc/buy/execute Executar compra

Body: { "quote_id": "uuid" }

Debita BRL, credita net_amount USDT no saldo do tenant. markup_amount fica retido para repasse. Dispara webhook otc.buy.completed.

POST /api/v1/otc/sell/quote Cotar venda de cripto

Body:

{
  "asset": "USDT",
  "amount": 100.00,            // quantidade de cripto a vender
  "markup_percent": 1.5
}

Resposta tem mesma estrutura do buy/quote, mas side: "sell", amount_brl vira o que voce vai receber, e markup_amount + net_amount vem em BRL.

POST /api/v1/otc/sell/execute Executar venda

Debita cripto, credita net_amount BRL. Dispara webhook otc.sell.completed.

GET /api/v1/otc/quotes/{id} Detalhes da cotacao

Status atual: pending, executed, expired ou failed.

Fiat — Deposito e Saque BRL via PIX

Mesma titularidade obrigatoria

Tanto deposito quanto saque so podem usar contas/chaves PIX do mesmo CPF/CNPJ cadastrado no tenant. A API valida antes de chamar o provider e o provider tambem valida do lado dele.

POST /api/v1/fiat/deposit Gerar QR Code de deposito PIX

Body:

{
  "value": 250.00,
  "payer_document": "12312312323",    // deve bater com tenant.document
  "custom_id": "pedido-9421"             // opcional
}

Retorna payment_string (copia-e-cola) e qr_code (base64). Quando o PIX cair, voce recebe webhook deposit.fiat.received.

GET /api/v1/fiat/deposits Listar depositos

GET /api/v1/fiat/deposits/{id} Detalhes

POST /api/v1/fiat/withdraw Saque PIX (mesma titularidade)

Body:

{
  "value": 100.00,
  "pix_key": "12312312323",
  "holder_document": "12312312323"   // CPF/CNPJ do titular da chave
}

Valida documento e saldo BRL antes de enviar. Dispara withdraw.fiat.completed.

GET /api/v1/fiat/withdrawals Listar saques

GET /api/v1/fiat/withdrawals/{id} Detalhes

PIX-to-Wallet — BRL via PIX → cripto → wallet externa

Fluxo agregador com aprovacao humana

Orquestra fiat/deposit + otc/buy + crypto/send num unico fluxo idempotente. Cotacao BRL→cripto e tirada quando o PIX cai (nao no request); tenant passa min_amount_out para se proteger de slippage. Aprovacao manual e sempre exigida apos o PIX cair.

Maquina de estados

AWAITING_DEPOSIT  —(PIX cai)→     PENDING_APPROVAL
AWAITING_DEPOSIT  —(expires_at)→  EXPIRED
PENDING_APPROVAL  —(/approve)→    APPROVED  →  PROCESSING  →  COMPLETED
PENDING_APPROVAL  —(/reject)→     REJECTED        (BRL fica saldo)
PROCESSING        —(falha)→       FAILED_POST_DEPOSIT  (BRL fica saldo + email + KPI)

POST /api/v1/pix-to-wallet Criar ordem (gera QR PIX)

Headers extras: Idempotency-Key obrigatorio.

Body:

{
  "amount_brl": 1500.00,
  "asset": "USDT",                  // USDT | BTC | ETH
  "network": "trx",                  // trx | eth | polygon
  "destination_address": "TXY...wallet...",
  "min_amount_out": "499.50",         // piso de slippage
  "markup_percent": 0.5,                // opcional
  "description": "Order #4231",        // opcional
  "expires_in_seconds": 86400           // opcional, default 24h, max 72h
}

Response 201 (resumido):

{
  "data": {
    "id": "01j2k3...",
    "status": "AWAITING_DEPOSIT",
    "pix": {
      "qr_code": "data:image/png;base64,...",
      "payment_string": "00020126...",
      "custom_id": "p2wAbCdEfGh"
    },
    "expires_at": "2026-05-09T15:00:00+00:00"
  }
}

Dispara webhook pix_to_wallet.created. Quando o PIX cair, voce recebe pix_to_wallet.deposit_received e a ordem transita para PENDING_APPROVAL.

POST /api/v1/pix-to-wallet/{id}/approve Aprovar conversao+envio

Headers extras: Idempotency-Key obrigatorio. Body vazio.

Pre-condicao: ordem em PENDING_APPROVAL. Enfileira ProcessPixToWalletJob que cota OTC, valida slippage, consome quote e envia cripto. Erros: 404 (ORDER_NOT_FOUND), 409 (INVALID_STATE).

POST /api/v1/pix-to-wallet/{id}/reject Rejeitar (BRL fica saldo)

Body: { "reason": "..." } opcional.

Pre-condicao: PENDING_APPROVAL. Nao ha refund automatico — BRL fica como saldo do tenant.

GET /api/v1/pix-to-wallet/{id} Detalhe (estado completo)

GET /api/v1/pix-to-wallet Listar (filtros: status, asset, from, to)

Eventos webhook (envelope data compartilhado)

`pix_to_wallet.created`	QR gerado, esperando PIX
`pix_to_wallet.deposit_received`	PIX caiu, aguardando `/approve`
`pix_to_wallet.approved`	Aprovado, conversao+envio em andamento
`pix_to_wallet.rejected`	Rejeitado, BRL fica saldo
`pix_to_wallet.completed`	Envio crypto OK, com `blockchain_hash`
`pix_to_wallet.failed_post_deposit`	Falhou apos PIX (SLIPPAGE/OTC_FAILED/SEND_FAILED); BRL fica saldo
`pix_to_wallet.expired`	PIX nao caiu antes de `expires_at`

Crypto Deposit — Receber Cripto

Wallet e por rede, nao por moeda. Um endereco TRC20 recebe USDT/USDC/etc na rede Tron. Se ja existir, devolvemos; senao, criamos.

POST /api/v1/crypto/wallets/address Obter ou gerar endereco

Body:

{
  "coin": "USDT",
  "network": "trx"
}

Resposta:

{
  "data": {
    "address": "TJYeasrz1dvZ3BqKLR...",
    "coin": "USDT",
    "network": "trx",
    "network_name": "Tron [TRC-20]",
    "created": false            // true se acabou de criar
  }
}

Quando alguem deposita, voce recebe webhook deposit.crypto.received com amount, asset, blockchain_hash e mais.

GET /api/v1/crypto/wallets Listar todas as wallets ja criadas

Webhooks

POST /api/v1/webhooks Criar webhook

Body:

{
  "url": "https://seu-servidor.com/webhook",
  "events": [
    "transaction.created",
    "transaction.approved",
    "transaction.completed",
    "transaction.failed"
  ]
}

O secret sera gerado automaticamente e retornado na resposta.

GET /api/v1/webhooks Listar webhooks

GET /api/v1/webhooks/{id} Detalhes webhook

DELETE /api/v1/webhooks/{id} Remover webhook

Eventos

Evento	Descricao
`transaction.created`	Solicitacao criada (PIX ou Crypto)
`transaction.approved`	Solicitacao aprovada (dupla autorizacao)
`transaction.completed`	Transacao processada com sucesso pelo provider
`transaction.failed`	Transacao falhou no processamento
`otc.buy.completed`	OTC de compra (BRL→Cripto) executado
`otc.sell.completed`	OTC de venda (Cripto→BRL) executado
`otc.failed`	Falha ao executar OTC no provider
`deposit.fiat.received`	Deposito PIX recebido (status processing/credited)
`withdraw.fiat.completed`	Saque PIX executado
`deposit.crypto.received`	Deposito de cripto creditado em uma wallet

Payload do Webhook

Seu endpoint recebera um POST com o seguinte formato:

Headers:

Content-Type: application/json
X-Webhook-Signature: hmac_sha256_do_body
X-Webhook-Event: transaction.completed
User-Agent: LexxenHub/1.0

Body (JSON) - Exemplo CRYPTO:

{
  "event": "transaction.completed",
  "data": {
    "request_id": "uuid",
    "type": "CRYPTO",
    "amount": "5.00000000",
    "fee_amount": "2.00000000",
    "network_fee": "1.80000000",
    "net_amount": "3.20000000",
    "asset": "USDT",
    "network": "TRC20",
    "destination": "TAddress...",
    "status": "COMPLETED",
    "blockchain_hash": "3fb6ad4ff7da746db9021d1a659994cdc85243c5bb6689636bcf7db8cf9413b8",
    "blockchain_explorer": "https://tronscan.org/#/transaction/3fb6ad4ff7da...",
    "provider_transaction_id": "1950405",
    "auto_conversion": {                       // presente quando auto_convert=true e ocorreu conversao
      "quote_id": "USuEcu3s4pwtLZxN23jDCfmJSlYQCNw",
      "transaction_id": "61636",
      "side": "buy",
      "pair": "USDTBRL",
      "brl_spent": "20.00",
      "crypto_received": "1.93457275",
      "price": "10.3382",
      "price_without_markup": "5.1691",
      "liquidation": "d0",
      "executed_at": "2026-04-15T12:34:56+00:00"
    }
  },
  "timestamp": "2026-03-19T05:27:05+00:00"
}

Exemplos por Evento

transaction.created

{
  "event": "transaction.created",
  "data": {
    "request_id": "uuid",
    "type": "PIX",
    "amount": 250.00,
    "fee_amount": 2.00,
    "status": "PENDING_APPROVAL",
    "destination": "[email protected]",
    "pix_key_type": "EMAIL"
  },
  "timestamp": "2026-03-18T22:00:00+00:00"
}

transaction.approved

{
  "event": "transaction.approved",
  "data": {
    "request_id": "uuid",
    "type": "PIX",
    "amount": 250.00,
    "status": "APPROVED",
    "approved_by": "Lexxen Pay"
  },
  "timestamp": "2026-03-18T22:01:00+00:00"
}

transaction.completed (CRYPTO)

{
  "event": "transaction.completed",
  "data": {
    "request_id": "uuid",
    "type": "CRYPTO",
    "amount": "5.00000000",
    "fee_amount": "2.00000000",
    "asset": "USDT",
    "network": "TRC20",
    "destination": "TAddress...",
    "status": "COMPLETED",
    "blockchain_hash": "3fb6ad4ff7da...",
    "provider_transaction_id": "1950405"
  },
  "timestamp": "2026-03-19T05:27:05+00:00"
}

transaction.completed (PIX)

{
  "event": "transaction.completed",
  "data": {
    "request_id": "uuid",
    "type": "PIX",
    "amount": "100.00",
    "fee_amount": "2.00",
    "destination": "[email protected]",
    "pix_key_type": "EMAIL",
    "status": "COMPLETED",
    "e2e_id": "E5481141720260319..."
  },
  "timestamp": "2026-03-19T05:27:05+00:00"
}

transaction.failed

{
  "event": "transaction.failed",
  "data": {
    "request_id": "uuid",
    "type": "CRYPTO",
    "amount": "5.00000000",
    "fee_amount": "2.00000000",
    "status": "FAILED",
    "destination": "TAddress...",
    "asset": "USDT",
    "network": "TRC20",
    "error": "Saldo insuficiente"
  },
  "timestamp": "2026-03-19T05:27:05+00:00"
}

Verificando a Assinatura do Webhook

Cada webhook inclui o header X-Webhook-Signature com a assinatura HMAC SHA256 do body usando o secret do webhook. Sempre valide a assinatura antes de processar o evento.

PHP:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$expected = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // Assinatura valida
}

Node.js:

const crypto = require('crypto');

const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(body)
  .digest('hex');

if (signature === expected) {
    // Assinatura valida
}

Python:

import hmac, hashlib

expected = hmac.new(
    webhook_secret.encode(),
    body.encode(),
    hashlib.sha256
).hexdigest()

if hmac.compare_digest(signature, expected):
    # Assinatura valida

Retentativas

Se seu endpoint retornar um status diferente de 2xx, o webhook sera reenviado automaticamente:

1a tentativa: 10s 2a tentativa: 30s 3a tentativa: 1min 4a tentativa: 5min 5a tentativa: 15min

Apos 5 tentativas sem sucesso, o webhook e marcado como falho.

Limites e Regras

Regra	PIX	Crypto
Valor minimo	R$ 50,00	$10,00
Dupla autorizacao	Obrigatoria	Obrigatoria
Tipo de chave	CPF, CNPJ, EMAIL, PHONE, RANDOM	N/A
Asset suportado	N/A	USDT
Redes aceitas	N/A	TRC20, ERC20, Polygon
Timestamp valido	5 minutos (anti-replay)

Codigos de Erro

Status HTTP

Codigo	Descricao
`200`	Sucesso
`201`	Recurso criado (solicitacao registrada)
`401`	Headers de autenticacao invalidos ou ausentes
`404`	Recurso nao encontrado
`409`	Idempotency-Key ja processada (resposta repetida)
`422`	Erro de validacao ou regra de negocio
`429`	Rate limit excedido
`500`	Erro interno

Erros de Autenticacao

Mensagem	Causa / Solucao
`Missing authentication headers`	Envie X-API-Key, X-Timestamp, X-Signature
`Request timestamp expired`	Timestamp velho — sincronize relogio (limite: 5 min)
`Invalid API key`	Verifique a API Key no painel
`Invalid signature`	Assinatura HMAC nao confere — ordem: timestamp+method+path+body
`Tenant is inactive`	Conta desativada — contate o suporte

Erros de Transacao

Mensagem	HTTP	Causa / Solucao
`Saldo insuficiente para aprovar`	422	Saldo < amount + fee. Consulte `GET /balance`
`Esta solicitacao nao pode ser aprovada`	422	Status nao permite. Verifique se esta em PENDING_APPROVAL
`Envie amount OU amount_brl, nao ambos`	422	Use apenas um dos campos
`Informe amount ou amount_brl.`	422	Nenhum dos dois enviado
`Network e obrigatoria`	422	Informe `trx`, `eth` ou `polygon`
`Endereco de destino e obrigatorio.`	422	Informe a wallet ou chave PIX
`Markup nao pode ser negativo.`	422	Envie valor entre 0 e 100
`Markup maximo: 100%.`	422	Envie valor entre 0 e 100
`Falha na cotacao: ...`	422	Erro temporario ao consultar preco. Tente novamente

Erros de Auto-conversao (`auto_convert: true`)

Mensagem	HTTP	Causa / Solucao
`Valor minimo para auto_convert (OTC) e R$ 80,00.`	422	`amount_brl < 80` — limite minimo do OTC do provider
`Auto-conversao falhou na cotacao OTC: ...`	500	Falha em `generateQuoteOTC` — tente novamente
`Auto-conversao falhou ao executar OTC: ...`	500	Saldo BRL insuficiente ou cotacao expirada — verifique `GET /balance`

O minimo de R$ 80,00 e exigido apenas quando auto_convert: true. Se voce ja tem saldo USDT suficiente, qualquer valor de amount_brl e aceito.

Notas Importantes

Todas as respostas seguem formato JSON. Timestamps em ISO 8601.
IDs de transacao sao UUIDs.
Nenhuma transacao e executada sem aprovacao (dupla autorizacao).
Taxas sao retornadas no campo fee_amount de cada resposta.
Produtos suportados: PIX (BRL) e Crypto (USDT em TRC20, ERC20, Polygon).
Mantenha seu api_secret seguro e nunca exponha no frontend.

Documentacao da API

Produtos Disponiveis

Dupla Autorizacao Obrigatoria

Indice

Autenticacao

Gerando a Assinatura

Idempotencia

Fluxo de Dupla Autorizacao

Taxas

Cotacao / Quote

Crypto

Saldo Unificado

OTC — Compra e Venda direta de cripto

Fiat — Deposito e Saque BRL via PIX

PIX-to-Wallet — BRL via PIX → cripto → wallet externa

Crypto Deposit — Receber Cripto

Webhooks

Eventos

Payload do Webhook

Exemplos por Evento

Verificando a Assinatura do Webhook

Retentativas

Limites e Regras

Codigos de Erro

Status HTTP

Erros de Autenticacao

Erros de Transacao

Erros de Auto-conversao (auto_convert: true)

Notas Importantes

Erros de Auto-conversao (`auto_convert: true`)