BRL ↔ USDT por API

Para quem é

• Fintech ou empresa que precisa de BRL → USDT e USDT → BRL rodando em produção, não em piloto.
• Tesouraria que converte todo dia e quer o preço na tela antes de decidir.
• Quem hoje usa corretora manual e quer o mesmo resultado com contrato, estado e comprovante.

O problema

Converter BRL e USDT com previsibilidade tem dois inimigos: preço que muda entre a decisão e a execução, e processo que depende de alguém logar em algum lugar. O primeiro vira prejuízo silencioso; o segundo vira dependência de horário comercial.

A resposta é separar cotar de executar. A prévia responde a mesma conta da ordem real — mesmo trilho, mesmos mínimos, mesmas recusas — mas não persiste nada. Você mostra o número, o usuário decide, e só então a ordem nasce com o valor travado.

O fluxo, ponta a ponta

1. Cotar: POST /cashin/preview (reais → cripto) ou POST /cash-outs/preview (cripto → reais). Nada é criado.
2. A prévia devolve o trilho (path), a quantidade e, na compra, o mínimo em reais daquela rota.
3. Comprar: POST /cashin/charge gera o PIX; pago, a cripto sai para a carteira indicada.
4. Vender: POST /cash-outs + /accept devolve o endereço; depositado, o PIX sai.
5. Toda operação tem external_id, webhook assinado e comprovante — a conciliação é automática.

Endpoints usados

Exemplo que roda

# preço antes de qualquer ordem — os dois sentidos
curl -X POST https://api.luniumpay.com/cashin/preview -H "X-API-Key: $LUNIUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":100000,"asset":"usdt","chain":"polygon"}'

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","amount":"1000"}'

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

// BRL -> USDT: quanto de cripto sai por R$ X (com o mínimo da rota)
export async function comprar(cents) {
  const p = await (await fetch(`${API}/cashin/preview`, { method: "POST", headers: h,
    body: JSON.stringify({ amount_cents: cents, asset: "usdt", chain: "polygon" }) })).json();
  return { usdt: p.usdt_amount ?? p.amount, minimoBrlCents: p.min_brl_cents };
}

// USDT -> BRL: quanto de PIX sai por N USDT, sem criar ordem
export async function vender(qtd) {
  const p = await (await fetch(`${API}/cash-outs/preview`, { method: "POST", headers: h,
    body: JSON.stringify({ asset: "USDT", network: "polygon", amount: String(qtd) }) })).json();
  return { brl: p.brl_amount, trilho: p.path };
}

import os, requests

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

def comprar(cents):
    p = requests.post(f"{API}/cashin/preview", headers=H, timeout=30, json={
        "amount_cents": cents, "asset": "usdt", "chain": "polygon"}).json()
    return p.get("usdt_amount") or p.get("amount"), p.get("min_brl_cents")

def vender(qtd):
    p = requests.post(f"{API}/cash-outs/preview", headers=H, timeout=30, json={
        "asset": "USDT", "network": "polygon", "amount": str(qtd)}).json()
    return p["brl_amount"], p["path"]

Sandbox: teste antes de gastar

Uma chamada, sem aprovação prévia, sem cartão; só o seu e-mail é obrigatório (é para ele que mandamos o manual, o fluxograma e o passo a passo da integraçã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 '{"email":"voce@empresa.com","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

O catálogo de entrada de cripto é GET /catalog; o de entrega após Pix é GET /cashin/catalog. Consulte o ativo e a rede do fluxo escolhido antes de cotar. Disponibilidade e mínimos podem mudar.

Use deposit_tag no depósito quando o aceite informar um memo. Na entrega, envie payout_tag quando exigido pela rota. O manual da API descreve cada campo.

Limites e retenções

Consulte GET /keys/me para os limites e as taxas da conta, GET /cashin/limits?payer_tax=... para o pagador e as prévias para o mínimo da rota. Não use um teto fixo compartilhado entre cash-in, cash-out e payout.

Uma cobrança paga pode aguardar retenção antes da liquidação. Use os estados, a linha do tempo e os eventos assinados para distinguir recebimento, saldo disponível e entrega final. A validade da operação vem em expires_at.

Medições, não promessas

O prazo depende do fluxo, da rota disponível, das confirmações da rede e de eventuais retenções. Acompanhe a operação até o estado final e consulte o status do serviço. O tempo de uma simulação não mede uma liquidação real.

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

Abaixo do mínimo: a recusa cita o número — na compra, min_brl_cents vem na própria prévia, então a tela mostra o mínimo antes de o usuário digitar.

Acima do máximo: valor_acima_do_maximo com o teto vigente. Leia de GET /keys/me em vez de fixar o número no código: tetos mudam por contrato.

Cotação expirada: a ordem tem expires_at. Depois dele, o depósito chega órfão — cote de novo em vez de depositar atrasado.

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

A primeira integração útil é só a prévia: uma chamada, sem efeito colateral, que já dá para colocar numa tela. A execução vem depois, com o mesmo contrato que você já testou.

Perguntas que os integradores fazem