API USDT para PIX

Para quem é

• Quem precisa transformar saldo em stablecoin em reais na conta de alguém, sem passar por corretora manual.
• Plataforma que paga usuários, prestadores ou parceiros no Brasil a partir de tesouraria em cripto.
• Produto que já tem off-ramp e quer um com valor travado na cotação, estados explícitos e devolução automática quando falha.

O problema

Vender cripto e fazer o PIX cair na conta certa costuma ser um processo manual: alguém envia para uma corretora, espera a venda, saca para um banco e transfere. Cada passo tem um horário, um limite e um humano. Quando falha, o dinheiro fica num lugar que ninguém consegue apontar.

Aqui a ordem tem estado. Você sabe onde ela está, o valor é travado na cotação que você aceitou, e uma falha tem destino definido: a cripto volta para o endereço de devolução que você informou.

O fluxo, ponta a ponta

1. Cote com POST /cash-outs/preview nos dois sentidos: por valor em reais ou por quantidade de cripto. Nada é criado.
2. Crie a ordem com POST /cash-outs informando a chave PIX que recebe — ou o copia e cola de uma cobrança.
3. Aceite com POST /cash-outs/{id}/accept. A resposta traz o endereço de depósito, o valor exato e o expires_at.
4. Envie exatamente a quantidade cotada, na rede cotada. Em redes de endereço compartilhado, inclua o deposit_tag.
5. O PIX sai sozinho. cashout.completed traz o pix_e2e e a URL do comprovante.

Endpoints usados

Exemplo que roda

# 1. cotação (não cria ordem)
curl -X POST https://api.luniumpay.com/cash-outs/preview \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{"asset":"USDT","network":"polygon","brl_amount":"500.00"}'

# 2. cria a ordem e aceita
ID=$(curl -sX POST https://api.luniumpay.com/cash-outs \
  -H "X-API-Key: $LUNIUM_KEY" -H "Content-Type: application/json" \
  -d '{"asset":"USDT","network":"polygon","brl_amount":"500.00",
       "pix_key":"loja@exemplo.com","pix_key_type":"email",
       "external_id":"saque-4412"}' | jq -r .cashout_id)

curl -X POST https://api.luniumpay.com/cash-outs/$ID/accept -H "X-API-Key: $LUNIUM_KEY"

const cabecalho = { "X-API-Key": process.env.LUNIUM_KEY, "Content-Type": "application/json" };

const previa = await (await fetch(`${API}/cash-outs/preview`, {
  method: "POST", headers: cabecalho,
  body: JSON.stringify({ asset: "USDT", network: "polygon", brl_amount: "500.00" }),
})).json();

const ordem = await (await fetch(`${API}/cash-outs`, {
  method: "POST", headers: cabecalho,
  body: JSON.stringify({
    asset: "USDT", network: "polygon", brl_amount: "500.00",
    pix_key: "loja@exemplo.com", pix_key_type: "email", external_id: "saque-4412",
  }),
})).json();

const aceita = await (await fetch(`${API}/cash-outs/${ordem.cashout_id}/accept`, {
  method: "POST", headers: cabecalho,
})).json();

console.log(aceita.deposit_address, aceita.deposit_tag, aceita.expires_at);

import os, requests

API = "https://api.luniumpay.com"
h = {"X-API-Key": os.environ["LUNIUM_KEY"]}

previa = requests.post(f"{API}/cash-outs/preview", headers=h, timeout=30, json={
    "asset": "USDT", "network": "polygon", "brl_amount": "500.00"}).json()

ordem = requests.post(f"{API}/cash-outs", headers=h, timeout=30, json={
    "asset": "USDT", "network": "polygon", "brl_amount": "500.00",
    "pix_key": "loja@exemplo.com", "pix_key_type": "email",
    "external_id": "saque-4412"}).json()

aceita = requests.post(f"{API}/cash-outs/{ordem['cashout_id']}/accept",
                       headers=h, timeout=60).json()
print(aceita["deposit_address"], aceita.get("deposit_tag"), aceita["expires_at"])

Sandbox: teste antes de gastar

Uma chamada, sem cadastro, sem cartão. A chave lun_test_ exercita a superfície inteira sem mover dinheiro nenhum.

curl -X POST https://api.luniumpay.com/keys/sandbox \
  -H "Content-Type: application/json" \
  -d '{"name":"meu-teste"}'

O que o sandbox não prova: liquidação real. Nenhuma cripto se move e nenhum PIX é pago — ele serve para acertar o contrato, não para medir o trilho.

Ativos e redes

Instantâneo (trilho próprio): USDT na Polygon e USDC na Polygon — liquidação em segundos, sem corretora no caminho.

Via corretora: 1.478 ativos em 241 redes na venda (1.668 pares ativo×rede) e 1.795 rotas na compra. O prazo é o número de confirmações que a rede exige, não uma escolha nossa.

Redes de endereço compartilhado (ALGO, ATOM, EOS, HBAR, KAVA, LUNA, TON, XLM, XRP): o depósito precisa levar o memo. Na venda ele vem em deposit_tag no aceite; na compra você manda payout_tag junto do endereço.

O catálogo muda sozinho conforme redes entram e saem. Leia de GET /catalog e GET /cashin/catalog em vez de manter lista no código.

Limites e retenções

A escada é por documento de quem paga, não por conta que recebe: dez pagadores são dez limites independentes. É isso que faz o produto servir a e-commerce e marketplace. Consulte o disponível de um pagador antes de cobrar em GET /cashin/limits?payer_tax=, e leia os limites da sua chave em GET /keys/me — tetos acima do tier são contratados.

Medições, não promessas

Medido em produção, janela de 90 dias, em 07/09/2026:

Fora da Polygon o relógio é o da rede: o prazo é o número de confirmações que a corretora exige, e está em eta no catálogo. Não prometemos “instantâneo” fora do trilho próprio.

Idempotência

Mande external_id em toda operação que move dinheiro. Repetir a mesma chamada devolve a mesma operação, nunca uma segunda; os mesmos parâmetros com id diferente criam duas, e o mesmo id com parâmetros diferentes responde 409 external_id_divergente em vez de adivinhar.

Timeout não é recusa. Se a chamada não respondeu, consulte pelo external_id antes de repetir — a operação pode existir.

Webhooks e reconciliação

Cada transição dispara um evento assinado em HMAC SHA-256 com timestamp (header X-Lunium-Signature, formato t=…,v1=…) — o timestamp é o que impede replay de uma entrega capturada. Confira a assinatura antes de confiar no corpo.

Webhook é o sinal principal; polling é opcional. Quando precisar pesquisar, o status traz a timeline carimbada pelo servidor — desenhe a etapa a partir dela, porque o cronômetro do seu polling mede a sua rede, não a operação.

Não respondeu 2xx? A entrega é retentada com backoff. Você reenvia à mão em POST /webhooks/deliveries/{event_id}/retry e testa a sua URL em POST /webhooks/test.

Quando dá errado

Depósito com valor diferente do cotado: a ordem não casa e vai para revisão em vez de pagar um valor que ninguém reconhece. Envie o amount exato da resposta.

Rede errada ou depois do expires_at: o depósito chega órfão e vira revisão manual. Sempre deposite antes do vencimento, na rede cotada.

O banco recusa a chave: a cripto volta para o refund_address que você informou, com o estado REFUNDED e o hash da devolução — não fica saldo pendurado com a gente.

Rede com memo sem o memo: o valor cai na corretora sem dono. Por isso o aceite devolve deposit_tag nessas redes e a documentação insiste: se veio preenchido, ele é obrigatório.

Segurança

• webhook assinado — Todo webhook vai assinado em HMAC SHA-256 com timestamp (header X-Lunium-Signature, formato t=…,v1=…), o que impede replay de uma entrega capturada.
• idempotencia — external_id em cash-in, cash-out e payout: repetir a mesma chamada devolve a MESMA operação, nunca uma segunda. Parâmetros diferentes no mesmo external_id respondem 409.
• egress validado — A URL de webhook é resolvida e validada antes de cada entrega: endereço interno, metadata de nuvem e redirect para rede privada são recusados, e a conexão é fixada no IP validado.
• retencao fail closed — A retenção é verificada na liquidação e repetida na reivindicação SQL: nenhum caminho (worker, consulta de status, fila) consegue liquidar antes da hora.
• payout duravel — O saque grava a operação e debita o saldo na MESMA transação, antes de qualquer chamada ao provedor: não existe débito sem ordem para reconciliar.
• verificacao aberta — GET /v1/verificar/{e2e} confere um PIX liquidado sem chave nenhuma — a contraparte não precisa confiar na nossa palavra.

A verificação aberta é a que mais importa numa negociação: a sua contraparte confere o PIX sozinha, sem chave e sem depender da nossa palavra.

Tempo até a primeira integração

Três chamadas e um depósito. Quem só quer ver o preço para na primeira, que não cria nada e não consome limite nenhum.

O trilho próprio (Polygon) é o previsível: mediana de 81 s e p90 de 580 s do aceite ao PIX pago. Nas outras redes o relógio é o das confirmações — está em eta no catálogo.

Perguntas que os integradores fazem