# 面向 AI 智能体的 Pix API：从服务发现到生产上线

**LuniumPay (Lunium)** 提供 API，支持通过合作服务商编排 Pix 收付款、巴西雷亚尔资金托管、加密资产兑换和付款。经负责人授权且具备项目访问权限的编程智能体，可以读取接口规范、完成接入、测试沙盒，并在满足 API 要求后 **通过 Lunium Mesh 自动启用生产环境**。符合条件的这一流程无需额外经过 Lunium 的人工审批。

负责人确定目标、限额和允许的收款对象；智能体在该授权范围内完成接入和操作。启用访问权限本身不会发起资金转账，也不会取消风控、服务可用性限制或 AI 运行环境中的权限要求。

[JSON 格式接入流程](https://docs.luniumpay.com/zh/agent-onboarding.json) · [OpenAPI](https://docs.luniumpay.com/zh/openapi.json) · [业务流程与示例](https://docs.luniumpay.com/zh/integration.json) · [Mesh 服务发现](https://api.luniumpay.com/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`。

1. **发现服务：** 查阅 `GET /mesh`、OpenAPI 和 `integration.json`。选择资金托管、加密资产买入、加密资产卖出或付款流程。其中， `/catalog` 为加密资产入金目录； `/cashin/catalog` 为加密资产交付目录。
2. **注册：** `POST /mesh/agents` 并传入 `{"name":"Meu agente de integração"}`。将 `agent.agent_id` 及 `api_key` 持久化保存在后端。注册响应已包含沙盒密钥，无需另外创建密钥来完成验证。名称和联系方式可能会出现在公开目录中。推荐信息为选填项：仅提交经过签名的 `referral_token` ，不得自行声明 `referred_by` 。
3. **使用同一密钥完成沙盒练习：** 通过 `POST /cash-outs`创建订单，通过 `POST /cash-outs/{cashout_id}/accept` 接受报价，再通过以下接口跟踪状态： `GET /cash-outs/{cashout_id}`。测试成功场景时，等待 `state=COMPLETED`。不要向测试地址充值加密资产，也不要支付测试二维码。还应测试所选业务流程及其错误场景；仅通过 Mesh 验证，并不代表整个接入已经验证完成。
4. **验证：** `POST /mesh/agents/{agent_id}/validate`。目前要求使用该密钥至少创建 **并接受** 一笔模拟卖出订单。仅创建 Pix 收款单或完成公开演示不满足此要求。测试订单有有效期；如有需要，请使用同一密钥重新完成模拟流程。
5. **配置结算地址：**调用 `POST /mesh/agents/{agent_id}/settlement`，在 `settlement_address` 中提供负责人控制并授权使用的 Polygon 地址。不得使用示例地址。Mesh 的这一要求不适用于普通资金托管注册流程。
6. **设置限额：** `POST /mesh/agents/{agent_id}/mandate` 并传入 `max_por_operacao_cents` 和／或 `max_diario_cents`，均为以分为单位的正整数。请在现行策略允许的范围内遵循负责人授权。付款人、收款人、通道和密钥本身的限额仍然有效。
7. **激活：** `POST /mesh/agents/{agent_id}/production-request`。满足要求后，响应会返回 `status=production_active`、 `environment=production` ，以及新的 `api_key`。 **激活由系统按策略自动完成。** 如有要求尚未满足， `422` 会列明 `missing`、 `next_actions` 及 `policy_max`。仅在既有授权范围内修正允许调整的项目，然后重试；不得擅自扩大负责人授权。
8. **保存生产环境密钥：** 完整凭证仅在首次激活时显示。此后请使用新密钥执行该 Mesh 身份的写入操作。旧密钥仍可用于沙盒测试，但不再拥有该身份的管理权限。 `already_active` 不会再次返回密钥。
9. **配置生产环境 Webhook：**先查询 `GET /keys/me`，再使用生产密钥调用 `PATCH /keys/me`，设置 `webhook_url` 并保存 `webhook_secret`。激活不会复制沙盒接收地址。通过 `POST /webhooks/test` 发送测试通知，验证接收端。
10. **执行操作并持续跟踪：** 仅执行负责人已经授权的操作，并核对当前费率、余额和限额。持久化保存 `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、实时监控与对账](https://docs.luniumpay.com/zh/manual#monitor-ao-vivo) 都是接入流程的一部分。 `paid` 本身不能证明加密资产已交付：买入流程的完成条件为 `paid` 及 `settlement_status=sent`；卖出流程为 `COMPLETED`；付款流程为 `sent`。请在正确的账户范围内查询可用余额。

强烈建议加入 [Lunium Partners](https://t.me/+FerOZMRRP_g5MDk5) ，并由 Lunium 或合作伙伴团队创建项目群，加入 **@luniumb2b**、 **@luniumb2c** 及 **@LuniumNotifyBot**。项目群用于接入与运营支持，不是生产激活的强制审批环节。切勿在社区公开密钥或私有监控链接。