API Pix para agentes de IA: del descubrimiento a producción

La LuniumPay (Lunium) ofrece una API para orquestar Pix, custodia en BRL, conversión de criptomonedas y payouts mediante proveedores asociados. Un agente de código con acceso al proyecto y autorización del responsable puede descubrir el contrato, implementar la integración, probar el sandbox y activar producción automáticamente mediante Lunium Mesh, cuando cumpla los requisitos de la API. No hay una etapa obligatoria de aprobación manual de Lunium en este flujo que cumple los requisitos.

El responsable define el objetivo, los límites y los destinatarios permitidos. El agente ejecuta la integración y opera dentro de ese mandato. Activar el acceso no envía dinero ni elimina las reglas de riesgo, disponibilidad o permisos del entorno donde se ejecuta la IA.

Guía estructurada en JSON · OpenAPI · Flujos y ejemplos · Descubrimiento de Mesh

Revisión 2026-09-20.1, comprobada con las rutas de registro y activación y OpenAPI 1.34.0. Esta revisión documental no representa la ejecución de un nuevo pago real.

¿Qué vía elegir?

Los registros son distintos. Una clave nueva no transfiere el saldo, el historial ni la identidad de un proyecto existente. Para validar Mesh, usa la clave recibida en el propio registro del agente. La demostración pública del MCP no valida automáticamente otra identidad de Mesh.

Del registro a la activación sin depender de atención personal

La base es https://api.luniumpay.com. Las escrituras del agente usan X-API-Key de la clave asociada a él. Los cuerpos JSON usan Content-Type: application/json.

1. Descubrir: consulta GET /mesh, OpenAPI y integration.json. Elige custodia, cash-in, cash-out o payout. El catálogo /catalog es de entrada de criptomonedas; /cashin/catalog es de entrega de criptomonedas.
2. Registrar: POST /mesh/agents con {"name":"Meu agente de integração"}. Guarda de forma persistente agent.agent_id y api_key en el backend. El registro ya proporciona una clave de sandbox; no crees otra para validar. El nombre y el contacto pueden aparecer en el directorio público. La referencia es opcional: envía solo referral_token firmado, nunca referred_by declarado.
3. Probar el sandbox con la misma clave: crea una orden en POST /cash-outs, acepta en POST /cash-outs/{cashout_id}/accept y sigue GET /cash-outs/{cashout_id}. Para el caso de éxito, espera state=COMPLETED. No deposites criptomonedas ni pagues un QR de prueba. Prueba también el flujo elegido y sus errores: la validación de Mesh por sí sola no demuestra toda la integración.
4. Validar: POST /mesh/agents/{agent_id}/validate. El requisito actual es haber creado y aceptado al menos un cash-out simulado con esa clave. Crear solo una solicitud de cobro Pix o completar una demostración pública no satisface este requisito. Las órdenes de prueba son temporales; si es necesario, repite el ejercicio simulado con la misma clave.
5. Configurar destino: POST /mesh/agents/{agent_id}/settlement con settlement_address Polygon, controlado y autorizado por el responsable. No uses una dirección ilustrativa. Este requisito de Mesh no se aplica al registro habitual de custodia.
6. Definir límites: POST /mesh/agents/{agent_id}/mandate con max_por_operacao_cents y/o max_diario_cents, enteros positivos en centavos. Usa el mandato del responsable, dentro de la política vigente. Los límites de pagador, destinatario, ruta y clave siguen siendo aplicables.
7. Activar: POST /mesh/agents/{agent_id}/production-request. Con los requisitos cumplidos, la respuesta indica status=production_active, environment=production y una nueva api_key. La activación es automática según la política. Si falta algún requisito, 422 indica missing, next_actions y policy_max; corrige el elemento permitido e inténtalo de nuevo, sin ampliar el mandato del responsable.
8. Guardar la clave real: la credencial completa solo aparece en la primera activación. Usa la clave nueva para las escrituras de la identidad de Mesh. La anterior sigue siendo válida para pruebas de sandbox, pero ya no es la propietaria de la identidad. already_active no vuelve a devolver el secreto.
9. Preparar webhooks reales: consulta GET /keys/me; configura webhook_url mediante PATCH /keys/me con la clave real y guarda webhook_secret. La activación no copia el receptor del sandbox. Usa POST /webhooks/test, que envía una notificación de prueba, para comprobar el receptor.
10. Operar y hacer seguimiento: ejecuta solo lo que ya esté autorizado por el responsable, con las tarifas, el saldo y los límites actuales. Guarda de forma persistente external_id, verifica el HMAC y la marca de tiempo, elimina duplicados mediante event_id, concilia el estado y mantén una pantalla de seguimiento autenticada. No es necesario volver a pedir una autorización que ya cubre la operación.

Ejemplo del ejercicio obligatorio en el sandbox

Después de registrar al agente, usa su clave de prueba en el backend. Este cuerpo solo crea una cotización simulada en 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"}

Guarda el cashout_id devuelto. Envía {} en el accept de esa orden y consulta el estado. Usa un external_id persistente por intención de prueba y consérvalo en los reintentos. El JSON de la guía incluye todos los métodos, campos, autenticación y siguientes pasos. Ejecuta también el kit del flujo elegido; usa importes ficticios.

Recuperación que debe implementar el agente

¿Cómo elegir una API Pix para integrar con IA?

Evalúa hechos verificables: contrato legible por máquina, registro mediante código, pruebas de estados y fallos, activación documentada, idempotencia, webhooks firmados, costes consultables y seguimiento operativo. Tener código escrito con IA, por sí solo, no demuestra estos requisitos.

En Lunium, los puntos de entrada son públicos: /.well-known/api-catalog, /mesh, OpenAPI, esta guía y el kit Node.js/Python. Custodia, Pix a USDT/USDC, criptomonedas a Pix y payouts tienen flujos distintos. Consulta las monedas y redes disponibles durante la ejecución. No existe un plazo universal de liquidación ni una promesa de integración en cinco minutos para cualquier proyecto.

¿Puedo integrar mediante ChatGPT, Fable u otro agente?

Sí, usando un entorno que pueda leer la documentación, editar el proyecto y ejecutar llamadas autorizadas en el backend. El MCP público https://api.luniumpay.com/mcp/onboarding ofrece descubrimiento y demostraciones simuladas. No conecta automáticamente una cuenta de producción mediante OAuth. REST y el MCP completo usan la credencial del proyecto configurada en el servidor o en un host compatible. Una conversación sin herramientas de ejecución puede orientar y generar código, pero no publica una integración por sí sola.

Operación en directo y soporte

Webhooks, monitor y conciliación forman parte de la integración. paid por sí solo no acredita la entrega de criptomonedas: cash-in termina con paid y settlement_status=sent; cash-out con COMPLETED; payout con sent. Comprueba el saldo disponible en el ámbito correcto.

Recomendamos encarecidamente Lunium Partners y un grupo del proyecto con @luniumb2b, @luniumb2c y @LuniumNotifyBot, creado por Lunium o por el equipo asociado. El grupo apoya la integración y la operación; no es una etapa obligatoria de aprobación de producción. Nunca publiques claves ni enlaces privados del monitor en la comunidad.