Conversão USDT

Converta saldo BRL em USDT (rede TRC20/Tron) enviado direto para a wallet informada.

Recurso sob liberaçãoA conversão USDT é habilitada por conta pela nossa equipe. Sem a liberação, todos os endpoints retornam 403. Solicite ao suporte.

Endpoints

GET/v1/usdt/quote

Prévia da conversão na cotação atual (amount em BRL OU usdtAmount)

POST/v1/usdt/conversions

Cria a conversão: debita o saldo BRL e envia USDT à wallet (assíncrono)

GET/v1/usdt/conversions

Lista as conversões da conta (paginação page/limit)

GET/v1/usdt/conversions/:id

Consulta uma conversão por conversionId ou externalReference

Segurança

A criação da conversão movimenta saldo e segue o mesmo regime do saque: requer IP whitelistado (Configurações > Regras de Segurança) ou o header x-withdrawal-secret, além do scope withdrawals:write na API Key. As consultas e a prévia usam withdrawals:read e não exigem IP.

Parâmetros — POST /v1/usdt/conversions

Body (JSON)

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	number	Não	Valor em BRL a converter (debitado do saldo). Use este OU usdtAmount.`Ex: 2000.00`
`usdtAmount`	number	Não	Quantidade EXATA de USDT que deve chegar na wallet. O débito na criação é o valor cotado (amountBrl). Se a cotação subir até a execução, a diferença é debitada do saldo na conclusão (extraChargedBrl, presente no webhook); se cair, vale o valor cotado.`Ex: 323.43`
`walletAddress`	string	Sim	Endereço da wallet USDT na rede TRC20 (Tron) — 34 caracteres, começa com "T".`Ex: "TX7k2mNpQr9sT4uVwXyZ1aB3cD5eF6gH8i"`
`externalReference`	string	Não	Sua referência (máx. 100 caracteres). Também é a chave de idempotência: repetir o mesmo valor retorna a conversão já criada, sem novo débito.`Ex: "CONV-2026-0001"`

amount OU usdtAmountInforme exatamente um dos dois — pelo menos um é obrigatório.

Ciclo de Vida (assíncrono)

A resposta do POST vem com status: "PENDING". A execução passa pela mesa de câmbio do provedor (janela comercial, aprox. 09h10–16h30 BRT) e pode levar horas — diferente de um PIX. Estados:

Status	Significado
`PENDING`	Saldo debitado; envio dos fundos ao provedor em andamento
`FUNDING`	Fundos enviados; aguardando confirmação do provedor
`FUNDED`	Fundos confirmados; aguardando execução da compra
`CONVERTING`	Compra enviada à mesa; aguardando liquidação
`COMPLETED`	USDT enviado à wallet (`usdtQuantityFinal` preenchido; se a cotação subiu, `extraChargedBrl` traz o débito adicional)
`FAILED`	Falha definitiva — o valor debitado volta ao saldo (`refunded: true`)

Acompanhe pelos webhooks usdt.conversion.completed e usdt.conversion.failed (configure em Webhooks) ou consultando GET /v1/usdt/conversions/:id.

Limites

Quantidade mínima por conversão: há um mínimo operacional da mesa de câmbio (na ordem de 300 USDT). O mínimo em BRL varia com a cotação — consulte GET /v1/usdt/quote: valores abaixo retornam 400 com o mínimo atual.
Valor máximo por conversão: configurado pela plataforma; acima dele a API retorna 400.
Rede: apenas TRC20 (Tron). Endereço de outra rede é rejeitado na validação.

Próximo passoConfigure Webhooks para ser notificado quando a conversão concluir ou falhar.

Prévia (cURL)
curl -X GET "https://api.ActivePayments.com.br/api/v1/usdt/quote?amount=2000" \
  -H "Authorization: ApiKey ActivePayments_pk_xxx:ActivePayments_sk_xxx"

Response — /v1/usdt/quote
{
  "success": true,
  "data": {
    "amountBrl": 2000.00,
    "usdtEstimated": 361.50,
    "targetUsdt": null,
    "effectiveUnitPrice": 5.5325,
    "network": "TRC20",
    "quoteExpiresAt": "2026-08-25T14:35:00.000Z",
    "disclaimer": "Quantidade estimada. A quantidade final pode variar levemente conforme a cotação no momento da execução."
  }
}

Criar conversão (cURL)
curl -X POST "https://api.ActivePayments.com.br/api/v1/usdt/conversions" \
  -H "Authorization: ApiKey ActivePayments_pk_xxx:ActivePayments_sk_xxx" \
  -H "x-withdrawal-secret: seu-secret-de-saque" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2000.00,
    "walletAddress": "TX7k2mNpQr9sT4uVwXyZ1aB3cD5eF6gH8i",
    "externalReference": "CONV-2026-0001"
  }'

Response 201 — conversão criada
{
  "success": true,
  "data": {
    "conversionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalReference": "CONV-2026-0001",
    "amountBrl": 2000.00,
    "usdtQuantityEstimated": 361.50,
    "usdtQuantityFinal": null,
    "effectiveUnitPrice": 5.5325,
    "targetUsdt": null,
    "extraChargedBrl": null,
    "excessRefundedBrl": null,
    "walletAddress": "TX7k2mNpQr9sT4uVwXyZ1aB3cD5eF6gH8i",
    "network": "TRC20",
    "status": "PENDING",
    "refunded": false,
    "createdAt": "2026-08-25T14:30:00.000Z",
    "completedAt": null
  }
}

Webhook usdt.conversion.completed
{
  "event": "usdt.conversion.completed",
  "conversionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "externalReference": "CONV-2026-0001",
  "amountBrl": 2000.00,
  "usdtQuantityFinal": 361.50,
  "targetUsdt": null,
  "effectiveUnitPrice": 5.5325,
  "extraChargedBrl": null,
  "excessRefundedBrl": null,
  "walletAddress": "TX7k2mNpQr9sT4uVwXyZ1aB3cD5eF6gH8i",
  "network": "TRC20",
  "status": "COMPLETED",
  "refunded": false,
  "createdAt": "2026-08-25T14:30:00.000Z",
  "completedAt": "2026-08-25T16:10:00.000Z"
}