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.
X-Api-Key: avant_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxChaves de producao tem prefixo avant_. Chaves sandbox tem prefixo avant_test_. Todas as requisicoes devem usar HTTPS.
{
"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.
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.
| Passo | Acao | Observacao |
|---|---|---|
| 1 | POST /v1/quote | Retorna quote_ready imediatamente com preco simulado |
| 2 | POST /v1/quote/confirm | Retorna QR code PIX fake — nao tente pagar |
| 3 | POST /v1/sandbox/pix-pay | Simula pagamento — dispara 3 webhooks (pix_confirmed, usdt_sent, complete) |
| 4 | GET /v1/operation/{id} | Verifique que o estado final e complete com tx_hash fake |
Endpoints
Todos os endpoints retornam Content-Type: application/json. Respostas de sucesso encapsulam dados em data; erros em error.
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_avant = preco_tela x (1 + spread_cliente)
valor_brl = preco_avant x valor_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.
| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
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. |
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"
}'{
"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
}
}{
"data": {
"operation_id": "OTC20260401120000AABB1234",
"estado": "quote_requested",
"valor_usdt": 500,
"message": "Cotacao em processamento..."
}
}Trava a cotacao e gera um QR code PIX dinamico para o cliente pagar. Operacao move para awaiting_pix. PIX expira em 15 minutos.
| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
op_id |
string |
required | Operation ID retornado por POST /v1/quote. Deve estar em quote_ready. |
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"}'{
"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
}
}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.
| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
op_id |
string |
required | Operation ID a cancelar. Deve estar em quote_requested, quote_ready ou quote_expired. |
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"}'{
"data": {
"operation_id": "OTC20260401120000AABB1234",
"estado": "cancelled",
"message": "Operacao cancelada com sucesso."
}
}Retorna o estado atual de uma cotacao. Poll a cada 5-10 segundos enquanto estado = quote_requested. Quando quote_ready, prossiga para confirmar.
curl https://api.avantglobal.com.br/v1/quote/OTC20260401120000AABB1234 \
-H "X-Api-Key: avant_your_key"{
"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"
}
}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.
curl https://api.avantglobal.com.br/v1/operation/OTC20260401120000AABB1234 \
-H "X-Api-Key: avant_your_key"{
"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"
}
}Simula pagamento PIX no sandbox. Transiciona a operacao pelo fluxo completo — pix_confirmed → usdt_sent → complete — e dispara todos os 3 webhooks. Disponivel apenas com chaves avant_test_.
| Campo | Tipo | Obrigatorio | Descricao |
|---|---|---|---|
op_id |
string |
required | Operation ID em estado awaiting_pix. |
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"}'{
"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.
X-Avant-Retry: N indica a tentativa. Implemente idempotencia usando operation_id + event como chave de deduplicacao.{
"event": "pix_confirmed",
"operation_id": "OTC20260401120000AABB1234",
"timestamp": 1775000000,
"data": {
// campos especificos do evento
}
}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).X-Avant-Signature: sha256=a1b2c3d4e5f6...
X-Avant-Event: pix_confirmed
X-Avant-Retry: 0$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;
}data inclui valor_brl, valor_usdt.data inclui tx_hash, tronscan_url, valor_usdt, wallet_trc20.data inclui operation_id, valor_usdt, tx_hash.data inclui preco_avant, valor_brl, expires_in.data inclui pix_qrcode, valor_brl, pix_expires_at.Fluxo de Estados
Toda operacao progride por um conjunto definido de estados. Estados terminais sao complete, cancelled, quote_expired e pix_expired.
| Estado | Descricao | Proxima acao |
|---|---|---|
quote_requested | Cotacao recebida, precificacao pendente | Poll GET /v1/quote/{id} |
quote_ready | Preco travado, valido por 10 min | Chamar POST /v1/quote/confirm |
awaiting_pix | PIX gerado, aguardando pagamento | Cliente paga o QR code PIX |
pix_confirmed | Pagamento recebido, processando USDT | Aguardar webhook usdt_sent |
usdt_sent | USDT enviado on-chain | Verificar TX no TronScan |
complete | Entrega confirmada | — |
quote_expired | TTL da cotacao expirado sem confirmacao | Criar nova cotacao |
pix_expired | PIX nao pago em 15 min | Criar nova cotacao |
cancelled | Cancelado pelo cliente | — |
failed | Falha no processamento | Contatar Avant |
Codigos de Erro
Todos os erros retornam um JSON com error.code (machine-readable) e error.message (human-readable).
{
"error": {
"code": "invalid_wallet",
"message": "Endereco TRC-20 invalido. Deve comecar com T e ter 34 caracteres."
}
}api_key_missingX-Api-Key nao fornecidoapi_key_invalidip_not_alloweddaily_limit_exceededoperation_not_foundinvalid_statecannot_cancelquote_expiredinvalid_walletbelow_minimumrate_limit_exceededsandbox_onlypix_creation_failed| Parametro | Valor | Observacao |
|---|---|---|
| Operacao minima | 100 USDT | Por cotacao |
| Quote TTL | 10 min | Apos expirar, solicite nova cotacao |
| PIX TTL | 15 min | Validade do QR code apos confirm |
| Rate limit | 60 req/min | Por API key · 429 quando excedido |
| Limite diario | configuravel | Definido por chave · 0 = ilimitado |
| IP whitelist | opcional | Restrinja a IPs especificos por chave |
| Webhook timeout | 10 s | Seu endpoint deve responder em ate 10 s |
SDKs & Exemplos
Exemplos completos de integracao em diferentes linguagens. Todos os exemplos usam chave sandbox para seguranca.
# 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"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)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)
);
}