Documentação — Lunium API

A Lunium API é a infraestrutura de cripto → Pix: seu usuário vende a cripto que tiver e recebe em Pix, por uma única integração. Você conecta o front-end — a Lunium escolhe a rota, liquida e paga. Sem montar exchange, sem custodiar fiat, sem KYC no seu fluxo.

Como funciona

Toda operação é um cash-out e segue sempre o mesmo ciclo, independente da moeda ou da rota:

1. Cotação — POST /cash-outs trava preço e prazo (QUOTE_CREATED).
2. Aceite — POST /cash-outs/{id}/accept devolve o endereço de depósito (AWAITING_DEPOSIT).
3. Depósito — seu usuário envia a cripto para o endereço.
4. Polling — GET /cash-outs/{id} até um estado terminal (COMPLETED).

A Lunium decide sozinha qual rota usar (veja Rotas de liquidação); para o seu código, os quatro passos acima são sempre iguais.

Início rápido

Descubra o que é vendável e crie uma cotação:

# 1. Catálogo vivo (o que dá pra vender agora)
curl https://api.luniumpay.com/catalog -H "Authorization: Bearer SEU_TOKEN"

# 2. Cria a cotação
curl -X POST https://api.luniumpay.com/cash-outs \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asset":"USDT","network":"polygon","amount":"100.00","pixKey":"lojista@luniumpay.com","pixKeyType":"email"}'
# → { "id":"co_...", "state":"QUOTE_CREATED", "brlAmount":"540.00", "expiresAt":"..." }

# 3. Aceita e recebe o endereço de depósito
curl -X POST https://api.luniumpay.com/cash-outs/co_.../accept -H "Authorization: Bearer SEU_TOKEN"
# → { "state":"AWAITING_DEPOSIT", "depositAddress":"0x...", ... }

# 4. Após o depósito, faça polling até um estado terminal
curl https://api.luniumpay.com/cash-outs/co_... -H "Authorization: Bearer SEU_TOKEN"
# → { "state":"COMPLETED", ... }

Rotas de liquidação

A rota é escolhida automaticamente a partir da moeda × rede — transparente para o cliente, muda só a latência:

Rota	Quando	Latência do Pix
FAST	USDT/USDC em Polygon e Solana	segundos
DEX	Qualquer token em Polygon/Solana (swap on-chain → USDT)	segundos
CONVERT	Demais moedas/redes (depósito → venda spot → USDT)	minutos

O campo path na resposta informa qual rota foi escolhida.

Autenticação

Todas as chamadas (exceto o catálogo público de status) exigem o header:

Authorization: Bearer SEU_TOKEN

O token é emitido pela Lunium por cliente. Chamadas sem token válido respondem 401. Chame sempre a partir do seu back-end — nunca exponha o token no front-end.

Redes, moedas e o catálogo

Não mantenha catálogo à mão: consulte-o vivo.

• GET /catalog — rotas FAST (fixas) + CONVERT (catálogo da exchange, com min/max e precisão por moeda).
• GET /catalog/dex?chain=&q= — busca na whitelist do DEX por address/mint (símbolos se repetem — há três "DOG" na Solana).

Para tokens do DEX, envie tokenAddress (o mint/endereço canônico) no POST /cash-outs — o símbolo sozinho é ambíguo. É case-sensitive; nunca normalize.

Ciclo de vida

O campo state avança por esta máquina. Faça polling em GET /cash-outs/{id} e pare num estado terminal (✔).

Estado	Significado
QUOTE_CREATED	Cotação criada, aguardando aceite.
AWAITING_DEPOSIT	Aceita — aguardando o depósito no endereço.
DEPOSIT_DETECTED	Depósito visto on-chain, aguardando confirmações.
DEPOSIT_CONFIRMED	Depósito confirmado.
SELLING / SOLD	(CONVERT) venda spot em andamento / concluída.
FORWARDING	Encaminhando para liquidação em Pix.
PAYING_OUT	Pix em processamento.
COMPLETED ✔	Pix pago.
EXPIRED ✔	Cotação expirou sem depósito.
REFUNDED ✔	Cripto devolvida ao usuário.
FAILED ✔	Falha terminal.
MANUAL_REVIEW / REFUNDING_CRYPTO	Sob intervenção do operador (transitórios).

Erros

Respostas de erro usam códigos HTTP padrão com corpo { "message": "...", "statusCode": N }:

Código	Causa
400	Requisição inválida (ex.: amount não-decimal, rota inexistente).
401	Token ausente ou inválido.
403	Chave Pix fora do allowlist (período canário).
404	Cash-out inexistente.
429	Rate limit — veja Limites.
503	Serviço temporariamente indisponível (circuit breaker / limite diário).

Limites

• Operação até US$ 50 mil.
• Rate limits por token: cotação 5/min, aceite 10/min, consulta 60/min, catálogo 30/min.
• Valores mínimos por moeda vêm do GET /catalog (campo min).
• Dinheiro trafega como string decimal ("100.00"), nunca float — para preservar precisão.

Chaves Pix

pixKeyType é obrigatório e deve casar com a chave (CPF e telefone sem +55 têm os mesmos 11 dígitos — a ambiguidade já causou devolução on-chain): um de cpf, cnpj, phone, email, random.

Suporte

Dúvidas de integração: contato@luniumpay.com · https://luniumpay.com