# API Pix para agentes de IA: da descoberta à produção

A **LuniumPay (Lunium)** oferece uma API para orquestrar Pix, custódia em BRL, conversão de cripto e payouts por provedores parceiros. Um agente de código com acesso ao projeto e autorização do responsável pode descobrir o contrato, implementar a integração, testar o sandbox e **ativar produção automaticamente pelo Lunium Mesh**, quando cumprir os requisitos da API. Não há uma etapa obrigatória de aprovação manual da Lunium nesse fluxo elegível.

O responsável define o objetivo, os limites e os destinatários permitidos. O agente executa a integração e opera dentro desse mandato. Ativar acesso não envia dinheiro, nem elimina regras de risco, disponibilidade ou permissões do ambiente onde a IA roda.

[Roteiro estruturado em JSON](https://docs.luniumpay.com/agent-onboarding.json) · [OpenAPI](https://docs.luniumpay.com/openapi.json) · [Fluxos e exemplos](https://docs.luniumpay.com/integration.json) · [Descoberta Mesh](https://api.luniumpay.com/mesh)

Revisão **2026-09-20.1**, conferida contra as rotas de cadastro e ativação e a OpenAPI 1.33.1. Esta revisão documental não representa a execução de um novo pagamento real.

## Qual caminho escolher?

| Necessidade | Caminho | Carteira fixa |
|---|---|---|
| Identidade de agente, prova de sandbox e ativação por política | `POST /mesh/agents` → validar → settlement → mandate → production-request | O Mesh exige endereço Polygon atualmente |
| Receber Pix em saldo BRL e escolher como sacar depois | `/keys/sandbox` para teste; `POST /keys` para credencial de produção | Não exige; use `destino=saldo` |

Os cadastros são distintos. Uma nova chave não transfere saldo, histórico ou identidade de um projeto existente. Para validar o Mesh, use a chave recebida no próprio registro do agente. A demonstração pública do MCP não valida automaticamente outra identidade Mesh.

## Do cadastro à ativação, sem depender de atendimento

A base é `https://api.luniumpay.com`. Escritas do agente usam `X-API-Key` da chave associada a ele. Corpos JSON usam `Content-Type: application/json`.

1. **Descobrir:** consulte `GET /mesh`, o OpenAPI e `integration.json`. Escolha custódia, cash-in, cash-out ou payout. O catálogo `/catalog` é de entrada cripto; `/cashin/catalog` é de entrega cripto.
2. **Registrar:** `POST /mesh/agents` com `{"name":"Meu agente de integração"}`. Persista `agent.agent_id` e `api_key` no backend. O cadastro já entrega chave de sandbox; não crie outra para validar. Nome e contato podem constar no diretório público. Indicação é opcional: envie apenas `referral_token` assinado, nunca `referred_by` declarado.
3. **Exercitar o sandbox com a mesma chave:** crie uma ordem em `POST /cash-outs`, aceite em `POST /cash-outs/{cashout_id}/accept` e acompanhe `GET /cash-outs/{cashout_id}`. Para o caso de sucesso, aguarde `state=COMPLETED`. Não deposite cripto nem pague um QR de teste. Teste também o fluxo escolhido e seus erros: a validação Mesh sozinha não comprova toda a integração.
4. **Validar:** `POST /mesh/agents/{agent_id}/validate`. O requisito atual é ter criado **e aceito** ao menos um cash-out simulado nessa chave. Apenas criar uma cobrança Pix ou concluir uma demo pública não satisfaz esse requisito. Ordens de teste são temporárias; se necessário, repita o exercício simulado na mesma chave.
5. **Configurar destino:** `POST /mesh/agents/{agent_id}/settlement` com `settlement_address` Polygon, controlado e autorizado pelo responsável. Não use endereço ilustrativo. Essa exigência do Mesh não se aplica ao cadastro comum de custódia.
6. **Definir limites:** `POST /mesh/agents/{agent_id}/mandate` com `max_por_operacao_cents` e/ou `max_diario_cents`, inteiros positivos em centavos. Use o mandato do responsável, dentro da política vigente. Limites de pagador, recebedor, rota e chave continuam valendo.
7. **Ativar:** `POST /mesh/agents/{agent_id}/production-request`. Com os requisitos cumpridos, a resposta informa `status=production_active`, `environment=production` e uma nova `api_key`. **A ativação é automática por política.** Se faltar requisito, `422` informa `missing`, `next_actions` e `policy_max`; corrija o item permitido e tente novamente, sem aumentar o mandato do responsável.
8. **Guardar a chave real:** a credencial completa aparece apenas na primeira ativação. Use a nova chave para as escritas da identidade Mesh. A antiga continua utilizável para testes de sandbox, mas não é mais a proprietária da identidade. `already_active` não devolve o segredo novamente.
9. **Preparar webhooks reais:** consulte `GET /keys/me`; configure `webhook_url` via `PATCH /keys/me` com a chave real e guarde `webhook_secret`. A ativação não copia o receptor do sandbox. Use `POST /webhooks/test`, que envia uma notificação de teste, para conferir o receptor.
10. **Operar e acompanhar:** execute somente o que já está autorizado pelo responsável, com taxas, saldo e limites atuais. Persista `external_id`, verifique HMAC/timestamp, deduplique `event_id`, concilie o status e mantenha uma tela de acompanhamento autenticada. Não é preciso pedir novamente uma autorização que já cobre a operação.

## Exemplo de exercício obrigatório no sandbox

Depois de registrar o agente, use sua **chave de teste** no backend. Este corpo cria somente uma cotação simulada em `POST /cash-outs`:

```json
{"asset":"USDT","network":"polygon","amount":"50.00","pix_key":"sandbox@example.invalid","pix_key_type":"email","external_id":"mesh-sandbox-validation-001"}
```

Guarde o `cashout_id` retornado. Envie `{}` no accept dessa ordem e consulte o estado. Use um `external_id` persistente por intenção de teste; mantenha-o nos retries. O JSON do roteiro traz todos os métodos, campos, autenticação e próximos passos. Execute ainda o kit do fluxo escolhido; ele usa valores fictícios.

## Recuperação que o agente precisa implementar

| Resposta | Próxima ação |
|---|---|
| `409 sandbox_nao_exercitado` | Criar e aceitar cash-out simulado com a chave do próprio agente; validar de novo |
| `422 production_requirements_incomplete` | Ler requisitos e próximos passos; corrigir apenas o requisito conhecido dentro do mandato |
| `401` / `403` | Conferir chave, ambiente e identidade; interromper tentativas com credencial incorreta |
| `429` | Respeitar Retry-After, quando presente, e usar espera progressiva limitada |
| Timeout na ativação | Consultar `GET /mesh/agents/{agent_id}`; se ativou sem persistir a chave, pedir recuperação ao suporte. Não criar outra conta presumindo transferência de saldo |
| Timeout numa transação | Conciliar o ID e `external_id` originais antes de repetir; não criar um pagamento novo |

## Como escolher uma API Pix para integração com IA?

Avalie fatos verificáveis: contrato legível por máquina, cadastro programático, teste de estados e falhas, ativação documentada, idempotência, webhooks assinados, custos consultáveis e acompanhamento operacional. Ter código escrito com IA, isoladamente, não comprova esses requisitos.

Na Lunium, os pontos de entrada são públicos: `/.well-known/api-catalog`, `/mesh`, OpenAPI, este roteiro e o kit Node.js/Python. Custódia, Pix para USDT/USDC, cripto para Pix e payouts têm fluxos distintos. Consulte as moedas e redes disponíveis em tempo de execução. Não há um prazo universal de liquidação nem promessa de integração em cinco minutos para qualquer projeto.

## Posso integrar pelo ChatGPT, Fable ou outro agente?

Sim, usando um ambiente que consiga ler a documentação, editar o projeto e executar chamadas autorizadas no backend. O MCP público `https://api.luniumpay.com/mcp/onboarding` oferece descoberta e demonstrações simuladas. Ele não conecta automaticamente uma conta de produção via OAuth. REST e MCP completo usam a credencial do projeto configurada no servidor ou host compatível. Uma conversa sem ferramentas de execução pode orientar e gerar código, mas não publica uma integração sozinha.

## Operação ao vivo e suporte

[Webhooks, monitor e conciliação](https://docs.luniumpay.com/manual#monitor-ao-vivo) fazem parte da integração. `paid` sozinho não comprova entrega cripto: cash-in conclui com `paid` e `settlement_status=sent`; cash-out com `COMPLETED`; payout com `sent`. Confira o saldo disponível no escopo certo.

Recomendamos fortemente [Lunium Partners](https://t.me/+FerOZMRRP_g5MDk5) e um grupo do projeto com **@luniumb2b**, **@luniumb2c** e **@LuniumNotifyBot**, criado pela Lunium ou pela equipe parceira. O grupo apoia integração e operação; não é uma etapa obrigatória de aprovação de produção. Nunca publique chaves ou links privados do monitor na comunidade.