{
  "revision": "2026-09-20.1",
  "reviewed_at": "2026-09-20",
  "name": "LuniumPay 智能体自主接入",
  "api_base": "https://api.luniumpay.com",
  "openapi": "https://docs.luniumpay.com/zh/openapi.json",
  "discovery": "https://api.luniumpay.com/mesh",
  "human_guide": "https://docs.luniumpay.com/zh/agent-onboarding",
  "markdown": "https://docs.luniumpay.com/zh/agent-onboarding.md",
  "purpose": "发现 Pix API、实现选定付款流程、通过沙盒测试，并在负责人授权范围内自动激活符合条件的 Mesh 生产访问权限。",
  "scope": "技术配置按策略自动完成，不代表允许任意转账，也不保证所有通道的执行、流动性、价格或审批结果。",
  "owner_inputs": [
    "业务流程与目标代码库",
    "测试人员邮箱：直接调用 POST /keys/sandbox 时必填；在 MCP 工具 lunium_create_sandbox_key、lunium_start_sandbox_demo 中为选填，但强烈建议提供。LuniumPay 会向本人发送一次带退订链接的接入指南；未提供时仍应创建密钥，之后通过 lunium_contact 补充",
    "生产激活与财务操作授权，包括允许的金额和收款对象",
    "Mesh 流程所需、由负责人控制的 Polygon 结算地址",
    "后端密钥存储与 HTTPS Webhook 接收端"
  ],
  "tracks": {
    "mesh": {
      "registration": "POST /mesh/agents",
      "returns": [
        "agent.agent_id",
        "api_key",
        "测试环境"
      ],
      "production_activation": "POST /mesh/agents/{agent_id}/production-request",
      "manual_provisioning_required": false,
      "policy_requirements": [
        "有效的智能体及其关联密钥",
        "通过沙盒验证：使用 Mesh 注册所得密钥，至少创建并接受一笔卖出订单",
        "Polygon 结算地址",
        "至少设置一项符合现行策略的金额授权上限"
      ],
      "fixed_polygon_address_required": true
    },
    "custody_without_fixed_wallet": {
      "sandbox_registration": "POST /keys/sandbox",
      "sandbox_registration_required": [
        "email"
      ],
      "production_registration": "POST /keys",
      "fixed_wallet_required": false,
      "guide": "https://docs.luniumpay.com/zh/manual#primeiros-passos",
      "relationship": "独立的自助密钥配置流程，不能替代 Mesh 验证。创建第二个密钥不会迁移现有账户、余额或智能体身份。"
    }
  },
  "authentication": {
    "header": "X-API-Key",
    "mesh_writes": "使用当前关联该智能体的密钥；仅有 agent_id 不构成授权。激活后，智能体写入操作应使用新发放的生产密钥。",
    "secret_storage": "立即将密钥持久化保存在服务端密钥存储中，不得写入日志、浏览器包、提示词或支持消息。"
  },
  "steps": [
    {
      "id": "discover",
      "method": "GET",
      "path": "/mesh",
      "authentication": "none",
      "next": "register",
      "read": [
        "https://docs.luniumpay.com/zh/openapi.json",
        "https://docs.luniumpay.com/zh/integration.json"
      ]
    },
    {
      "id": "register",
      "method": "POST",
      "path": "/mesh/agents",
      "authentication": "none",
      "body_example": {
        "name": "My authorized integration agent"
      },
      "success_statuses": [
        201
      ],
      "save": [
        "agent.agent_id",
        "api_key"
      ],
      "next": "quote_sandbox",
      "notes": [
        "注册时已创建沙盒密钥；不要另建 /keys/sandbox 密钥来进行 Mesh 验证。",
        "可选的 referral_token 为向推荐人签发的签名证明。切勿直接提交 referred_by。",
        "智能体名称、描述与联系方式可能出现在公开目录中，不要登记客户私密信息。"
      ]
    },
    {
      "id": "quote_sandbox",
      "method": "POST",
      "path": "/cash-outs",
      "authentication": "agent_sandbox_key",
      "body_example": {
        "asset": "USDT",
        "network": "polygon",
        "amount": "50.00",
        "pix_key": "sandbox@example.invalid",
        "pix_key_type": "email",
        "external_id": "mesh-sandbox-validation-001"
      },
      "success_statuses": [
        200,
        201
      ],
      "save": [
        "cashout_id"
      ],
      "next": "accept_sandbox",
      "notes": [
        "仅用于沙盒。每个测试意图使用唯一且已持久化的 external_id，重试时复用。不发生真实入金。可用币种组合与场景见沙盒指南。"
      ]
    },
    {
      "id": "accept_sandbox",
      "method": "POST",
      "path": "/cash-outs/{cashout_id}/accept",
      "authentication": "agent_sandbox_key",
      "body_example": {},
      "next": "track_sandbox",
      "notes": [
        "切勿向沙盒入金地址转入加密资产。"
      ]
    },
    {
      "id": "track_sandbox",
      "method": "GET",
      "path": "/cash-outs/{cashout_id}",
      "authentication": "agent_sandbox_key",
      "success_condition": "此成功场景要求 state == COMPLETED",
      "next": "validate",
      "notes": [
        "采用有次数上限的轮询与退避。同时测试 integration.json 中所选业务流程及失败路径；通过 Mesh 验证并不能证明整个接入已具备上线条件。"
      ]
    },
    {
      "id": "validate",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/validate",
      "authentication": "agent_sandbox_key",
      "body_example": {},
      "success_condition": "validado == true",
      "next": "settlement",
      "notes": [
        "409 sandbox_nao_exercitado 要求在同一密钥下创建并接受报价。临时沙盒订单可能过期；必要时使用同一密钥重新完成模拟练习。"
      ]
    },
    {
      "id": "settlement",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/settlement",
      "authentication": "agent_sandbox_key",
      "body_template": {
        "settlement_address": "${OWNER_POLYGON_ADDRESS}"
      },
      "next": "mandate",
      "notes": [
        "使用负责人批准的真实 Polygon 地址，不得使用示例地址。此项为 Mesh 激活要求，不适用于普通密钥配置下的 BRL 托管。"
      ]
    },
    {
      "id": "mandate",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/mandate",
      "authentication": "agent_sandbox_key",
      "body_template": {
        "max_por_operacao_cents": "${OWNER_MAX_PER_OPERATION_CENTS_INTEGER}",
        "max_diario_cents": "${OWNER_MAX_DAILY_CENTS_INTEGER}"
      },
      "next": "activate",
      "notes": [
        "替换为正整数 BRL 分值，而非字符串。激活至少需要一个金额上限，现行策略仍可能规定更低限额。422 响应不代表允许提高负责人设定的限额。"
      ]
    },
    {
      "id": "activate",
      "method": "POST",
      "path": "/mesh/agents/{agent_id}/production-request",
      "authentication": "agent_sandbox_key",
      "body_example": {},
      "success_condition": "status == production_active AND environment == production",
      "save": [
        "api_key（仅首次激活时返回）",
        "agent_id",
        "mandate",
        "capabilities"
      ],
      "next": "inspect_live_key",
      "notes": [
        "满足前提条件后无需人工审批队列。继续前先保存返回的生产密钥。激活本身不会转移资金。",
        "旧沙盒密钥仍可用于模拟操作，但智能体的管理权限转移至生产密钥。already_active 不会再次发放密钥。"
      ]
    },
    {
      "id": "inspect_live_key",
      "method": "GET",
      "path": "/keys/me",
      "authentication": "agent_live_key",
      "next": "configure_live_webhook",
      "notes": [
        "确认实际权限、费用、限额与授权。Mesh 激活成功不意味着所有产品流程均已启用。"
      ]
    },
    {
      "id": "configure_live_webhook",
      "method": "PATCH",
      "path": "/keys/me",
      "authentication": "agent_live_key",
      "body_template": {
        "webhook_url": "${OWNED_HTTPS_WEBHOOK_URL}"
      },
      "save": [
        "webhook_secret"
      ],
      "next": "verify_live_webhook",
      "notes": [
        "生产激活会创建没有 Webhook URL 的独立密钥；不会复制沙盒接收地址或密文。"
      ]
    },
    {
      "id": "verify_live_webhook",
      "method": "POST",
      "path": "/webhooks/test",
      "authentication": "agent_live_key",
      "body_example": {},
      "next": "ready_under_mandate",
      "notes": [
        "此操作发送测试回调，不是付款。验证接收端持久化、原始请求体 HMAC、时间戳与去重。"
      ]
    }
  ],
  "ready_under_mandate": {
    "financial_flow_contract": "https://docs.luniumpay.com/zh/integration.json",
    "live_tracking": "https://docs.luniumpay.com/zh/manual#monitor-ao-vivo",
    "operational_recovery": "https://docs.luniumpay.com/zh/operations-playbook.json",
    "rule": "仅执行负责人现有授权及实际 API 限额覆盖的操作。如缺少授权范围，应申请该范围；发现一份文档并不构成授权。"
  },
  "errors": {
    "401_or_403": "停止写入，核对当前密钥、环境及智能体的实际归属。不要反复注册替代账户。",
    "409_sandbox_nao_exercitado": "使用该智能体自身的沙盒密钥创建并接受一笔模拟卖出订单，然后重新验证。",
    "422_production_requirements_incomplete": "读取 missing、next_actions 和 policy_max。仅在负责人授权范围内修正已确认的前提条件。限制重试次数，无法继续推进时停止。",
    "429": "如有 Retry-After，请遵守该值；否则采用有次数上限的指数退避。不要循环创建密钥。",
    "activation_timeout_or_already_active_without_key": "通过 GET /mesh/agents/{agent_id} 读取智能体状态。不要假定旧沙盒密钥仍拥有新激活身份，也不要假定重试会再次返回生产密钥。激活密钥丢失时请联系支持团队恢复。",
    "financial_timeout": "重试前先对账核对原操作及 external_id。切勿为消除未知结果而新建业务付款。"
  },
  "mcp": {
    "onboarding": "https://api.luniumpay.com/mcp/onboarding",
    "full": "https://api.luniumpay.com/mcp",
    "distinction": "公开接入端点提供发现与模拟演示。生产 REST 或完整 MCP 要求在服务器／宿主配置已授权的项目凭证，不会通过 ChatGPT OAuth 自动关联生产账户。"
  },
  "support": {
    "community": "https://t.me/+FerOZMRRP_g5MDk5",
    "human_contacts": [
      "@luniumb2b",
      "@luniumb2c"
    ],
    "notification_bot": "@LuniumNotifyBot",
    "group_created_by": [
      "Lunium",
      "合作伙伴团队"
    ],
    "strongly_recommended": true,
    "required_for_api": false
  },
  "evidence": {
    "checked_against": [
      "routes/mesh.js",
      "src/lib/mesh.js",
      "已发布的 OpenAPI 1.34.0"
    ],
    "verification_scope": "仅核验规范与实现；不声称本次文档发布执行过新的真实付款或生产激活。"
  }
}