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 · OpenAPI · Fluxos e exemplos · Descoberta 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.

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.
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.
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.
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.
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.
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.
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.
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.
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.
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:

{"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 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 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.