# Lunium

> Infraestrutura de liquidação entre criptomoedas e PIX no Brasil. Um cliente entrega cripto e uma chave PIX recebe reais; ou paga um PIX e recebe cripto na carteira. Mais de 1.400 ativos em dezenas de redes. Toda operação sai com comprovante e identificador oficial do Banco Central (E2E).

A Lunium é a camada de liquidação — quem integra não precisa montar exchange, manter saldo em rede nenhuma nem custodiar reais.

English: https://api.luniumpay.com/llms.txt

**Manual de integração completo (Markdown, para agentes):** https://docs.luniumpay.com/manual.md — limites do cash-in e retenção de 24h, saldo em reais, cash-out, payouts, webhooks, erros, tabela de limites, checklist de go-live. O mesmo em HTML: https://docs.luniumpay.com/manual · PDF: https://docs.luniumpay.com/manual.pdf

**Comece por aqui:** https://api.luniumpay.com/quickstart — do zero a uma ordem concluída com comprovante do Banco Central, executável em sandbox, sem mover dinheiro.

Passo a passo para humanos: https://docs.luniumpay.com/comecar

Base da API: `https://api.luniumpay.com` · Autenticação: header `X-API-Key` · Documentação: https://docs.luniumpay.com · OpenAPI: https://api.luniumpay.com/openapi.json

## Verificação de pagamento (aberta, sem chave)

Qualquer agente pode confirmar que um PIX aconteceu, mesmo sem ser cliente da Lunium. É a forma de checar um pagamento sem ter que confiar em quem diz ter pago.

```
GET https://api.luniumpay.com/v1/verificar/{e2e}
```

Devolve `verificado`, `pago`, `valor_brl`, `pago_em`, iniciais do recebedor, instituição e o link do comprovante. Não expõe chave PIX, nome completo nem documento — prova o pagamento sem expor as partes.

Quando não encontra, a resposta diz explicitamente que o pagamento pode ter sido feito por outra instituição — ausência aqui não é prova de que o PIX não existiu.

## Vender cripto e receber PIX (cash-out)

Três passos, nesta ordem:

1. `POST /cash-outs` — cotação. Campos: `asset`, `network`, `amount` (cripto, string decimal) **ou** `brl_amount` (reais que a chave vai receber, `"250.00"` — exatamente um dos dois; a resposta traz a cripto em `amount`), `pix_key`, `external_id`, e `pix_key_type` só se a chave forem 11 dígitos puros. Devolve `brl_amount` e `expires_at`.
   Formatos aceitos — a API normaliza a chave para o formato exato que o liquidante exige no memo, e recusa antes de existir depósito (`400 pix_key_invalida`): CPF = 11 dígitos; CNPJ = 14 dígitos; telefone = internacional `+55` + DDD + número (`+5548996005588`); e-mail; chave aleatória = UUID (`6602ede6-b1a9-4e63-9178-c6883fd0095e`).
2. `POST /cash-outs/{id}/accept` — trava a cotação e devolve `deposit_address`. O cliente envia a cripto para lá.
   Antes de aceitar, mostre quem vai receber: `GET /pix/keys/lookup?key=` devolve nome, CPF/CNPJ mascarado e instituição do titular (DICT). 5 consultas/min por conta; chave inexistente → 404 `chave_nao_encontrada`.
3. `GET /cash-outs/{id}` — acompanha. Quando paga, traz o comprovante (abaixo).

Prefere partir do valor em reais? Mande `brl_amount` no lugar de `amount` no `POST /cash-outs` — a cotação volta com a cripto exata a depositar em `amount`, travada pela mesma janela.

**Carteira de retorno — mande em toda cotação.** `refund_address` é a carteira do seu cliente na mesma rede da venda. É para onde a cripto volta se algo impedir o PIX: o provedor recusou a chave, o PIX foi revertido ou o envio falhou antes de sair. Sem ela a devolução vai para a origem on-chain do depósito — errado quando o depósito veio de uma exchange (a origem é a hot wallet da exchange).

## Quando uma venda falha — exatamente o que acontece

- QR code / copia-e-cola no campo `pix_key` é recusado na cotação (`pix_key_invalida`). Nada se move: ainda não existe endereço de depósito. A API paga **chaves** PIX (CPF, CNPJ, telefone, e-mail, aleatória).
- O provedor recusa a chave depois do depósito (chave inválida ou inexistente): a ordem vai a `MANUAL_REVIEW` (`cashout.under_review`), a cripto volta para a custódia da Lunium e é enviada automaticamente para `refund_address`; a ordem termina `REFUNDED` (`cashout.refunded`) com `refund_tx_hash`. Devolve-se o líquido que o provedor devolveu.
- O envio falha antes de sair (provedor fora do ar, chave rejeitada na submissão): retentado a cada 5 min por até 45 min; se ainda não liquidar, o valor **cheio** (taxa inclusive) volta para `refund_address`; `REFUNDED` + `refund_tx_hash`.
- PIX revertido depois de pago (raro — conta de destino bloqueada): mesmo caminho, `REFUNDED` com `refund_tx_hash`.
- Depósito diferente do cotado: paga-se o valor realmente recebido. Token diferente fica em `MANUAL_REVIEW`.
- Depósito depois de `expires_at`: a ordem é revivida quando o depósito aparece (até 7 dias); senão `MANUAL_REVIEW`.
- Devoluções automáticas até 5.000 USDT por ordem; acima disso uma pessoa da operação executa e você recebe `REFUNDED` + hash do mesmo jeito. A devolução sai sempre na rede e no token do depósito, do endereço de custódia da Lunium; o gas é nosso.
- `refund_address`, `refund_tx_hash` e `deposit_from` vêm em `GET /cash-outs/{id}` e em todo webhook.

## Pagar uma cobrança (QR code / copia e cola)

Mande `br_code` (o copia e cola inteiro) no lugar de `pix_key`, **somente com USDT ou USDC na Polygon** — qualquer outro ativo ou rede é recusado (`400 br_code_nao_suportado`). O QR precisa ter valor fixo: ele vira o `brl_amount` da ordem, e a chave do recebedor é lida do próprio QR (`pix_key` mascarada e `merchant_name` na resposta). Não envie `amount`, `brl_amount` nem `pix_key` junto com `br_code` (`400 campos_conflitantes`). O liquidante valida o QR na hora de pagar; se recusar, a cripto volta para `refund_address` automaticamente (`REFUNDED` + `refund_tx_hash`). O sandbox lê QR estático (chave + valor); produção resolve também os dinâmicos.

## Saldo em reais (custódia): depositar por PIX, sacar por PIX
Chaves com custódia habilitada (`custodia_ativa: true` em `GET /saldo`) guardam reais para os seus clientes finais — a aba "depositar e sacar" de um app de carteira.
- **Depósito**: `POST /cashin/charge` com `destino: "saldo"` (e `customer_ref` = id do seu cliente). O PIX pago é creditado **integral** (`deposito_fee_bps` = 0 hoje) nessa sub-conta, **bloqueado até `disponivel_em`** (D+1 por padrão — `carencia_horas`). O webhook `cashin.settled` traz `asset: "brl"`, `saldo_credito_cents`, `saldo_disponivel_em`. Nenhuma cripto sai.
- **Saldo**: `GET /saldo?customer_ref=…` → `disponivel_cents`, `bloqueado_cents`, `proximas_liberacoes`, e as duas taxas que a sua tela precisa mostrar. `GET /saldo/extrato` é o extrato (livro-razão append-only; saldo = soma).
- **Saque**: `POST /payouts` com o mesmo `customer_ref`. O valor **mais a taxa da casa** (`saque_fee_bps`, hoje 1,8% — depósito é grátis, o custo é recuperado aqui) **mais a taxa do provedor** (~R$ 1,00 por PIX) é debitado antes de o PIX sair; `fee_cents` no payout é o total; recusa estorna o débito. 402 `saldo_insuficiente` quando disponível < valor + taxas. A chave PIX tem que pertencer ao `tax_number` enviado (regra do banco) — é isso que impede um cliente sacar o saldo de outro. O PIX cai em até 24h.
- **Saque em cripto**: `POST /saldo/sacar-cripto` {amount_cents, chain, asset, payout_address, tax_number, customer_ref} — os reais saem do saldo (valor + `saque_cripto_fee_bps`) e a cripto vai para a carteira do próprio cliente pelo mesmo trilho da compra por PIX; a resposta é uma cobrança já `paid` — acompanhe `settlement_status` em `GET /cashin/{id}/status` até `sent`. Qualquer moeda/rede de `GET /cashin/catalog`, exceto Liquid/DePix.
- **Duas carências, uma regra**: o saldo aparece na hora, mas cada depósito só pode ser usado depois de `carencia_horas` (D+1), e o **primeiro depósito de uma sub-conta trava qualquer saque por 24h** (`carencia_ate` em `GET /saldo`; `423 carencia_primeiro_deposito` com `libera_em` nas duas rotas de saque). As cobranças trazem `fonte` (`pix`|`saldo`) e `destino` (`cripto`|`saldo`) para um saque nunca ser confundido com uma compra.
- Nada é adiantado e nenhuma taxa é absorvida: o que o provedor cobra é o que o saldo paga.

## O comprovante — três formas do mesmo fato

Toda ordem paga devolve as três, na mesma resposta e no mesmo webhook. Não é preciso montar URL na mão nem fazer segunda chamada.

| campo | o que é | para quê |
|---|---|---|
| `pix_e2e` | identificador oficial do Banco Central | conferência por terceiro, sem confiar em ninguém |
| `receipt_url` | página compartilhável | abrir no celular do cliente final |
| `receipt_pdf_url` | arquivo PDF | anexar em chamado, mandar no WhatsApp, contabilidade |
| `verify_url` | link direto da verificação aberta | dar ao contraparte para ele mesmo checar |

O PDF traz nome, documento e instituição do recebedor, valor, data, E2E e o link de verificação. É gerado da mesma fonte de dados da página — os dois nunca divergem.

Quem tem grupo no Telegram com a gente recebe o PDF como arquivo, automaticamente, a cada PIX pago.

## Comprar cripto pagando PIX (cash-in)

`POST /cashin/charge` gera o QR e o copia-e-cola; `GET /cashin/{id}/status` acompanha. O CPF ou CNPJ do pagador é obrigatório — exigência do Banco Central, e é ele que identifica a cobrança.

**Por cobrança: R$ 1,00 a R$ 6.000,00.** Até R$ 200,00 no dia daquele CPF/CNPJ o dinheiro entra na hora; de R$ 200,00 a R$ 6.000,00 por dia a cobrança também é aceita, mas o provedor **retém o valor por 24h** antes de liberar (é o estado `delayed`, não é falha). Isso vale **já na primeira operação** do documento — não é preciso ter histórico nem esperar 24h.

## Estados de uma cobrança (cash-in)

`pending` → ninguém pagou ainda · `under_review` → PIX recebido, liquidação em trânsito · `paid` → creditado · `expired` / `refunded` / `failed` → terminais.

**`delayed` merece atenção:** significa que o PIX **foi pago** e o provedor está segurando a liberação — é o que acontece com tudo que passa de R$ 200,00 no dia daquele pagador, retido por 24h, primeira operação inclusive. A resposta traz `delay_until` com o momento previsto de liberação.

Não trate `delayed` como falha e não cancele a ordem: ela vira `paid` sozinha quando a retenção termina. É o campo que permite responder ao cliente final que já pagou e está esperando. O evento `cashin.delayed` avisa no webhook.

## Limite do pagador — pergunte antes de cobrar

```
GET /cashin/limits?payer_tax={cpf_ou_cnpj}
```

Devolve `max_amount_cents` — o teto que entra **na hora** para aquele CPF/CNPJ — mais `stage`, `used_cents`, `available_cents` e `next_stage` (quando o teto sobe e para quanto). Acima dele, até R$ 6.000,00, a cobrança continua sendo aceita: volta `delayed`, retida 24h. Não leia esse número como o máximo que dá para cobrar.

Existe um degrau antifraude por pagador, independente da chave, e ele tem dois patamares: até **R$ 200,00** por dia naquele CPF/CNPJ o dinheiro entra na hora; de **R$ 200,00 a R$ 6.000,00** por dia a cobrança continua sendo aceita, mas o provedor **retém o valor por 24h** antes de liberar — é o estado `delayed`, não é recusa. Isso vale **já na primeira operação** do documento: não é preciso ter histórico nem esperar 24h para chegar aos R$ 6.000,00. O mínimo por cobrança é R$ 1,00 e o máximo é R$ 6.000,00.

Consulte antes de criar a cobrança. Chutar valor e levar 403 funciona para um humano que ajusta na hora; para um agente vira laço.

## Servidor MCP (Model Context Protocol)

```
https://api.luniumpay.com/mcp
```

Streamable HTTP, revisão `2025-06-18`, sem estado. Adicione como conector MCP remoto em qualquer host que fale o protocolo.

**Funciona sem credencial nenhuma.** Conecte sem chave e o `lunium_verify_pix_payment` já está disponível — confirma que um PIX foi liquidado, a partir do E2E, inclusive de um pagamento que não é seu. É esse o ponto: dá para conferir o que a contraparte alega sem ter conta e sem confiar nela.

As demais ferramentas exigem chave, enviada pelo host no header `X-API-Key`. Sem ela, respondem `erro: "chave_ausente"` com `acao: "parar"` — não somem da lista, para o agente conseguir avisar o usuário em vez de concluir que a capacidade não existe.

São oito: verificar pagamento · listar o que liquida agora · consultar limite do pagador · cotar venda de cripto · confirmar · criar cobrança PIX · acompanhar venda · acompanhar cobrança.

As duas que movem dinheiro de verdade vêm marcadas com `destructiveHint: true`, para o host poder exigir aprovação humana, e confirmar exige o `confirmation_token` da cotação, amarrado àquele valor, rede e destino. Vender é de propósito em dois passos: cotar não compromete nada, confirmar é irreversível.

## Sandbox — teste tudo antes de gastar qualquer coisa

```
POST https://api.luniumpay.com/keys/sandbox
```

Uma chamada. Sem nome, sem e-mail, sem carteira, sem aprovação. Você recebe uma chave `lun_test_…` que roda o fluxo **inteiro** sem um centavo se mover, na mesma URL base e no mesmo endpoint MCP. Código que funciona aqui funciona em produção sem mudança — mesmas formas, mesmos estados, mesmo contrato de erro.

A ordem **não** conclui na hora: ela caminha pelos estados reais em ~15 segundos, para você escrever o laço de acompanhamento (ou o webhook) que vai precisar de qualquer jeito.

**Gatilhos determinísticos.** Testar só o caminho feliz é como a integração quebra no primeiro dia, então as duas primeiras casas decimais do `amount` escolhem o desfecho — sem sorte envolvida, dá para afirmar isso em CI:

| `amount` terminado em | o que acontece |
|---|---|
| `.01` | ordem vai para **delayed** (PIX pago, provedor segurando) e conclui sozinha — prove que seu código não trata isso como falha |
| `.02` | ordem **falha** — exercite seu caminho de erro |
| `.03` | a cotação **expira** em 5s — prove que você recota em vez de insistir |
| `.04` | recusa por **limite**, com `limits.min_amount` / `max_amount` preenchidos |
| `.05` | conclui **devagar** (~2 min) — prove que seu polling tem paciência |

Reusar um `external_id` com destino diferente devolve **409**, igual à produção — é o caso que mais confunde integrador, e aqui dá para ensaiar.

**A verificação também funciona.** Uma ordem de sandbox gera um E2E bem formado com ISPB `00000000` — que nenhuma instituição real possui, então nunca pode ser confundido com pagamento de verdade. `GET /v1/verificar/{e2e}` responde para ele, marcado com `sandbox: true`.

Ordens de teste somem 2 horas depois de criadas. Nunca envie cripto para um `deposit_address` de sandbox: ele não tem dono e os fundos seriam perdidos.

## Limites

- **Cash-out, por transação: R$ 6,00 a R$ 250.000,00.** O limite é em reais e a chamada é em cripto, então a recusa devolve `limits.min_amount` e `limits.max_amount` já convertidos pela cotação daquela ordem — é literalmente o próximo valor a mandar.
- **Cash-out, por recebedor por dia: R$ 100.000,00.** Conta no CPF/CNPJ de quem **recebe** o PIX — ou na própria chave, quando ela é e-mail, telefone ou aleatória, porque nunca pedimos CPF de quem vende. Renova à meia-noite, horário de Brasília.
- **O máximo efetivo de uma operação é o MENOR dos dois.** Para um recebedor que ainda não recebeu nada no dia, o máximo real é R$ 100.000,00 — não R$ 250.000,00. A API já faz essa conta: `limits.max_brl_cents` é o que dá para mandar agora, e `limits.max_brl_cents_por_transacao` é o teto por transação. Precisa de mais? Divida em dias, ou pague outro recebedor.
- **Não existe teto diário por chave no cash-out.** O teto diário por chave (tier: R$ 5.000 · R$ 25.000 · R$ 100.000 por dia, cresce com o volume liquidado) vale para **cash-in e payouts**, e só para eles — `limits.daily_limit_applies_to` em `GET /keys/me` diz o escopo. Nunca leia o tier como limite da venda.
- **Cash-in, por cobrança: R$ 1,00 a R$ 6.000,00**, com degrau antifraude por pagador (CPF/CNPJ): até R$ 200,00 por dia entra na hora; de R$ 200,00 a R$ 6.000,00 por dia a cobrança é aceita, mas fica retida 24h antes de liberar — já na primeira operação, sem histórico nenhum. Pergunte antes: `GET /cashin/limits?payer_tax={cpf_ou_cnpj}` devolve `max_amount_cents` — o maior valor que o `POST /cashin/charge` aceita agora (retenção incluída), `instant_available_cents` — o que entra **na hora**, e `held_qr` — o degrau retido (teto, consumo, `hold_hours`). Acima do valor instantâneo e até `max_amount_cents` a cobrança é aceita com retenção de 24h: responde `held: true` e, paga, fica em `delayed` até liberar.
- Todo número daqui pode mudar. O `GET /keys/me` devolve os que valem para a sua chave — é o valor que nunca envelhece; leia ele em vez de fixar estes no código.
- Requisições: 60 por minuto por chave (configurável por cliente).

## Redes e prazos

`GET /catalog` é a fonte da verdade e muda sozinho. Não fixe lista no código.

- **Polygon** (USDT/USDC): liquidação nossa, PIX em segundos. É o padrão. Medido em produção: 49 a 57 segundos do aceite ao PIX pago.
- **Demais redes**: o prazo é o número de confirmações que cada rede exige — de cerca de 1 minuto (TON, Aptos) a algumas horas (Celo). Nunca prometa "instantâneo" fora da Polygon.
- **Solana** está temporariamente fora do cash-out. A cotação recusa explicitamente, em vez de aceitar uma ordem que não viraria PIX.

## Erros: o campo que diz o que fazer

Os erros carregam `erro` (código estável, não muda com a redação) e **`acao`**, que vale mais que a mensagem:

- `corrigir` — o pedido está errado. Repetir igual nunca vai passar.
- `repetir` — falha transitória nossa. Tente de novo.
- `esperar` — a cota renova. Volte depois.
- `parar` — não insista; fale com a gente.

### Todos os códigos de erro, e o que fazer com cada um

| `erro` | `acao` | o que aconteceu |
|---|---|---|
| `chave_ausente` | `parar` | falta o header `X-API-Key`. `POST /keys/sandbox` cria uma de teste na hora. |
| `formato_invalido` | `parar` | o valor não é uma chave Lunium. Chaves começam com `lun_` (produção) ou `lun_test_` (sandbox). |
| `chave_incorreta` | `parar` | **o prefixo existe mas o segredo não confere** — a chave foi cortada ao copiar. A mensagem diz quantos caracteres você enviou e quantos são esperados. |
| `chave_desconhecida` | `parar` | nenhuma chave começa com esse prefixo. Provavelmente o ambiente errado. |
| `campos_obrigatorios` | `corrigir` | `asset` e `network` são obrigatórios — veja `GET /catalog`. |
| `amount_invalido` | `corrigir` | `amount` tem que ser decimal positivo **em string**: `"25.5"`, não `25.5`. |
| `pix_key_obrigatoria` | `corrigir` | falta a `pix_key` (quem recebe os reais). |
| `tipo_ambiguo` | `corrigir` | a chave tem 11 dígitos puros, que pode ser CPF *ou* telefone. Recusamos em vez de chutar — pagar a pessoa errada é pior que um erro. Informe `pix_key_type`. |
| `pix_key_invalida` | `corrigir` | a chave não bate com o tipo declarado. |
| `valor_abaixo_do_minimo` | `corrigir` | leia `limits.min_amount` — já vem convertido na moeda da sua ordem. |
| `valor_acima_do_maximo` | `corrigir` | leia `limits.max_amount`, mesma ideia. |
| `limite_diario` | `esperar` | a cota diária do seu tier, em **cash-in e payouts, só neles** — cresce com o volume liquidado e renova à meia-noite, horário de Brasília. A venda não consome essa cota. |
| `limite_diario_recebedor` | `esperar` | só no cash-out, e é um código diferente de propósito: este recebedor já usou os **R$ 100.000** que um CPF/CNPJ (ou uma chave PIX, quando a chave não é documento) recebe por dia. `limits.payee_available_cents` diz quanto ainda cabe hoje. Renova à meia-noite, horário de Brasília — é o único erro em que tentar amanhã realmente funciona. |
| `rede_indisponivel` | `corrigir` | essa rede não está liquidando agora. Use `polygon` (segundos) ou outra de `GET /catalog`. |
| `nao_encontrado` | `corrigir` | o id está errado ou é de outra chave. Não repita o mesmo id. |

Os mesmos códigos saem do sandbox e da produção. Código que ramifica por `erro`
no sandbox continua funcionando quando você troca a chave.

**Todo carimbo de tempo leva o fuso.** `pago_em` sai como `2026-08-01T22:35:49-03:00` — horário de Brasília, explícito. Interprete como ISO 8601; nunca suponha que a string é UTC ou local.


A distinção existe porque os dois casos abaixo já devolveram a mesma resposta, e o errado custa caro: uma ordem maior que a cota de um dia inteiro devolvia "tente amanhã" — e amanhã falhava igual, para sempre.

## Regras que evitam erro caro

- `external_id` em toda ordem: é a chave de conciliação e torna a chamada idempotente. Repetir a mesma chamada devolve a mesma ordem, não cria outra.
- Leia `expires_at` da resposta em vez de fixar prazo. Hoje são 15 minutos na Polygon e até 300 minutos nas demais redes, mas isso muda.
- **Para vender, basta a chave PIX.** O tipo é deduzido dela para e-mail, CNPJ, chave aleatória e telefone com `+55`. `pix_key_type` só é exigido quando a chave são 11 dígitos puros — CPF e telefone têm o mesmo tamanho, e chutar pagaria a pessoa errada. Mande explícito quando souber; explícito sempre vence.
- **Deduplique webhooks pelo `event_id`** (`evt_…`, no corpo e no header `X-Lunium-Event-Id`). Ele é estável entre retentativas, então um retry nosso não credita seu usuário duas vezes. O `X-Lunium-Delivery-Id` é o oposto: identifica UMA tentativa, e é o número a citar no suporte.
- Verifique o `X-Lunium-Signature` (`t=<unix>,v1=<hmac de "t.corpo">`) e recuse o que tiver mais de ~5 minutos. O `X-Webhook-Signature` antigo (só o corpo) continua valendo, mas não tem hora dentro: uma entrega capturada pode ser reenviada contra você para sempre. Ela está descontinuada com data marcada: deixa de ser enviada em **09/11/2026**, e chaves criadas a partir de 08/08/2026 já não a recebem — verifique somente a v2.
- Trate evento desconhecido como no-op. A lista cresce sem aviso.
- `POST /webhooks/test` dispara um `webhook.test` pelo mesmo transporte da produção e devolve o que o SEU endpoint respondeu (status e latência). Rode antes da primeira cobrança real; não move dinheiro e funciona com chave de sandbox.
- Nada se perde em silêncio: a entrega que esgota as 12 tentativas (~7h de backoff) aparece como `failed` em `GET /webhooks/deliveries` e é recuperável com `POST /webhooks/deliveries/{event_id}/retry`.
- Prefira webhook a consulta repetida. Consultar uma vez por segundo consome sozinho o limite de 60 requisições por minuto da chave.
- Erro `400` numa rede significa que ela não liquida naquele momento. Recusar na cotação é barato; aceitar e não pagar é o que custa caro.

## Links

- [Documentação completa](https://docs.luniumpay.com): tabela de redes e prazos, ciclo de vida das ordens, exemplos em curl, Node e Python, assinatura dos webhooks.
- [OpenAPI](https://api.luniumpay.com/openapi.json): o contrato em máquina.
- [Status](https://docs.luniumpay.com/status): cash-in, cash-out, entrega de webhook e se a produção ainda cumpre a OpenAPI publicada — chamadas reais a cada 5 minutos. Em máquina: `/status.json`.
- [Aplicativo](https://app.luniumpay.com): dá para testar o fluxo inteiro sem escrever código.
- [Grupo de parceiros no Telegram](https://t.me/+FerOZMRRP_g5MDk5): status em tempo real e mudanças de contrato antes de irem ao ar. Participação recomendada para quem opera em produção.
- Contato: contato@luniumpay.com

## Conseguir uma chave sem passar por um humano

Se uma ferramenta respondeu `erro: "chave_ausente"`, você não precisa parar e pedir credenciais
ao seu usuário. Pegue sua própria chave de teste numa chamada:

```
POST https://api.luniumpay.com/keys/sandbox      # sem autenticação, sem formulário
{"name": "meu-agente"}
→ {"api_key": "lun_test_…", "sandbox": true, "como_usar": {…}}
```

Pelo MCP, o mesmo é a ferramenta `lunium_create_sandbox_key`, que — como a de verificação —
não exige chave nenhuma.

Ela roda o fluxo **inteiro** na mesma URL base e no mesmo endpoint MCP da produção, e nada
liquida: nenhuma cripto se move, nenhum PIX é pago, ninguém é cobrado. Diga com clareza ao seu
usuário que é uma chave de teste; mover dinheiro real exige chave de produção, e isso é decisão
de humano.

## O que esperar, em números que medimos

São medições, não promessas. Colhidas em 02/08/2026 contra o serviço no ar.

| | |
|---|---|
| Liquidação, da cotação ao PIX pago | **49–65 s** em Polygon |
| Ordem no sandbox, ponta a ponta | **p50 34 ms · p95 76 ms** com 20 simultâneas |
| Vazão sustentada, sandbox | **~200 ordens/s** sem a latência de produção se mexer |
| Limite por chave | **60 requisições/minuto** (um `429` é proteção, não falha) |
| Por transação (venda) | **R$ 6,00 a R$ 250.000,00** |
| Por recebedor por dia (venda) | **R$ 100.000,00** — na prática é esse o máximo de uma operação |
| Por cobrança (compra) | **R$ 1,00 a R$ 6.000,00** — passando de R$ 200,00 no dia do pagador, retido 24h |
| Cota diária por chave | tier **R$ 5.000 · R$ 25.000 · R$ 100.000** — cash-in e payouts, **nunca a venda** |

**Onde é mais lento, e por quê.** O trilho de conversão espera as confirmações da própria rede —
TON pede ~10 e Celo ~2.400, então a mesma ordem leva minutos ou horas conforme a rede de onde
você envia. O `GET /catalog` traz o prazo esperado por ativo; leia ele em vez de supor.

**O que não afirmamos.** Os números de sandbox acima exercitam a superfície da API, não uma
liquidação real: nenhuma cripto se move e nenhum PIX é pago, então eles não provam vazão de
ordens ao vivo. Dimensione seu retry pelo `expires_at` da resposta, nunca por uma janela fixa.

## Agent Skills

Installable skills for coding agents (Gemini, ChatGPT, Claude, Cursor):
https://github.com/guilhermezanqueta-collab/lunium-agent-skills — golden rules,
cash-in/cash-out/verify/webhooks flows. Every API error also returns
agent_guidance (machine-directed next step), and sandbox amounts ending in
.01-.08 trigger deterministic scenarios, including provider compliance refusal
(.06), provider instability with retry (.07) and the payer anti-fraud ladder (.08).