Avant Global — API Reference v1 · REST · JSON

Avant Global API

Conecte sua mesa OTC ou gateway de pagamentos a Avant como provedor de liquidez USDT/BRL. Solicite cotacoes, gere cobranças PIX e receba webhooks em tempo real — tudo via uma unica integracao REST.

Base URL: api.avantglobal.com.br TRC-20 / USDT · PIX BRL HTTPS + HMAC-SHA256

Autenticacao

Toda requisicao requer sua API key no header X-Api-Key. Chaves sao emitidas por integracao — entre em contato com a Avant para receber a sua.

!
Mantenha sua chave em segredo. Nunca exponha em codigo client-side, repositorios publicos ou logs. Trate como uma senha.
Header
HTTP
X-Api-Key: avant_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Chaves de producao tem prefixo avant_. Chaves sandbox tem prefixo avant_test_. Todas as requisicoes devem usar HTTPS.

Resposta de erro — 401
JSON
{
  "error": {
    "code":    "api_key_invalid",
    "message": "API key invalida ou inativa."
  }
}

Ambiente Sandbox

O ambiente sandbox permite testar sua integracao completa — cotacoes, PIX, webhooks — sem movimentar dinheiro real.

i
Ativacao: Use uma API key com prefixo avant_test_. Todas as operacoes criadas com chave de teste sao isoladas da producao e marcadas com "sandbox": true nas respostas.

Preco simulado: BRL 5.85 / USDT (fixo). O spread do cliente e aplicado normalmente.

PIX QR code: Estruturalmente valido mas nao pagavel. Use POST /v1/sandbox/pix-pay para simular o pagamento.
Fluxo Sandbox
PassoAcaoObservacao
1POST /v1/quoteRetorna quote_ready imediatamente com preco simulado
2POST /v1/quote/confirmRetorna QR code PIX fake — nao tente pagar
3POST /v1/sandbox/pix-paySimula pagamento — dispara 3 webhooks (pix_confirmed, usdt_sent, complete)
4GET /v1/operation/{id}Verifique que o estado final e complete com tx_hash fake
Operacoes sandbox nao afetam limites diarios de producao e nao geram notificacoes internas. Use livremente para testes.

Endpoints

Todos os endpoints retornam Content-Type: application/json. Respostas de sucesso encapsulam dados em data; erros em error.

$
Formula de precificacao: O preco exibido ao cliente (preco_avant) e derivado do rate do eNor descontando o spread interno e aplicando o spread contratado com o cliente. O campo valor_brl e o total em reais a pagar via PIX.
preco_tela = preco_enor / (1 + enor_spread) # enor_spread padrao: 0.0019
preco_avant = preco_tela x (1 + spread_cliente)
valor_brl = preco_avant x valor_usdt
POST /v1/quote Solicitar cotacao USDT

Cria uma nova operacao de compra. Retorna uma cotacao travada (quote_ready) quando a taxa de mercado esta disponivel, ou quote_requested quando precificacao manual e necessaria — poll GET /v1/quote/{id} ate ficar pronta.

Request body
CampoTipoObrigatorioDescricao
valor_usdt float required Quantidade de USDT para comprar. Minimo: 100.
wallet_trc20 string required Carteira TRC-20 de destino. Deve comecar com T, exatamente 34 caracteres.
Request
cURL
curl -X POST https://api.avantglobal.com.br/v1/quote \
  -H "X-Api-Key: avant_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "valor_usdt":   500,
    "wallet_trc20": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
  }'
Response · 201 quote_ready
JSON
{
  "data": {
    "operation_id":     "OTC20260401120000AABB1234",
    "estado":           "quote_ready",
    "valor_usdt":       500,
    "preco_avant":      6.25,
    "valor_brl":        3125.00,
    "quote_expires_at": "2026-04-01T12:10:00Z",
    "expires_in":       600,
    "sandbox":          false
  }
}
Response · 202 quote_requested
JSON
{
  "data": {
    "operation_id": "OTC20260401120000AABB1234",
    "estado":       "quote_requested",
    "valor_usdt":   500,
    "message":      "Cotacao em processamento..."
  }
}
i
preco_avant e a taxa BRL/USDT incluindo o spread da Avant. valor_brl e o valor exato que o cliente deve pagar via PIX. Cotacoes sao validas por 10 minutos.
POST /v1/quote/confirm Aceitar cotacao · gerar PIX

Trava a cotacao e gera um QR code PIX dinamico para o cliente pagar. Operacao move para awaiting_pix. PIX expira em 15 minutos.

Request body
CampoTipoObrigatorioDescricao
op_id string required Operation ID retornado por POST /v1/quote. Deve estar em quote_ready.
Request
cURL
curl -X POST https://api.avantglobal.com.br/v1/quote/confirm \
  -H "X-Api-Key: avant_your_key" \
  -H "Content-Type: application/json" \
  -d '{"op_id": "OTC20260401120000AABB1234"}'
Response · 200
JSON
{
  "data": {
    "operation_id":   "OTC20260401120000AABB1234",
    "estado":         "awaiting_pix",
    "pix_qrcode":     "00020101021226990014br.gov...",
    "valor_brl":      3125.00,
    "pix_expires_at": "2026-04-01T12:25:00Z",
    "expires_in":     900
  }
}
pix_qrcode e uma string PIX Copia e Cola. Apresente ao cliente ou renderize como QR code. Apos pago, a Avant processa a entrega de USDT automaticamente e dispara webhooks.
POST /v1/quote/cancel Cancelar cotacao

Cancela uma operacao enquanto ainda esta na fase de cotacao. Uma vez que o PIX e gerado (awaiting_pix ou posterior), a operacao nao pode ser cancelada via API — entre em contato com a Avant.

Request body
CampoTipoObrigatorioDescricao
op_id string required Operation ID a cancelar. Deve estar em quote_requested, quote_ready ou quote_expired.
Request
cURL
curl -X POST https://api.avantglobal.com.br/v1/quote/cancel \
  -H "X-Api-Key: avant_your_key" \
  -H "Content-Type: application/json" \
  -d '{"op_id": "OTC20260401120000AABB1234"}'
Response · 200
JSON
{
  "data": {
    "operation_id": "OTC20260401120000AABB1234",
    "estado":       "cancelled",
    "message":      "Operacao cancelada com sucesso."
  }
}
GET /v1/quote/{id} Consultar status da cotacao

Retorna o estado atual de uma cotacao. Poll a cada 5-10 segundos enquanto estado = quote_requested. Quando quote_ready, prossiga para confirmar.

Request
cURL
curl https://api.avantglobal.com.br/v1/quote/OTC20260401120000AABB1234 \
  -H "X-Api-Key: avant_your_key"
Response · 200
JSON
{
  "data": {
    "operation_id":     "OTC20260401120000AABB1234",
    "estado":           "quote_ready",
    "valor_usdt":       500,
    "preco_avant":      6.25,
    "valor_brl":        3125.00,
    "quote_expires_at": "2026-04-01T12:10:00Z"
  }
}
GET /v1/operation/{id} Status completo da operacao

Retorna o estado completo da operacao incluindo QR code PIX (quando gerado) e TX hash (quando USDT e enviado). Ideal para paginas de status e auditoria.

Request
cURL
curl https://api.avantglobal.com.br/v1/operation/OTC20260401120000AABB1234 \
  -H "X-Api-Key: avant_your_key"
Response · 200 (complete)
JSON
{
  "data": {
    "operation_id": "OTC20260401120000AABB1234",
    "estado":       "complete",
    "valor_usdt":   500,
    "wallet_trc20": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "preco_avant":  6.25,
    "valor_brl":    3125.00,
    "hash_tx":      "a1b2c3d4e5f6...",
    "tronscan_url": "https://tronscan.org/#/transaction/...",
    "sandbox":      false,
    "created_at":   "2026-04-01T12:00:00Z",
    "completed_at": "2026-04-01T12:18:42Z"
  }
}
POST /v1/sandbox/pix-pay Simular pagamento PIX SANDBOX

Simula pagamento PIX no sandbox. Transiciona a operacao pelo fluxo completo — pix_confirmedusdt_sentcomplete — e dispara todos os 3 webhooks. Disponivel apenas com chaves avant_test_.

Request body
CampoTipoObrigatorioDescricao
op_id string required Operation ID em estado awaiting_pix.
Request
cURL
curl -X POST https://api.avantglobal.com.br/v1/sandbox/pix-pay \
  -H "X-Api-Key: avant_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"op_id": "OTC20260401120000AABB1234"}'
Response · 200
JSON
{
  "data": {
    "operation_id": "OTC20260401120000AABB1234",
    "estado":       "complete",
    "tx_hash":      "SANDBOX_TX_A1B2C3D4...",
    "simulated":    ["pix_confirmed", "usdt_sent", "complete"],
    "webhooks":     3,
    "sandbox":      true,
    "message":      "Fluxo completo simulado."
  }
}

Webhooks

A Avant envia um POST assinado para sua webhook_url a cada mudanca de estado. Registre seu endpoint ao solicitar acesso a API.

i
Seu endpoint deve responder com HTTP 200 em ate 10 segundos. Retorne 200 imediatamente e processe de forma assincrona se necessario.
!
Politica de retry automatico: Em caso de falha (non-2xx ou timeout), a Avant reenvia ate 4 vezes com backoff exponencial — 1 min → 5 min → 30 min → 2 h. O header X-Avant-Retry: N indica a tentativa. Implemente idempotencia usando operation_id + event como chave de deduplicacao.
Estrutura do payload
JSON
{
  "event":        "pix_confirmed",
  "operation_id": "OTC20260401120000AABB1234",
  "timestamp":    1775000000,
  "data": {
    // campos especificos do evento
  }
}
Autenticacao — Header X-Avant-Signature
i
Todo webhook carrega o header X-Avant-Signature: sha256=HMAC. O HMAC e calculado com HMAC-SHA256 do body JSON usando o webhook_secret fornecido junto com sua API key. Use hash_equals() para comparar (previne timing attacks).
Headers enviados pela Avant
HTTP
X-Avant-Signature: sha256=a1b2c3d4e5f6...
X-Avant-Event:     pix_confirmed
X-Avant-Retry:     0
Verificacao em PHP
PHP
$body   = file_get_contents('php://input');
$sig    = $_SERVER['HTTP_X_AVANT_SIGNATURE'] ?? '';
$expect = 'sha256=' . hash_hmac('sha256', $body, $webhook_secret);

if (!hash_equals($expect, $sig)) {
  http_response_code(401);
  exit;
}
Eventos
pix_confirmed
Pagamento PIX recebido. Avant esta processando a entrega de USDT. data inclui valor_brl, valor_usdt.
usdt_sent
USDT enviado para a carteira do cliente. data inclui tx_hash, tronscan_url, valor_usdt, wallet_trc20.
complete
Operacao totalmente confirmada. data inclui operation_id, valor_usdt, tx_hash.
quote_ready
Cotacao precificada e pronta para confirmacao. data inclui preco_avant, valor_brl, expires_in.
pix_generated
QR code PIX gerado apos confirmacao. data inclui pix_qrcode, valor_brl, pix_expires_at.
cancelled
Operacao cancelada pelo cliente. Nenhuma mudanca de estado adicional ocorrera.

Fluxo de Estados

Toda operacao progride por um conjunto definido de estados. Estados terminais sao complete, cancelled, quote_expired e pix_expired.

quote_requested awaiting_pix pix_confirmed usdt_sent complete
quote_expired pix_expired cancelled failed
i
quote_expired ocorre se a cotacao nao for confirmada em 10 minutos. pix_expired se o PIX nao for pago em 15 minutos. Em ambos os casos, crie uma nova cotacao.
EstadoDescricaoProxima acao
quote_requestedCotacao recebida, precificacao pendentePoll GET /v1/quote/{id}
quote_readyPreco travado, valido por 10 minChamar POST /v1/quote/confirm
awaiting_pixPIX gerado, aguardando pagamentoCliente paga o QR code PIX
pix_confirmedPagamento recebido, processando USDTAguardar webhook usdt_sent
usdt_sentUSDT enviado on-chainVerificar TX no TronScan
completeEntrega confirmada
quote_expiredTTL da cotacao expirado sem confirmacaoCriar nova cotacao
pix_expiredPIX nao pago em 15 minCriar nova cotacao
cancelledCancelado pelo cliente
failedFalha no processamentoContatar Avant

Codigos de Erro

Todos os erros retornam um JSON com error.code (machine-readable) e error.message (human-readable).

Formato de erro
{
  "error": {
    "code":    "invalid_wallet",
    "message": "Endereco TRC-20 invalido. Deve comecar com T e ter 34 caracteres."
  }
}
HTTP
code
Quando ocorre
401
api_key_missing
Header X-Api-Key nao fornecido
401
api_key_invalid
Chave nao encontrada ou inativa
403
ip_not_allowed
IP da requisicao fora da whitelist
403
daily_limit_exceeded
Limite diario de volume atingido
404
operation_not_found
ID nao encontrado ou pertence a outra chave
409
invalid_state
Acao nao permitida no estado atual
409
cannot_cancel
Operacao ja passou da fase cancelavel
410
quote_expired
TTL da cotacao expirou — solicite uma nova
422
invalid_wallet
wallet_trc20 falhou na validacao TRC-20
422
below_minimum
valor_usdt abaixo do minimo de 100 USDT
429
rate_limit_exceeded
Mais de 60 requisicoes/min para esta chave
500
sandbox_only
Endpoint exclusivo sandbox chamado com chave de producao
502
pix_creation_failed
Erro no provedor PIX upstream — retry
Limites
ParametroValorObservacao
Operacao minima100 USDTPor cotacao
Quote TTL10 minApos expirar, solicite nova cotacao
PIX TTL15 minValidade do QR code apos confirm
Rate limit60 req/minPor API key · 429 quando excedido
Limite diarioconfiguravelDefinido por chave · 0 = ilimitado
IP whitelistopcionalRestrinja a IPs especificos por chave
Webhook timeout10 sSeu endpoint deve responder em ate 10 s

SDKs & Exemplos

Exemplos completos de integracao em diferentes linguagens. Todos os exemplos usam chave sandbox para seguranca.

cURL — Fluxo completo
Bash
# 1. Solicitar cotacao
curl -X POST https://api.avantglobal.com.br/v1/quote \
  -H "X-Api-Key: avant_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"valor_usdt": 500, "wallet_trc20": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"}'

# 2. Confirmar cotacao (use o operation_id retornado)
curl -X POST https://api.avantglobal.com.br/v1/quote/confirm \
  -H "X-Api-Key: avant_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"op_id": "OTC20260401120000AABB1234"}'

# 3. Simular pagamento PIX (sandbox only)
curl -X POST https://api.avantglobal.com.br/v1/sandbox/pix-pay \
  -H "X-Api-Key: avant_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"op_id": "OTC20260401120000AABB1234"}'

# 4. Verificar estado final
curl https://api.avantglobal.com.br/v1/operation/OTC20260401120000AABB1234 \
  -H "X-Api-Key: avant_test_your_key"
Python — Integracao completa
Python
import requests
import hmac
import hashlib
import json

API_KEY = "avant_test_your_key"
BASE    = "https://api.avantglobal.com.br"
HEADERS = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

# 1. Solicitar cotacao
resp = requests.post(f"{BASE}/v1/quote", headers=HEADERS, json={
    "valor_usdt":   500,
    "wallet_trc20": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
})
data = resp.json()["data"]
op_id = data["operation_id"]
print(f"Cotacao: {data['preco_avant']} BRL/USDT | Total: R$ {data['valor_brl']}")

# 2. Confirmar e receber PIX
resp = requests.post(f"{BASE}/v1/quote/confirm", headers=HEADERS, json={"op_id": op_id})
pix = resp.json()["data"]
print(f"PIX QR Code: {pix['pix_qrcode'][:50]}...")

# 3. Simular pagamento (sandbox)
resp = requests.post(f"{BASE}/v1/sandbox/pix-pay", headers=HEADERS, json={"op_id": op_id})
print(f"Status: {resp.json()['data']['estado']}")

# 4. Verificar operacao
resp = requests.get(f"{BASE}/v1/operation/{op_id}", headers=HEADERS)
op = resp.json()["data"]
print(f"TX Hash: {op.get('hash_tx', 'N/A')}")


# --- Webhook verification ---
def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
JavaScript (Node.js) — Integracao completa
JavaScript
const API_KEY = "avant_test_your_key";
const BASE    = "https://api.avantglobal.com.br";

const headers = {
  "X-Api-Key":    API_KEY,
  "Content-Type": "application/json"
};

async function fullFlow() {
  // 1. Solicitar cotacao
  const quoteResp = await fetch(`${BASE}/v1/quote`, {
    method: "POST", headers,
    body: JSON.stringify({
      valor_usdt:   500,
      wallet_trc20: "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
    })
  });
  const { data: quote } = await quoteResp.json();
  console.log(`Cotacao: ${quote.preco_avant} BRL/USDT`);

  // 2. Confirmar cotacao
  const confirmResp = await fetch(`${BASE}/v1/quote/confirm`, {
    method: "POST", headers,
    body: JSON.stringify({ op_id: quote.operation_id })
  });
  const { data: pix } = await confirmResp.json();
  console.log(`PIX gerado: ${pix.pix_qrcode.slice(0, 50)}...`);

  // 3. Simular pagamento (sandbox)
  const payResp = await fetch(`${BASE}/v1/sandbox/pix-pay`, {
    method: "POST", headers,
    body: JSON.stringify({ op_id: quote.operation_id })
  });
  const { data: result } = await payResp.json();
  console.log(`Estado final: ${result.estado}`);
}

fullFlow().catch(console.error);


// --- Webhook verification (Express.js) ---
const crypto = require("crypto");

function verifyWebhook(req, secret) {
  const sig      = req.headers["x-avant-signature"] || "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(req.body))
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(sig)
  );
}
Precisa de ajuda com a integracao? Entre em contato pelo caio@avantglobal.com.br.