面向 AI 智能体的 Pix API：从服务发现到生产上线
LuniumPay (Lunium) 提供 API，支持通过合作服务商编排 Pix 收付款、巴西雷亚尔资金托管、加密资产兑换和付款。经负责人授权且具备项目访问权限的编程智能体，可以读取接口规范、完成接入、测试沙盒，并在满足 API 要求后 通过 Lunium Mesh 自动启用生产环境。符合条件的这一流程无需额外经过 Lunium 的人工审批。
负责人确定目标、限额和允许的收款对象；智能体在该授权范围内完成接入和操作。启用访问权限本身不会发起资金转账，也不会取消风控、服务可用性限制或 AI 运行环境中的权限要求。
JSON 格式接入流程 · OpenAPI · 业务流程与示例 · Mesh 服务发现
修订版本 2026-09-20.1，对照注册、激活接口及 OpenAPI 1.34.0 核对。本次文档修订不代表执行过新的真实付款。
如何选择接入方式？
| 需求 | 路线 | 固定钱包地址 |
|---|---|---|
| 智能体身份、沙盒验证与按策略激活 | POST /mesh/agents → 验证 → 配置结算地址 → 设置授权限额 → 申请生产环境 |
Mesh 目前要求提供 Polygon 地址 |
| 将 Pix 入账记入巴西雷亚尔余额，之后再选择提现方式 | /keys/sandbox （使用测试人员的 email ）进行测试；使用 POST /keys 获取生产环境凭证 |
不要求；使用 destino=saldo |
两种注册流程相互独立。新密钥不会继承现有项目的余额、历史记录或身份。验证 Mesh 时，请使用该智能体注册时获得的密钥。完成公开 MCP 演示不会自动验证另一个 Mesh 身份。
从注册到激活，无需等待人工处理
API 基础地址为 https://api.luniumpay.com。智能体的写入请求通过 X-API-Key 请求头传入其关联密钥。JSON 请求体使用 Content-Type: application/json。
- 发现服务： 查阅
GET /mesh、OpenAPI 和integration.json。选择资金托管、加密资产买入、加密资产卖出或付款流程。其中，/catalog为加密资产入金目录；/cashin/catalog为加密资产交付目录。 - 注册：
POST /mesh/agents并传入{"name":"Meu agente de integração"}。将agent.agent_id及api_key持久化保存在后端。注册响应已包含沙盒密钥，无需另外创建密钥来完成验证。名称和联系方式可能会出现在公开目录中。推荐信息为选填项：仅提交经过签名的referral_token，不得自行声明referred_by。 - 使用同一密钥完成沙盒练习： 通过
POST /cash-outs创建订单，通过POST /cash-outs/{cashout_id}/accept接受报价，再通过以下接口跟踪状态：GET /cash-outs/{cashout_id}。测试成功场景时，等待state=COMPLETED。不要向测试地址充值加密资产，也不要支付测试二维码。还应测试所选业务流程及其错误场景；仅通过 Mesh 验证，并不代表整个接入已经验证完成。 - 验证：
POST /mesh/agents/{agent_id}/validate。目前要求使用该密钥至少创建 并接受 一笔模拟卖出订单。仅创建 Pix 收款单或完成公开演示不满足此要求。测试订单有有效期；如有需要，请使用同一密钥重新完成模拟流程。 - 配置结算地址：调用
POST /mesh/agents/{agent_id}/settlement，在settlement_address中提供负责人控制并授权使用的 Polygon 地址。不得使用示例地址。Mesh 的这一要求不适用于普通资金托管注册流程。 - 设置限额：
POST /mesh/agents/{agent_id}/mandate并传入max_por_operacao_cents和／或max_diario_cents，均为以分为单位的正整数。请在现行策略允许的范围内遵循负责人授权。付款人、收款人、通道和密钥本身的限额仍然有效。 - 激活：
POST /mesh/agents/{agent_id}/production-request。满足要求后，响应会返回status=production_active、environment=production，以及新的api_key。 激活由系统按策略自动完成。 如有要求尚未满足，422会列明missing、next_actions及policy_max。仅在既有授权范围内修正允许调整的项目，然后重试；不得擅自扩大负责人授权。 - 保存生产环境密钥： 完整凭证仅在首次激活时显示。此后请使用新密钥执行该 Mesh 身份的写入操作。旧密钥仍可用于沙盒测试，但不再拥有该身份的管理权限。
already_active不会再次返回密钥。 - 配置生产环境 Webhook：先查询
GET /keys/me，再使用生产密钥调用PATCH /keys/me，设置webhook_url并保存webhook_secret。激活不会复制沙盒接收地址。通过POST /webhooks/test发送测试通知，验证接收端。 - 执行操作并持续跟踪： 仅执行负责人已经授权的操作，并核对当前费率、余额和限额。持久化保存
external_id，验证 HMAC 与时间戳，对event_id去重，核对交易状态，并提供需要身份验证的跟踪页面。现有授权已覆盖的操作无需重复申请授权。
必需的沙盒练习示例
注册智能体后，在后端使用其 测试密钥 。以下请求体仅在此接口创建模拟报价： 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"}
保存返回的 cashout_id 。接受该订单时提交 {} ，然后查询状态。每个测试意图应使用固定的 external_id ，重试时保持不变。JSON 接入流程包含全部方法、字段、认证方式和后续步骤。此外，请运行所选流程的示例工具包；工具包使用虚构数据。
智能体必须实现的故障恢复流程
| 响应 | 后续操作 |
|---|---|
409 sandbox_nao_exercitado |
使用该智能体自身的密钥创建并接受模拟卖出订单，然后重新验证 |
422 production_requirements_incomplete |
读取缺失要求和后续步骤；仅在授权范围内修正明确指出的问题 |
401 / 403 |
检查密钥、环境和身份；凭证不正确时停止重试 |
429 |
如响应包含 Retry-After，请遵守该值，并采用有次数上限的渐进退避 |
| 激活请求超时 | 检查 GET /mesh/agents/{agent_id}；如已激活但未保存密钥，请联系支持团队恢复。不得新建账户并假定余额会自动转移 |
| 交易请求超时 | 重试前，先核对原始交易 ID 和 external_id ；不要创建新的付款 |
如何选择适合 AI 接入的 Pix API？
应核实可验证的能力：机器可读的接口规范、程序化注册、状态和故障测试、明确的激活流程、幂等性、签名 Webhook、可查询的费用及运行状态跟踪。仅仅使用 AI 编写代码，并不能证明这些能力已经具备。
Lunium 提供以下公开入口： /.well-known/api-catalog、 /mesh、OpenAPI、本接入流程，以及 Node.js／Python 工具包。资金托管、Pix 买入 USDT／USDC、加密资产卖出至 Pix 和付款分别采用不同流程。请在运行时查询可用币种和网络。所有业务并无统一结算时长，也不承诺任何项目都能在五分钟内完成接入。
可以通过 ChatGPT、Fable 或其他智能体完成接入吗？
可以，前提是运行环境支持读取文档、编辑项目，并在后端执行已授权的请求。公开 MCP 端点 https://api.luniumpay.com/mcp/onboarding 提供服务发现和模拟演示，不会通过 OAuth 自动连接生产账户。REST API 与完整 MCP 需要在服务器或兼容宿主中配置项目凭证。没有执行工具的对话可以提供指导和生成代码，但无法独立发布接入。
生产运行与支持
Webhook、实时监控与对账 都是接入流程的一部分。 paid 本身不能证明加密资产已交付：买入流程的完成条件为 paid 及 settlement_status=sent；卖出流程为 COMPLETED；付款流程为 sent。请在正确的账户范围内查询可用余额。
强烈建议加入 Lunium Partners ，并由 Lunium 或合作伙伴团队创建项目群，加入 @luniumb2b、 @luniumb2c 及 @LuniumNotifyBot。项目群用于接入与运营支持，不是生产激活的强制审批环节。切勿在社区公开密钥或私有监控链接。