Pular para o conteúdo principal

API — Ordens

POST /orders​

Cria ordem. Envie amount (valor na unidade do token) ou quoteCurrency + quoteAmount — não os dois.

Na Solana, token pode ser USDT ou USDC (este último exige USDC_MINT_SOLANA no servidor). Em Polygon e Ethereum, use apenas USDT.

USDC na Solana — destaque para integradores

Além de USDT, você pode cobrar em USDC na mesma rede: envie "token": "USDC" com "amount" no formato decimal (6 casas na prática, como USDT). O cliente paga com USDC na Phantom; o payUrl / QR refletem o mint configurado no servidor.

  • Requisito de ambiente: variável USDC_MINT_SOLANA (mint oficial do USDC na Solana que o backend deve usar).
  • Exemplos prontos: JSON e cURL abaixo; cotação BRL/EUR com USDC aqui.

Se USDC não estiver habilitado no deploy, a API retorna erro de validação — nesse caso use apenas USDT ou configure o mint.

Body — valor em USDT (Solana)​

{
  "network": "SOLANA",
  "token": "USDT",
  "amount": "100.00",
  "webhookUrl": "https://opcional-para-esta-ordem.com/webhook",
  "telegramChatId": "opcional"
}

Body — valor em USDC (Solana)​

Exemplo USDC (mesmo padrão que USDT)

Troque apenas token e o valor em amount. Campos opcionais (webhookUrl, telegramChatId, merchantWalletId, etc.) são os mesmos de uma ordem USDT.

{
  "network": "SOLANA",
  "token": "USDC",
  "amount": "100.00",
  "webhookUrl": "https://opcional-para-esta-ordem.com/webhook",
  "telegramChatId": "opcional"
}

Body — valor cotado em BRL​

{
  "network": "SOLANA",
  "token": "USDT",
  "quoteCurrency": "BRL",
  "quoteAmount": "550.00"
}

Com token: "USDC", a conversão BRL/EUR usa o mesmo feed que para USDT (stable ~USD); o rótulo fxRateLabel mostra 1 USDC = ….

Body — valor cotado em BRL com USDC​

USDC + cotação BRL (destaque)

Mesmo fluxo de cotação que com USDT: o servidor converte o valor em BRL para a quantidade de USDC a pagar.

{
  "network": "SOLANA",
  "token": "USDC",
  "quoteCurrency": "BRL",
  "quoteAmount": "550.00"
}

cURL (USDT)​

curl -s -X POST "{{BASE_URL}}/orders" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{"network":"SOLANA","token":"USDT","amount":"100.00"}'

cURL (USDC)​

Copiar e colar — ordem em USDC

Payload mínimo; ajuste amount e o Bearer.

curl -s -X POST "{{BASE_URL}}/orders" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{"network":"SOLANA","token":"USDC","amount":"50.00"}'

cURL (BRL em USDC)​

curl -s -X POST "{{BASE_URL}}/orders" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{"network":"SOLANA","token":"USDC","quoteCurrency":"BRL","quoteAmount":"550.00"}'

cURL (BRL)​

curl -s -X POST "{{BASE_URL}}/orders" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{"network":"SOLANA","token":"USDT","quoteCurrency":"BRL","quoteAmount":"550.00"}'

Resposta inclui, entre outros: reference, amount, token, tokenMintOrContract, quoteCurrency, quoteAmount, quotedAt, fxRateLabel, fxSource, payUrl, qrData, expiresAt, status.

GET /users/me/orders​

Paginação por página: page, per_page (máx. 50).
Para alto volume: cursor + per_page usando nextCursor da resposta anterior.

cURL (página)​

curl -s -X GET "{{BASE_URL}}/users/me/orders?page=1&per_page=10" \
  -H "Authorization: Bearer {{TOKEN}}"

GET /orders/{reference}​

curl -s -X GET "{{BASE_URL}}/orders/REFERENCE_DA_ORDEM" \
  -H "Authorization: Bearer {{TOKEN}}"

POST /orders/{reference}/submit-tx​

Registra o txId on-chain (integração server-side). O fluxo da página de pagamento costuma usar POST /pay/{reference}/submit-tx.

Body​

{
  "txId": "assinatura_ou_hash_da_transacao"
}

cURL​

curl -s -X POST "{{BASE_URL}}/orders/REFERENCE/submit-tx" \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{"txId":"TX_ID_NA_BLOCKCHAIN"}'

GET /orders/{reference}/webhook-deliveries​

Histórico de tentativas de webhook (payload e resposta truncada).

curl -s -X GET "{{BASE_URL}}/orders/REFERENCE/webhook-deliveries" \
  -H "Authorization: Bearer {{TOKEN}}"

GET /orders/{reference}/telegram-deliveries​

Histórico de envios ao Telegram.

curl -s -X GET "{{BASE_URL}}/orders/REFERENCE/telegram-deliveries" \
  -H "Authorization: Bearer {{TOKEN}}"

GET /orders/{reference}/audit​

Linha do tempo de eventos da ordem.

curl -s -X GET "{{BASE_URL}}/orders/REFERENCE/audit" \
  -H "Authorization: Bearer {{TOKEN}}"