{
  "revision": "2026-10-06.2",
  "api_base": "https://api.luniumpay.com",
  "openapi": "https://docs.luniumpay.com/zh/openapi.json",
  "manual": "https://docs.luniumpay.com/zh/manual",
  "start_url": "https://luniumpay.com/zh/integrar",
  "flows": {
    "custody": {
      "title": "Pix 收款记入托管余额",
      "description": "先以 BRL 余额入账，提现时再选择币种、网络与地址，无需固定钱包。",
      "sandbox_supported": true,
      "operations": [
        "GET /keys/me",
        "GET /cashin/limits?payer_tax=CPF_DO_PAGADOR",
        "POST /cashin/charge com destino=saldo",
        "GET /cashin/{cashin_id}/status",
        "GET /saldo?customer_ref=CLIENTE",
        "GET /cashin/catalog",
        "POST /saldo/sacar-cripto"
      ],
      "create_example": {
        "amount_cents": 5000,
        "payer_tax_number": "CPF_REAL_DO_PAGADOR",
        "destino": "saldo",
        "customer_ref": "cliente-42",
        "external_id": "deposito-cliente42-001"
      },
      "completion": "入账确认条件：status=paid 且 settlement_status=sent。请在正确范围内核对 disponivel_cents。"
    },
    "cashin": {
      "title": "Pix 收款后直接交付加密资产",
      "description": "每笔收款单均可指定币种、网络与钱包。创建前请查询现行通道和最低金额。",
      "sandbox_supported": true,
      "operations": [
        "GET /cashin/catalog",
        "POST /cashin/preview",
        "GET /cashin/limits?payer_tax=CPF_DO_PAGADOR",
        "POST /cashin/charge com destino=cripto",
        "GET /cashin/{cashin_id}/status"
      ],
      "create_example": {
        "amount_cents": 5000,
        "payer_tax_number": "CPF_REAL_DO_PAGADOR",
        "destino": "cripto",
        "asset": "USDT",
        "chain": "polygon",
        "payout_address": "CARTEIRA_INFORMADA_PELO_CLIENTE",
        "external_id": "compra-cripto-001"
      },
      "completion": "Pix 已支付：status=paid。发送已登记：settlement_status=sent。链上确认已登记：settlement_proof=confirmed 且存在 settlement_confirmed_at。broadcast 表示已广播但未登记确认；缺少确认记录不代表失败。simulated 仅用于测试。"
    },
    "cashout": {
      "title": "使用加密资产支付 Pix，并获取凭证",
      "description": "提供 Pix 收款键及 BRL 目标金额，或加密资产数量。支付现有收款单时，提交完整的 Pix 复制粘贴码；目前在兼容通道支持 USDT／USDC。用户核对并接受报价后再转入加密资产。",
      "sandbox_supported": true,
      "operations": [
        "GET /catalog",
        "POST /cash-outs",
        "POST /cash-outs/{cashout_id}/accept",
        "GET /cash-outs/{cashout_id}"
      ],
      "create_example": {
        "asset": "USDT",
        "network": "polygon",
        "amount": "10",
        "pix_key": "sandbox@example.invalid",
        "pix_key_type": "email",
        "external_id": "sandbox-cashout-001"
      },
      "completion": "state=COMPLETED 确认 Pix 已支付。提供 pix_e2e 及返回的 receipt_url、receipt_pdf_url 和 verify_url。链接可能稍后生成：继续查询同一订单，或等待 cashout.receipt_ready，不要再次付款。"
    },
    "payout": {
      "title": "使用托管余额支付 Pix",
      "description": "仅使用平台账户或子账户通过 Pix 收到的 BRL 余额。每笔 Pix 最高 R$6,000.00，仍受账户更低限额与当前 API 费用约束。必须提供有效的收款人 CPF／CNPJ，也可从有效的 CPF／CNPJ 收款键中取得。USDT 钱包独立运行，须按权限启用，其限额由报价决定，不适用此上限。",
      "sandbox_supported": true,
      "operations": [
        "GET /keys/me",
        "GET /saldo?customer_ref=CLIENTE",
        "POST /payouts",
        "GET /payouts/{payout_id}"
      ],
      "create_example": {
        "amount_cents": 5000,
        "pix_key": "CHAVE_PIX_DO_DESTINATARIO",
        "pix_key_type": "email",
        "customer_ref": "cliente-42",
        "external_id": "saque-pix-cliente42-001",
        "tax_number": "CPF_OU_CNPJ_VALIDO_DO_RECEBEDOR",
        "funding_source": "pix_brl"
      },
      "completion": "付款确认条件：status=sent。超时后保留 external_id，查询原订单。收到 409 external_id_divergente 或 external_id_nao_verificavel 时，使用 payout_id／recovery_endpoint，不要更换 ID 绕过限制。收到 503 idempotencia_indisponivel 时，等待并查询同一 ID。"
    },
    "usdt_wallet": {
      "title": "USDT/USDC 钱包：加密资产余额与 Pix 付款",
      "description": "通过多种网络转入 USDT 或 USDC，并使用余额通过 Pix 收款键或复制粘贴码付款。面向所有生产密钥开放。",
      "sandbox_supported": true,
      "operations": [
        "GET /carteira-usdt",
        "POST /carteira-usdt/deposits",
        "GET /carteira-usdt/deposits",
        "POST /carteira-usdt/quote",
        "POST /carteira-usdt/payments",
        "GET /carteira-usdt/payments/{payment_id}",
        "GET /carteira-usdt/statement"
      ],
      "create_example": {
        "amount": "100",
        "network": "tron"
      },
      "completion": "入金已入账：GET /carteira-usdt/deposits 返回 status=available，或收到 wallet.deposit_credited Webhook。Pix 已支付：status=concluido 且 final=true，并提供 pix_e2e 和 receipt_url，或收到 wallet.payment_completed Webhook。"
    }
  },
  "sandbox": {
    "simulates": [
      "Pix 收款单包含不可实际支付的二维码，须显式模拟付款",
      "BRL 托管入账与暂不可用余额",
      "在受支持的快照通道中模拟加密资产交付及托管提现",
      "使用托管余额支付 Pix",
      "子账户转账",
      "卖出报价、接受报价与状态流转",
      "签名 Webhook 发件队列、重试与投递历史"
    ],
    "does_not_simulate": [
      "真实银行或合作交易所执行",
      "当前市场价格、通道可用性或生产环境风控分级",
      "真实区块链确认"
    ],
    "safety": "所有资金均为模拟资金。仅通过 POST /sandbox/cashin/{cashin_id}/pay 模拟确认 Pix。切勿在银行支付测试二维码或转入加密资产。生产环境依赖真实服务商、相应权限与可用资金。",
    "guide": "https://docs.luniumpay.com/zh/sandbox",
    "capabilities": "GET /sandbox",
    "key_creation": {
      "request": "POST /keys/sandbox",
      "body_example": {
        "email": "you@company.com",
        "name": "my-integration"
      },
      "required": [
        "email"
      ],
      "email": "测试人员本人的邮箱。LuniumPay 支持系统通常约一分钟后向其发送一封邮件，介绍服务、三步接入流程、手册与 PDF、流程图及 VendaCripto。每个邮箱仅发送一次，并提供退订链接。请向本人索取，不得编造或复用他人邮箱。",
      "missing_email": "HTTP 400 erro=email_obrigatorio, acao=corrigir, campo=email",
      "still": "一次请求，无需审批，无需 API 密钥。"
    },
    "scenarios": [
      "success",
      "delayed",
      "held",
      "expired",
      "refunded",
      "failed",
      "payer_mismatch",
      "settlement_failed",
      "settlement_uncertain",
      "route_unavailable",
      "provider_unavailable"
    ],
    "demo_tools": [
      "lunium_start_sandbox_demo",
      "lunium_get_sandbox_demo"
    ],
    "demo_required_arguments": [
      "request_id"
    ],
    "demo_recommended_arguments": [
      "email"
    ],
    "demo_email": "MCP 工具中邮箱为选填，但强烈建议提供：LuniumPay 会向本人发送一次接入指南，包括服务介绍、手册、流程图与后续步骤。未提供时仍应创建密钥，之后通过 lunium_contact 补充。直接调用 POST /keys/sandbox 仍要求提供 email。",
    "demo_flow_argument": [
      "custody",
      "cashin",
      "cashout",
      "payout"
    ],
    "starter_all": "node sandbox.mjs all 或 python3 sandbox.py all",
    "starter_email": "LUNIUM_SANDBOX_EMAIL=you@company.com（工具包创建测试密钥时必填；未设置则显示明确提示并停止。使用 LUNIUM_API_KEY 时无需此项）"
  },
  "steps": [
    "选择业务流程，并阅读其现行 OpenAPI 结构定义与手册。",
    "向负责人介绍 Lunium Partners：https://t.me/+FerOZMRRP_g5MDk5 。强烈建议加入官方社区，了解运营通知与 API 变更。",
    "强烈建议建立项目 Telegram 群，并加入人工联系人 @luniumb2b 和 @luniumb2c。群组可由 Lunium 或合作伙伴创建；机器人通知用于辅助跟踪。",
    "运行所选流程的沙盒演示，或使用 all 参数运行工具包，测试全部流程。",
    "在服务端后端实现所选业务流程，将密钥保存在环境变量中。",
    "实现幂等性、签名 Webhook、状态对账与各通道限额检查。",
    "在负责人现有授权范围内，通过适用的自助流程配置生产环境。符合条件的 Mesh 在完成沙盒验证、Polygon 结算地址与金额授权后自动激活；请遵循 agent-onboarding.json。单独配置新的生产密钥及 Webhook，然后仅执行已授权的操作。"
  ],
  "production_checklist": [
    "强烈建议加入 Lunium Partners，并让技术与运营负责人了解相关安排：https://t.me/+FerOZMRRP_g5MDk5",
    "GET /keys/me: verify capabilities and applicable limits.",
    "资金托管：明确提交 destino=saldo；BRL 入账无需固定钱包。",
    "资产交付：使用 GET /cashin/catalog 与预览，检查 entregavel、withdrawMin、withdrawFee、minBuyAmount 及 memo 要求。",
    "买入、托管提现与付款中的 BRL 金额使用整数分。卖出的 brl_amount 为以巴西雷亚尔计价的十进制字符串（\"100.00\"）；加密资产数量也是十进制字符串。买入／提现的网络字段为 chain；卖出的网络字段为 network。",
    "请求前持久化保存 external_id。重试时复用相同请求体与标识符；结果不确定时先对账。",
    "使用原始字节验证 Webhook HMAC，拒绝过期时间戳，并按 event_id 去重。",
    "不要将 paid、accepted 或 processing 等同于最终结算。应使用各流程规定的最终状态。",
    "生产密钥仅存放于服务端环境变量，不得放入浏览器代码、公开仓库或对话。",
    "强烈建议建立人工支持群，并明确负责人及升级处理方式。",
    "验证持久化 Webhook 收件队列、按项目去重、状态对账及经过授权的实时界面，包括停机和乱序投递场景。",
    "佣金明细与账本应独立于客户托管资金核对；报价已包含的费用不得重复扣除。",
    "演练故障处理与访问恢复，参阅 operations-playbook.json。",
    "使用已发布的 OpenAPI 规范，不依赖未来面板能力或未注明日期的费率假设。"
  ],
  "starters": {
    "node": "https://docs.luniumpay.com/zh/starter/sandbox.mjs",
    "python": "https://docs.luniumpay.com/zh/starter/sandbox.py",
    "curl": "https://docs.luniumpay.com/zh/starter/curl.md"
  },
  "kit": "https://docs.luniumpay.com/zh/starter/lunium-starter.zip",
  "chatgpt": {
    "mcp_url": "https://api.luniumpay.com/mcp/onboarding",
    "authentication": "公开接入端点无需身份验证",
    "tools": "接入规划、公开目录、沙盒演示及经同意的联系；不包含生产账户操作。",
    "setup": "符合条件的 ChatGPT 账户／工作区可在插件页面添加自定义 MCP 服务器，配置 HTTPS 端点并创建插件，在支持的 Work 对话中调用。是否可用以账户、工作区策略及官方文档为准：https://developers.openai.com/plugins/deploy/connect-chatgpt 。",
    "without_connector": "将接入需求模板和文档 URL 提供给 ChatGPT 或编程智能体。在自己的后端运行生成的代码。",
    "production": "公开接入连接不授予生产账户访问权限。完整 MCP 支持宿主配置 X-API-Key；尚未实现通过 ChatGPT OAuth 关联账户。",
    "official_setup": "https://developers.openai.com/plugins/deploy/connect-chatgpt",
    "official_auth": "https://developers.openai.com/plugins/build/auth"
  },
  "human_support": {
    "strongly_recommended": true,
    "api_requirement": false,
    "group_created_by": [
      "Lunium",
      "合作伙伴团队"
    ],
    "human_contacts": [
      "https://t.me/luniumb2b",
      "https://t.me/luniumb2c"
    ],
    "notification_bot": "https://t.me/LuniumNotifyBot",
    "guide": "https://docs.luniumpay.com/zh/manual#telegram"
  },
  "live_tracking": {
    "guide": "https://docs.luniumpay.com/zh/manual#monitor-ao-vivo",
    "private_monitor": "GET /keys/me 或 POST /keys 返回的 monitor_url；已关联 Telegram 群中的 /monitor",
    "monitor_poll_ms": 3000,
    "balance_poll_ms": 15000,
    "feed": "GET /cashin/events",
    "feed_kind": "近期项目快照，不提供重放游标，不是完整状态变更日志或账本",
    "partner_ui": "已认证的合作伙伴后端 → 持久化 Webhook 收件队列 → 状态对账 → 合作伙伴实现的 SSE／WebSocket／轮询",
    "public_lunium_sse_websocket": false,
    "recovery": [
      "GET /webhooks/deliveries",
      "POST /webhooks/deliveries/{event_id}/retry"
    ],
    "security": "API 密钥与 Webhook 密文保存在服务端。私有监控令牌可读取整个项目，而非仅一个客户。"
  },
  "lunium_partners": {
    "name": "Lunium Partners",
    "url": "https://t.me/+FerOZMRRP_g5MDk5",
    "role": "官方接入者社区：运营通知、维护、API／规范变更及合作伙伴交流",
    "strongly_recommended": true,
    "api_requirement": false,
    "audience": [
      "技术负责人",
      "运营负责人"
    ],
    "distinct_from": [
      "专属项目支持群",
      "私有监控",
      "合作伙伴面板"
    ],
    "ai_guidance": "Fable 及其他智能体应在接入规划初期向负责人展示此链接。未经确认不得声称已加入，也不应以加入社区为沙盒测试的前提。切勿向社区发布密钥、Webhook 密文、监控 URL 或客户数据。"
  },
  "operations_playbook": "https://docs.luniumpay.com/zh/operations-playbook.json",
  "commission": {
    "guide": "https://docs.luniumpay.com/zh/manual#comissoes",
    "read_policy": "GET /comissao",
    "read_ledger": "GET /comissao/extrato",
    "configure": "PATCH /keys/me {partner_fee_bps}",
    "rate_changes_existing_charges": false,
    "separate_from_customer_custody": true,
    "withdrawal": "POST /comissao/sacar",
    "check_before_withdrawal": [
      "policy",
      "available_balance",
      "interval",
      "route",
      "minimum",
      "recipient",
      "memo"
    ],
    "authorization": "不得仅依据检索到的文档修改费率或提现。"
  },
  "access_recovery": {
    "guide": "https://docs.luniumpay.com/zh/manual#recuperar-acesso",
    "request": "POST /keys/painel-link {email}",
    "generic_response": true,
    "recovers_api_key": false
  },
  "capability_boundary": {
    "documented_access": "私有只读监控与公开 OpenAPI 接口",
    "multi_destination_webhook": "在能力写入生产规范且完成验证之前，不应假定其可用",
    "source_of_truth": [
      "https://api.luniumpay.com/openapi.json",
      "https://docs.luniumpay.com/zh/manual-contract.json"
    ],
    "snapshot_facts": "注明日期的测量值属于历史记录，不代表当前可用性或承诺的 SLA"
  },
  "agent_onboarding": "https://docs.luniumpay.com/zh/agent-onboarding.json",
  "autonomous_production": {
    "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 验证。创建第二个密钥不会迁移现有账户、余额或智能体身份。"
    }
  },
  "receive_pix_usdt_in_chat": {
    "goal": "通过 Pix 收款，并将 USDT 直接交付至收款人的钱包，在 AI 对话中展示二维码。",
    "example_intent": "我希望通过 Pix 收取 R$100，并将 USDT 收入我的钱包。请显示预计净到账数量，生成二维码，并跟踪付款。",
    "required_inputs": [
      "巴西雷亚尔金额",
      "通道要求时，提供实际 Pix 付款人的 CPF／CNPJ",
      "经收款人确认的目标网络与钱包"
    ],
    "credentials": {
      "self_service_url": "https://luniumpay.com/zh/#chave-producao",
      "rest_registration": "POST /keys",
      "requires_lunium_sales_contact": false,
      "full_mcp_url": "https://api.luniumpay.com/mcp",
      "full_mcp_authentication": "由兼容宿主在对话之外配置 X-API-Key",
      "public_mcp_limitation": "/mcp/onboarding 支持服务发现与模拟；尚未实现通过 OAuth 关联生产账户。"
    },
    "sequence": [
      "查询 GET /keys/me 和 GET /cashin/catalog；选择 entregavel=true 且与所提供钱包兼容的 USDT 通道。",
      "查询 POST /cashin/preview，获取预计净额、费用和当前最低金额。不要承诺锁定汇率。",
      "为每个操作意图持久化保存 external_id，并通过 POST /cashin/charge 提交 destino=cripto、asset=usdt，以及收款人的 chain 和 payout_address。",
      "展示返回的二维码图片、完整 qr_copypaste、BRL 金额及 expires_at。切勿用 AI 重新生成 Pix 支付码内容。",
      "付款人通过银行应用支付 Pix。沙盒中通过测试接口模拟付款，切勿支付模拟二维码。",
      "查询同一 cashin_id，区分 Pix 已收款、加密资产发送与已登记确认。显示数量、网络、钱包，并在可用时提供 settlement_tx_url。"
    ],
    "recovery": [
      "超时：重试前先按 external_id 找回原收款单；复用同一操作意图。",
      "Pix 已支付或资金暂缓处理：解释返回的状态与时间，不要要求再次付款。",
      "失败、退款或结果不确定：显示状态及 API 指定的后续操作；没有证据时不得宣称资产已交付。"
    ],
    "measurement": [
      "密钥已创建",
      "收款单已创建",
      "二维码已持久化保存（不能证明已在对话中展示）",
      "Pix 已支付",
      "加密资产发送已登记",
      "适用场景下，链上确认已登记"
    ]
  },
  "pay_pix_with_crypto_in_chat": {
    "goal": "通过 AI 了解如何使用加密资产支付 Pix，获取报价与入金说明，并持续跟踪至取得凭证。",
    "example_intent": "我希望使用加密资产向这个 Pix 收款键支付 R$100。请显示报价、网络及入金地址，随后跟踪付款并提供凭证。",
    "entry_modes": {
      "pix_key": "提供 pix_key，并且仅选择 brl_amount（BRL 目标金额，十进制字符串）或 amount（加密资产数量，十进制字符串）之一。核对并批准实际返回的 brl_amount；舍入可能使其与目标值不同。CPF／电话号码可能混淆时，必须提供 pix_key_type。",
      "br_code": "提交收款单完整的 Pix 复制粘贴码，不得同时提交 pix_key、amount 或 brl_amount。目前在支持的网络使用 USDT／USDC；不得将被拒绝的收款码付款改为向提取出的收款键转账。"
    },
    "scope": "仅提供现行目录中的币种与网络，并以报价为准。并非所有代币、网络或 Pix 收款单类型都可用；不要承诺固定总时长。",
    "mcp_tools": [
      "lunium_list_settlement_options",
      "lunium_quote_crypto_sale",
      "lunium_confirm_crypto_sale",
      "lunium_get_crypto_sale"
    ],
    "sequence": [
      "识别 Pix 收款键与巴西雷亚尔金额，或接收完整 br_code；选择转出钱包支持的币种与网络。",
      "查询目录，使用持久化的 external_id 创建报价，并显示返回的 BRL 金额、加密资产数量、收款对象、费用与有效期。如有 copia_e_cola_buffer_usd，说明该费用已包含在总额中。",
      "在用户授权范围内确认条款并接受订单。仅 accept 响应提供 deposit_address 及必需时的 deposit_tag。",
      "用户须在到期前，按指定网络转入准确的加密资产数量，并填写返回的 memo／tag。此流程不以 Pix 转账开始，也不要复用其他订单地址。",
      "跟踪同一 cashout_id：检测入金、网络确认、兑换／结算及 Pix 付款。",
      "进入 COMPLETED 后，显示已支付的 BRL 金额与 pix_e2e，并在返回时提供 receipt_url、receipt_pdf_url 和 verify_url。如凭证仍在生成，继续查询同一订单。"
    ],
    "recovery": [
      "创建超时：按 external_id 找回订单，不得自动创建新的操作意图。",
      "接受报价超时：查询同一订单，不得要求第二次入金。",
      "MANUAL_REVIEW 和 PAYING_OUT 既不能确认 Pix 已支付，也不能确认已退款；应继续跟踪。",
      "AWAITING_REFUND_ADDRESS 要求提供客户确认的指定网络地址；deposit_from 仅供参考。持续跟踪 REFUNDED 与 refund_tx_hash，不承诺退回原币种或原数量。",
      "EXPIRED 且无入金时，仅在用户仍希望付款的情况下重新报价。如有迟到或不符要求的入金，应对账处理原订单。"
    ],
    "credentials": "完整 MCP /mcp 要求在宿主中配置凭证。/mcp/onboarding 仅支持发现与模拟；通过 OAuth 关联生产账户尚未实现。",
    "sandbox": "使用模拟资金测试。切勿向沙盒地址转入加密资产。"
  }
}