gate-pay-x402

Gate Pay x402（gate-pay-x402）

通用规则

⚠️ 停止 — 如果你的宿主在使用此技能之前提供了任何共享运行时规则，请先遵守这些规则。满足这些规则之前，不要选择或调用工具。

• 只能调用此技能中明确列出的 MCP 工具。 不得调用此处未记载的工具，即使 MCP 服务中存在此类工具。

允许使用的 Gate Pay MCP 工具名称（与实时服务端公开的名称完全一致；跳过服务端未列出的工具）：

• 读取／编排（本身不会从链上扣款；可能根据架构执行 HTTP 请求或建立会话）： x402_place_order。仅当已连接的服务端列出 x402_request 时，才可使用它（某些替代版单工具构建中会提供此工具）；根据该工具的 inputSchema，将其用于商家 HTTP 请求、处理 402，或登录 MCP Wallet。
• 会话／身份验证： x402_quick_wallet_auth（MCP Wallet／quick_wallet）。x402_gate_pay_auth（当服务端列出此工具时，用于集中式支付的 Gate Pay OAuth——请参阅该工具的描述和 inputSchema）。
• 写入／签名／支付（不可逆或涉及安全风险——支付步骤须在明确价格后取得用户明确确认）： x402_sign_payment、x402_create_signature、x402_submit_payment、x402_centralized_payment（如果服务端列出）。
• 商家发现（只读）： 可能位于与 gatepay-local-mcp 不同的 MCP 服务端上（例如远程 HTTP MCP）。当任一已连接的服务端列出此工具时，请使用其实时公开的准确名称调用目录工具（通常为 discoveryResource；如果名称不同，只能使用实时名称）。发现过程不涉及支付。如果没有任何服务端列出此工具，则只能使用用户提供的 URL／上下文——绝不可自行编造工具名称。

不要使用 Gate Exchange MCP 来替代 Gate Pay 钱包绑定，也不要用它完成第三方 x402 MCP 上的 Gate Pay x402_place_order／同一服务端 402 流程。如果用户选择了 gate_exchange 支付路径，请仅根据 Gate Exchange 流程使用 Gate Exchange MCP 工具。

未经同意不得写入： 在用户看过明确价格（报价或 402 摘要）并给出明确确认之前，不得调用任何 inputSchema 会执行签名、资金转移或集中式结算的工具，包括 x402_sign_payment、x402_create_signature + x402_submit_payment、x402_centralized_payment，以及 x402_request 中的支付步骤（如果服务端列出此工具）。一次确认必须涵盖当前支付流程中的所有写入步骤。

---

Gate Pay x402 层 — 商家发现（仅资源列表）、钱包／环境设置和支付路由。支付和钱包 x402_* 工具通常在本地 gatepay-local-mcp（stdio）上运行。发现工具可能在同一 MCP 服务端上，也可能在第二个 MCP 服务端上（例如远程 URL）——请查看宿主的工具列表，确认各个服务端公开了哪些工具。工具的参数名称、类型、必填字段和枚举值由各工具的 inputSchema 决定。如果此技能中的任何内容与 inputSchema 不一致，则在该次调用中以 inputSchema 为准。

面向用户的语言： 所有用户可见的回复均应使用用户在当前对话中使用的相同语言（例如，用户使用中文时用中文回复，使用英语时用英语回复）。

触发场景：当用户希望通过 x402 付款、发现或挑选付费服务、配置或添加 Gate Pay 钱包，或选择支付路径时使用：

• 钱包设置 / 添加 / 切换： 配置 / 设置 / 添加 / 绑定 / 更改默认支付方式、PAYMENT_METHOD_PRIORITY，以及任何语言中语义等同的表达
• 按支付通道（MCP Wallet / quick_wallet）： MCP Wallet、Quick Wallet，以及用户语言中本地化或口语化命名的同一产品、插件钱包（包括扩展程序加 Open-API-token 风格的设置）、绑定私钥、本地私钥、私钥支付、EVM_PRIVATE_KEY、PLUGIN_WALLET_TOKEN
• 支付 / 购买： 402、需要支付、帮我支付 / 购买、下单、签署支付、x402_sign_payment，以及任何语言中等同的表达
• 付费服务意图（示例，不限于字面表达）： 预订航班、订餐、购买 API、“帮我买 X”、有哪些商户、可计费或付费服务列表，以及用户所用任何语言中的等同表达
• Exchange： Gate Exchange 支付、通过 Exchange 支付

根据含义识别意图，而不只是匹配英文原文；用户经常混用多种语言或使用特定供应商的术语。

不属于此技能（常见误路由）：

• 仅涉及一般市场 / 交易、且没有 Gate Pay MCP、没有 x402、没有针对本产品的商户发现、没有针对本产品的钱包 / 环境变量设置的请求
• 纯咨询或交易决策、且没有 Gate Pay / x402 / 此 MCP 路径
• 必须仅通过非 Gate 第三方 x402 MCP 为与 Gate Pay MCP 中 x402_place_order 相同的订单完成支付的请求（违反下文的同一服务端规则）

---

领域知识

• 产品范围： Gate Pay x402：通过 gatepay-local-mcp（x402_* 工具）处理商户 HTTP 和 402；可选的商户发现功能可通过同一或另一个 MCP 提供，前提是其中列出了目录工具（参见 GatePay 商户发现）；钱包支付通道（quick_wallet、plugin_wallet、local_private_key）；用户选择了 gate_exchange 时，可选用 Gate Exchange MCP。
• 以 Schema 为准： 根据目标工具的 inputSchema 构建每个 MCP arguments 对象；如果与本文档冲突，以 inputSchema 为准（参见 Gate Pay x402 模块（MCP 工具））。
• 用户确认： 在用户看到明确价格并给予明确确认之前，不得调用签名、资金转移或结算工具（参见 GatePay 商户发现与 Agent 编排、工作流）。
• 支付通道和环境变量： PAYMENT_METHOD_PRIORITY 和 MCP env 参见 钱包配置流程和身份验证状态。

---

路由规则

根据用户意图进行路由（操作流程章节位于本文档中——钱包、发现、工作流、Exchange；不拆分到其他文件。QA 场景位于 references/scenarios.md；该文件不是运行时路由子模块）：

用户意图	关键词 / 信号	目标
钱包 / 环境变量配置	钱包设置、添加支付通道、MCP Wallet、Quick Wallet、快捷钱包、gate/Gate钱包、本地化名称、插件钱包、私钥、PAYMENT_METHOD_PRIORITY、MCP 主机环境变量——匹配任何语言中的意图	本文档——钱包配置流程，然后是身份验证状态
商户发现 / 选择 / 报价	有哪些商户、付费服务列表、有哪些付费服务、选择服务、报价 / 动态价格、支付前发现——以及其他语言中的等同表达	本文档——GatePay 商户发现与 Agent 编排，然后是工作流
x402 支付（Gate Pay MCP）	支付、402、下单、x402_place_order、x402_sign_payment，以及（如已列出）x402_request——以及其他语言中的等同表达	本文档——工作流
Gate Exchange 支付	exchange、Gate Exchange——以及其他语言中的等同表达	本文档——Gate Exchange 路径
MCP 连接	找不到 MCP、未找到工具、需要添加发现或本地支付服务	本文档——MCP 主机设置（发现 + 支付），然后是MCP 服务连接检测

---

GatePay 商家发现与 Agent 编排

一句话意图： 当用户用自然语言说明想要哪项付费服务时，Agent 发现商家 → 按规则选择资源 → 商家支持时进行报价 → 填写所需的调用参数 → 调用服务 → 显示明确价格后，征求用户明确的付款同意 → 只有在此之后才运行签名／付款工具。钱包通道（quick_wallet、plugin_wallet、local_private_key、gate_exchange）遵循钱包配置流程和身份验证状态。

范围与边界

• 商家发现层仅返回可调用的资源列表。它不会收款、不会下单，也不会进行链上结算。
• 订单／HTTP／402 使用支付 MCP 上的 x402_place_order 和／或 x402_request（以及相关的 x402_*）——通常是 gatepay-local-mcp。所有参数都来自该工具的 inputSchema。
• 两个 MCP（常见情况）： (1) 发现 MCP — 仅公开目录工具的远程服务或独立进程。(2) 支付 MCP — npx -y gatepay-local-mcp（stdio），公开 x402_*。Agent 必须在列出相应工具的服务上调用该工具；不要假设发现和支付共用一个连接。
• 注册表／发现 HTTP API（如果 MCP 后方存在）属于实现细节：使用 MCP 工具和响应；此处不要重复列出发现负载字段表——列表项的结构以 MCP 返回的内容为准，并根据 inputSchema 进行验证。

商家发现 MCP 工具（已列出时）

• 使用哪个服务： 扫描所有已配置的 MCP 服务。目录工具可能只出现在发现服务上（而不在 gatepay-local-mcp 上）。
• 预期工具名称： discoveryResource — 必须与公开发现功能的服务上实时工具列表中的名称一致。如果已发布的名称不同，则仅使用实时列表中的名称。
• 行为： 仅返回分页的可调用资源列表（HTTP 和／或 MCP 类型条目，包含 accepts 及可选的报价元数据）。此工具不付款，也不下单。
• 参数（逻辑字段名称——根据实时的 inputSchema 组合参数值；如有任何不一致，以 inputSchema 为准）：

  字段	必填	说明
  resourceDes	是	用于模糊匹配目录的用户意图／服务描述（自然语言或关键词）。
  resourceType	是	http 或 mcp（设计默认值为 mcp）。
  pageNum	否	页码索引；设计默认值为 1。
  pageSize	否	每页条目数；设计默认值为 10。
  tenantId	否	租户 ID；设计默认值为 GATE_PAY；如果 schema 未公开此字段，则省略。

• 响应映射： 条目通常包含端点标识和 accepts（其中包含 HTTP 方法、标头、正文的 outputSchema / input，或 MCP 的 tool + inputSchema + transport）。可选的 metadata：用于动态定价的 quote_endpoint、quote_method、pricing_mode、quote_inputSchema / inputSchema——用于确定上述报价与主调用顺序。字段名称可能因层而异，显示为 resourceUrl 或 resource；始终遵循工具的实际响应，并根据 x402_place_order / x402_request 的 inputSchema 进行映射。
• 如果工具未列出： 跳过发现调用；依赖用户提供的 URL 和对话上下文。

discoveryResource 必须调用的情况（在商家 HTTP 调用之前）

当某个已连接的 MCP 服务列出了发现目录工具（通常名为 discoveryResource——请使用该服务工具列表中的确切名称），且以下条件全部成立时：

1. 用户用自然语言表达了对商品或服务的购买或下单意图（例如“帮我买一双鞋”“订一杯咖啡”“买一个查天气的 API”）——包括用其他语言或口语化表达的相同意图。
2. 用户消息加上对话上下文，仍不足以满足支付 MCP 上商家 HTTP 工具 x402_place_order 或 x402_request 的 inputSchema（通常缺少或未完整提供 url / method / body 或其他等效必填字段），且不能凭空编造端点或参数。

那么，Agent 必须先在列出该工具的服务上调用发现工具——arguments 只能依据该工具的 inputSchema 构建（通常将用户的表述映射到 resourceDes，并按 schema 设置 resourceType，例如默认设为 mcp）。然后应用选择规则，再从支付 MCP 上的工作流第 3–4 步继续，并使用选定的资源。不要通过猜测商家 URL，或使用空白、占位或臆造的商家目标调用 x402_place_order / x402_request，来跳过发现步骤。

以下情况不要执行此强制目录步骤：没有已连接的服务列出发现工具（仅使用用户提供的 URL / 上下文）；用户已经提供了具体商家端点和足以满足 HTTP 工具 schema 的参数；会话仅涉及钱包 / 支付轨道设置，不包含购买流程；或用户仅选择了 gate_exchange（Gate Exchange 路径）。

选择规则（筛选 → 排序 → 决胜）

按顺序应用；先筛选，再对剩余选项排序；如果有多个选项仍然接近，询问用户，不要默默替用户选择。

1. 意图匹配：description、类型和能力与用户目标相符（例如航班、餐饮或 API）。
2. **约束：**网络、货币、maxPrice、用户明确提出的预算——剔除不符合条件的资源。
3. **可调用性：**当前环境能否满足所需的 MCP 传输方式和／或 HTTP 要求；若不能，则剔除该选项或说明限制。
4. 参数可行性：根据用户已提供的信息，能否填写必填输入（依据商家 inputSchema）？若资源需要未知的关键字段且没有安全的默认值，不要选择该资源；或者选择最容易补全的选项，并询问缺失字段。
5. **价格路径：**如果用户坚持在决定前了解价格，优先选择提供 报价／动态元数据的资源；否则，在同等合适的选项中，优先选择固定价格或流程更简单的路径。
6. **决胜：**如果多个资源仍然同样合适，说明差异（价格区间、延迟、限制），并请用户选择（例如按编号选择）。绝不要在用户未选择的情况下自动挑选。

报价与主要调用的顺序

• 如果发现项或 schema／元数据表明存在报价／动态定价（例如 MCP 文档中的 dynamic、quote_endpoint 或等效字段）：先获取报价 → 向用户展示货币、金额和条件 → 询问是否继续使用该商家 → 用户同意后，再使用相应参数调用主要服务。
• 如果没有报价路径：不要臆造单独的报价步骤；按约定调用主要服务。如果费用只在 402 中出现，则解析 402，然后执行下方的强制支付确认。
• 没有报价路径不代表可以跳过支付确认。

参数、价格可见性和强制付款确认

• 参数： 调用任何商家工具 / x402_place_order 之前（如果支付 MCP 列出的 HTTP/402 工具是 x402_request，则调用它之前），先列出相关 inputSchema 中的必填字段。如果用户尚未提供这些字段，通过对话补全。不要使用空值或猜测的值调用工具来“探测”API。
• 价格可见性： 对于报价流程，显示币种、金额和适用范围。没有报价时，在收到 402 或商家明确给出价格后，用用户使用的语言概述付款要求。
• 付款确认（强制）： 用户必须先看到明确的价格（报价结果或 402 概述）。然后 Agent 必须再次询问；消息应说明金额、资产 / 链（如果已知）以及付款方式（如果已知）。仅在用户明确同意（例如“确认付款”“继续付款”）后，才调用 x402_sign_payment、分拆的签名工具，或进一步执行 x402_request 中的步骤，且仅当支付 MCP 列出了该工具时。如果用户拒绝或不确定，则停止付款；提供其他商家选项或结束流程。
• 步骤 1（工作流）： “余额 / 意图”检查可与此先展示价格、再确认步骤合并，以避免重复询问；价格明确后，优先进行一次清晰的确认。

将发现结果映射到步骤 4

• x402_place_order 的 url / method / body（或者当服务器将 x402_request 列为 HTTP 工具时使用的参数）来自用户消息、对话上下文或上游发现结果（资源标识、MCP 响应中的 outputSchema 或同等信息）。将字段名称映射到工具 inputSchema 要求的字段。

与工作流保持一致

• 步骤 4 仍通过 x402_place_order 处理商家 HTTP 请求和 402，或者在服务器列出 x402_request 时使用该工具。
• 步骤 5–6（需要时登录 MCP Wallet，使用签名 / 付款工具）：仅在完成上述强制付款确认后运行（如果确认步骤已合并，则可在首次扣款 / 签名前立即运行，但不得早于用户看到明确价格并同意）。
• 同一服务器规则（付款）： 对于一个商家订单 / 一个 402 挑战，所有 x402_* 步骤（下单、签名、提交、付款授权）都使用同一个支付 MCP 服务器 ID（通常为 gatepay-local-mcp）。发现可以在不同的服务器 ID 上调用；这不违反此规则——只有 x402_* 必须在该订单中始终使用同一个支付服务器。

钱包和支付渠道（产品规则）

这些规则优先于本文件中其他冲突的旧表述，但工具的 inputSchema 要求某个字段（例如 URL 参数）的情况除外：此时以 inputSchema 为准，并根据 schema 和供应商文档提供值。

1. plugin_wallet：用户仅在 MCP env 中配置 PLUGIN_WALLET_TOKEN（完整令牌绝不出现在聊天中）。不要将 PLUGIN_WALLET_SERVER_URL 作为默认规则要求用户在 env 中配置；实现可以使用内置端点。如果 inputSchema 仍要求调用时提供 URL（或类似字段），请按 schema／文档填写，不要因此违反必填字段要求。
2. quick_wallet（MCP Wallet）：****不要要求配置 MCP_WALLET_API_KEY、MCP_WALLET_URL 或类似的“quick wallet API URL”环境变量。会话通过工具驱动的登录建立（根据 schema，使用 x402_quick_wallet_auth，或在该版本中使用 x402_request 登录）；成功后，按第 1 节（MCP Wallet）的说明更新 PAYMENT_METHOD_PRIORITY。
3. 支付失败和支付渠道切换：仅使用已实际配置且可用的支付渠道（PAYMENT_METHOD_PRIORITY + env + 登录状态）。如果仅配置了 plugin_wallet 且其调用失败：不要启动 quick_wallet 登录／认证，除非 quick_wallet 已配置且用户明确同意切换。如果没有下一个支付渠道，请说明失败原因，建议检查令牌／插件配置，不要凭空编造其他支付方式。如果配置了多个支付渠道，失败时可以尝试下一个已配置的支付渠道；切换前最好先简要征求用户意见（除非产品明确允许纯技术重试的例外情况）。

硬性停止条件（不完全列举）

• 发现结果中没有可用选项，且无法放宽约束 → 停止或放宽约束后重试；不要伪造商家。
• 缺少必需参数 → 不要调用商家或支付工具。
• 用户看过价格后尚未明确同意付款 → 不要调用签名或支付工具。
• 仅配置了插件且插件调用失败 → 不要自动启动未配置的 quick_wallet。

---

MCP 主机设置（发现 + 支付）

许多部署使用两个 MCP 条目：

角色	常见传输方式	用途
Payment MCP	stdio — npx -y gatepay-local-mcp	x402_place_order、x402_request、x402_sign_payment、x402_quick_wallet_auth、其他 x402_*；钱包的 env（PAYMENT_METHOD_PRIORITY、EVM_PRIVATE_KEY、PLUGIN_WALLET_TOKEN，等等）放在此处。
Discovery MCP（可选）	HTTP 远程 URL（因主机而异）	可付款商家的目录（工具名称通常为 discoveryResource — 请在当前工具列表中确认）。不能替代支付工具。

将两者合并到主机的 MCP 服务映射中，不要移除无关的 MCP。编辑后请重新加载 MCP或重启应用。

示例：mcp.json 片段（Cursor 风格的主机）

项目级：<project>/.cursor/mcp.json。用户级：~/.cursor/mcp.json。位于 mcpServers 下：

{
  "gatepay-merchant-discovery": {
    "url": "https://openplatform.gateapi.io/pay-mcp-server/mcp"
  },
  "gatepay-local-mcp": {
    "command": "npx",
    "args": ["-y", "gatepay-local-mcp"],
    "env": {}
  }
}

• 键名（gatepay-merchant-discovery、gatepay-local-mcp）可以重命名；在会话期间请保持稳定，这样 Agent 才能为每个工具指定正确的服务。
• 如果主机要求使用其他形式配置远程 MCP（headers、transport、SSE），请遵循当前主机文档——关键是在产品采用发现与本地支付分离的方式时，将两个端点都注册进去。
• 机密信息只能放在 gatepay-local-mcp 的 env 中（绝不放在聊天中）。

---

MCP 服务连接检测

在首次调用 Gate Pay x402_* 工具进行支付或 MCP Wallet 认证之前，以及在流程需要目录时进行强制商家发现之前，请运行以下探测（如果用户仅收到第 0.A 节且尚未选择支付渠道，则跳过）。

A. 支付 MCP（x402 支付 / 钱包授权所必需）

1. 扫描已配置的服务，查找至少一个名称以 x402_ 开头的工具（例如 x402_place_order、x402_sign_payment、x402_quick_wallet_auth）。某些构建版本会将 x402_request 作为主要 HTTP/登录工具，而不是使用 x402_place_order，或与其同时提供。
2. 记录该主机的服务密钥，作为支付服务 ID（例如 gatepay-local-mcp）。
3. 验证工具列表中包含 x402_place_order、x402_request 或其他有文档说明的、用于商户 HTTP/402 的 x402_* 条目。

结果	操作
成功	在本次会话的同一订单流程中，所有 x402_* 调用都使用此支付服务 ID。
失败	显示下方的设置指南 — 支付 MCP；不要猜测支付参数。

B. 发现 MCP（仅在必须进行发现时需要）

1. 扫描所有已配置的服务（包括支付服务以外的服务），查找目录工具——通常是 discoveryResource；使用实时列表中的确切名称。
2. 如果存在，记录该服务密钥，作为发现服务 ID（例如 gatepay-merchant-discovery）。
3. 如果用户的购买流程需要目录（当 discoveryResource 为必需项时），但没有任何服务列出发现工具 → 显示下方的设置指南 — 发现 MCP。

结果	操作
找到目录工具	仅在发现服务 ID 上调用发现工具；将结果映射到支付服务 ID 上的 x402_place_order / x402_request。
缺少目录工具，但必需	用户必须添加发现 MCP，或手动提供商户 URL/参数。
不需要目录	跳过；用户已提供足够的商户字段，或当前会话仅涉及钱包 / Exchange。

设置指南 — 支付 MCP（当 A 失败时，每个会话最多显示一次）：

Payment MCP (gatepay-local-mcp)
  - Add a stdio server: command "npx", args ["-y", "gatepay-local-mcp"], env { } (add PAYMENT_METHOD_PRIORITY / EVM_PRIVATE_KEY / PLUGIN_WALLET_TOKEN only when that rail is used — full secrets never in chat).
  - Cursor-style: merge into .cursor/mcp.json under mcpServers; reload MCP or restart the IDE.
  - Other hosts: register the same stdio command per product docs (VS Code MCP, Claude Code, OpenClaw, etc.).

设置指南 — 发现 MCP（当需要 B 但缺少相应工具时，每个会话最多显示一次）：

Discovery MCP (example id: gatepay-merchant-discovery)
  - Add a remote MCP entry with your vendor URL, e.g. "url": "https://openplatform.gateapi.io/pay-mcp-server/mcp" (confirm exact URL and transport with your deployment).
  - Merge into the same mcpServers object as the payment MCP; reload MCP.
  - After reload, confirm the catalog tool appears (name may be discoveryResource or differ — use the live tool list).

---

钱包配置流程

当用户想要为 Gate Pay MCP配置、添加或更换支付钱包时，请遵循此流程。任何 MCP 工具的参数都来自该工具的 inputSchema。

0. 入口

0.A 意图模糊——仅限首次回复（面向用户）

如果用户只要求配置或添加钱包（例如“帮我设置钱包”“配置钱包”），没有指定具体支付方式，本轮回复必须简短易懂。使用与用户相同的语言（见上文的面向用户的语言）。

1. 提供三个选项——每个选项用通俗语言说明：它是什么、适合谁、大致需要做什么——每个选项总共用一到两句话。清晰区分这三种方式（浏览器／设备登录 vs 扩展／Open API 方式 vs 在本机保存密钥）：

   • MCP Wallet（本地化名称：Quick Wallet、快捷钱包、gate钱包 / Gate钱包）：通过浏览器或设备流程使用 Gate 登录（类似登录应用）；适合不想安装扩展且能接受托管式登录的用户。用户选择后，你将通过 MCP 工具完成登录和支付订单。
   • 插件钱包：使用 Gate 浏览器扩展和 Open API 风格的令牌，并将令牌保存在本地应用设置中——适合已在使用 Gate 扩展且希望由插件授权支付的用户。用户选择后，你将引导他们从插件端获取令牌，并仅将其粘贴到本地配置中，而不是随意粘贴到网站。
   • 私钥（本地签名）：他们将自己的 EVM 私钥放入本地配置，MCP 会在这台机器上进行签名——适合高级用户，他们需要完全控制密钥并接受处理原始密钥材料。用户选择后，你要告知他们只填写本地配置，绝不要在聊天中输入密钥。

2. 在这条首次消息中，不得包含： env 键名（例如 EVM_PRIVATE_KEY、PLUGIN_WALLET_*、PAYMENT_METHOD_PRIORITY）、MCP 工具名称（例如 x402_quick_wallet_auth、x402_place_order）、枚举值（quick_wallet、plugin_wallet）、如何编辑 mcp.json（或其他路径），或分步技术操作。待用户选择后再说明这些内容（第 0.B 节 → 第 1–3 节）。

3. 语气：****不要提供冗长的清单、不要审查 env、不要进行长篇安全说教。最多用一句简短说明，例如：“你选好后，我会一步步带你完成后续操作。”

4. 如果该 MCP 支持，也可以用一句话介绍 Gate Exchange 支付。

5. 结尾请用户选择一个选项（说出名称或编号）。等待用户选择（除非他们已在同一条首次消息中指定支付方式）。

0.B 用户选择之后（或已指定支付方式）

继续执行第 1–3 节 / 第 5 节——此时你可以按这些章节的说明使用 env 键、工具名称、PAYMENT_METHOD_PRIORITY 和编辑文件。对于 MCP Wallet，运行 MCP 服务器连接检测并记录服务器标识符。

1. MCP Wallet（quick_wallet）

MCP Wallet 是一种产品支付渠道；本地化名称（例如 “Quick Wallet”）指的是同一种支付方式。MCP 枚举值／env 令牌仍为 quick_wallet——按照 inputSchema，在 PAYMENT_METHOD_PRIORITY 和 sign_mode（或等效字段）中使用该值。

此支付方式不需要用户 API 密钥：MCP Wallet 不使用 MCP_WALLET_API_KEY，不会要求用户申请或粘贴“quick wallet API 密钥”，也不同于插件钱包的 Open API 令牌。凭据来自工具驱动的登录（设备／OAuth 流程）；实现可能会在本地持久化会话数据（例如存储在 ~/.gate-pay/ 下）——请遵循工具响应，而不是根据聊天内容猜测。

顺序：先通过工具完成身份验证，成功后再设置 PAYMENT_METHOD_PRIORITY。在 MCP Wallet 登录根据你实际使用的工具（见下文）成功之前，不要写入或合并 PAYMENT_METHOD_PRIORITY。 错误流程（MCP Wallet）： 不要将设置 MCP_WALLET_API_KEY、MCP_WALLET_URL、通用 API 密钥或 EVM_PRIVATE_KEY 作为使用此支付通道的前提条件。不要将 MCP Wallet 与 plugin_wallet 令牌设置混为一谈。

应调用哪个工具（读取实时 MCP 工具列表）：

• 如果存在 x402_quick_wallet_auth → 优先使用它；从 inputSchema 获取 arguments（例如可选的 wallet_login_provider：gate | google）。
• 如果不存在 x402_quick_wallet_auth，但列表中有 x402_request，且其 inputSchema 支持 MCP Wallet 登录 → 使用 x402_request 触发登录，并传入 quick_wallet 对应的字段（例如：sign_mode 为 quick_wallet，以及任何必需的 wallet_login_provider / URL 参数）。仍然不需要用户提供 API 密钥——遵循相同的先认证规则；只有成功后才更新 PAYMENT_METHOD_PRIORITY。（常见的单工具版 npm gatepay-local-mcp 构建通常只会为 HTTP 和 MCP Wallet 登录列出 x402_request——但仍然仅限该工具已列出时。）
• 如果用户选择了 centralized_payment，且列表中有 x402_gate_pay_auth → 按照该工具的说明和 inputSchema 完成 Gate Pay OAuth（与 MCP Wallet 登录分开）。

定义——已配置： 只有在登录 / 设备流程成功完成（工具响应为成功 / 就绪）后，MCP Wallet 才算完全配置完成。登录失败或中途放弃 → 不要更新 PAYMENT_METHOD_PRIORITY。

1. 首先——MCP 工具： 按照上方的应调用哪个工具，在支付 MCP 上调用 x402_quick_wallet_auth；或者当列表中有 x402_request 且根据其 schema 用于 quick_wallet 登录时调用该工具（参见 MCP Server Connection Detection §A）。引导用户完成 MCP Wallet 登录，直到工具显示成功 / 就绪。
2. 如果登录成功（根据工具响应，已建立会话）：然后编辑 MCP env：
   • 将 quick_wallet 添加到 PAYMENT_METHOD_PRIORITY（如果已有列表，则与现有列表合并）。
   • 如果之前 PAYMENT_METHOD_PRIORITY 中没有其他支付通道，可根据用户在 Section 0.B 中表达的意图，将 quick_wallet 设为唯一或第一项。
   • 如果之前 PAYMENT_METHOD_PRIORITY 中已有一个或多个其他支付通道，则明确询问用户是否要将 quick_wallet 设为新的默认项（移至最前）。只有用户同意时才将其移到第一位；如果用户不同意，则将 quick_wallet 追加到末尾，不更改当前第一项（未经确认不得重新排序——参见 Section 4）。
3. 如果认证 / 登录失败（出错、超时、用户取消、未就绪）：不要更改 PAYMENT_METHOD_PRIORITY，也不要添加 quick_wallet。说明后续步骤；用户可以重试。
4. 成功写入配置后，如有需要，提醒用户重新加载 MCP / 重启宿主。
5. 披露 MCP Wallet 登录后的工具输出：
   • 私钥 / 种子 / 导出的签名密钥： 绝不要在聊天中粘贴完整内容。将其打印到集成终端（stdout），确保在 macOS、Windows 和 Linux 上均可使用：优先使用 node -e / node -p 或 python -c 打印 JSON 安全或纯文本行；如果 PATH 中没有这两种运行时，则在项目下写入一个临时文件（位于 gitignored 路径），并运行命令将文件路径或内容打印到终端，然后在聊天中用用户的语言告诉他们打开 Terminal 面板并从中复制——仍然不要在聊天中发送密钥。
   • 公开的存款地址 / 钱包地址（非敏感标识符）：可以在聊天中完整显示或概述，使用用户的语言，并附上用户需要的简要说明。
   • 其他较长或包含混合内容的响应： 在聊天中删除或遮盖密钥；只有在终端 / 临时文件中提供完整的私密材料，按上述方式处理；地址仍可在聊天中显示。
6. 遵守安全规则。

2. 插件钱包（plugin_wallet）

1. PLUGIN_WALLET_TOKEN： 遵循 GatePay 商家发现与 Agent 编排中钱包与支付通道的 plugin_wallet 规则（令牌仅放在 env 中，绝不在聊天中发送完整令牌）。**PLUGIN_WALLET_SERVER_URL：**可选，具体取决于产品默认值；如果某个工具调用的 inputSchema 要求提供 URL，请根据架构／供应商文档设置。
2. PAYMENT_METHOD_PRIORITY：添加 plugin_wallet。如果这是第二个或后续支付通道，询问是否要将 plugin_wallet 设为默认（放在列表首位）。仅当用户确认是时，才将其移到首位；否则追加该支付通道，不更改当前默认项。
3. 此支付通道不使用 x402_quick_wallet_auth。
4. 提醒用户在更改 env 后重新加载 MCP。

3. 私钥／本地签名（local_private_key）

1. 在 env 中，确保存在用于本地签名的 EVM_PRIVATE_KEY。在共享仓库中使用占位符；用户只能在本地 MCP 配置中填写真实值。绝不在聊天中收集或重复任何私钥。
2. 添加 MCP 软件包文档要求的任何 RPC_URL（或等效）变量。
3. PAYMENT_METHOD_PRIORITY：添加 local_private_key。如果这是第二个或后续支付通道，询问是否要将 local_private_key 设为默认。仅当用户确认是时，才将其移到首位。
4. 除非用户也在使用 MCP Wallet（quick_wallet），否则此支付通道不使用 x402_quick_wallet_auth。
5. 提醒用户在更改 env 后重新加载 MCP。

4. 添加第二个支付通道或更改默认项

1. 用户绑定第二个或更多支付通道时，绝不能在用户明确选择前更改 PAYMENT_METHOD_PRIORITY 中的第一个令牌（当前默认项）。
2. 始终使用用户的语言提出明确的是／否（或二选一）问题，例如：“要将 <rail> 设为默认支付方式吗？”仅当用户回答是时，才将该支付通道的令牌移到首位。如果回答否，则追加新支付通道或按需保持现有顺序，不得将其设为默认项。
3. MCP Wallet（quick_wallet）：在更改 PAYMENT_METHOD_PRIORITY 以添加 quick_wallet 之前，仍须先完成身份验证（第 1 节）；登录成功后，如果已存在其他支付通道，则应用同一条须经用户确认的规则，确定是否将 quick_wallet 设为默认项。
4. 重新排列已在列表中的支付通道（用户只想切换默认项）时，编辑首位令牌前仍须获得用户明确确认。

5. Gate Exchange（gate_exchange）

如果用户配置的是仅使用 Exchange 进行支付，请确保单独注册 Gate Exchange MCP；如果预期使用的支付通道是 gate_exchange，则将其加入 PAYMENT_METHOD_PRIORITY。支付工具仅在 Exchange MCP 上提供，请在那里查看每个工具的 inputSchema。

认证状态

支付和签名使用用户实际配置的钱包通道。Gate Pay MCP env 从宿主的 MCP 配置中读取（路径和格式取决于 Cursor、VS Code、Claude Code 等，而非在此处硬编码）。

• PAYMENT_METHOD_PRIORITY：如果在 env 中设置，则以逗号分隔；第一个标记 = 默认通道。标记：quick_wallet、plugin_wallet、local_private_key、gate_exchange。如果未设置，则仅根据非空环境变量键 / MCP 会话推断通道，或询问用户。
• local_private_key：仅当用户选择此通道时使用：必须在 env 中设置 EVM_PRIVATE_KEY（以及 MCP 文档中列出的任何 RPC 变量）——绝不要在聊天中收集私钥。如果为空，则此通道不可用。
• quick_wallet（MCP Wallet）：设置 = 通过工具身份验证成功登录（第 1 节：如果存在 x402_quick_wallet_auth，则使用该工具；否则，当 x402_request 已列出且其 schema 支持 MCP Wallet 登录时使用该工具）。用户无需设置 MCP_WALLET_API_KEY。先完成身份验证，再写入 PAYMENT_METHOD_PRIORITY；如果失败，不要更改该 env。**支付：**工作流第 5 步；过期时，先进行一次身份验证，然后重试一次签名。
• plugin_wallet：在 env 中设置 PLUGIN_WALLET_TOKEN；默认情况下，用户无需设置 PLUGIN_WALLET_SERVER_URL（参见钱包和通道）。如果 inputSchema 要求提供 URL 参数，则按 schema 要求提供。如果缺少令牌，则此通道不可用。
• gate_exchange：单独配置 Gate Exchange MCP；仅当该 MCP 存在且用户选择此通道时，才路由到该 MCP。

添加第二个或更多支付通道时，询问用户是否应将默认通道切换为新绑定的通道。在用户明确同意更改默认通道之前，不要调整 PAYMENT_METHOD_PRIORITY 的顺序。

---

Gate Pay x402 模块（MCP 工具）

如何构建 arguments（必须遵守）

在此流程中，每次调用 MCP 工具之前：

1. 在正确的服务上按确切名称查找工具：发现工具位于发现服务 ID（如有）上；所有 x402_* 工具位于支付服务 ID 上（参见MCP 服务连接检测）。
2. 阅读该工具的 inputSchema：properties、required、enum、description。
3. 仅根据该 schema 和允许的运行时值（用户消息、上下文、先前的工具输出）组装 arguments。

不要复制此 Skill 中的参数表；MCP inputSchema 是事实依据。**如果此文件与 inputSchema 有任何冲突 → 遵循 inputSchema。**如果 MCP 未连接且无法获取 schema，请先完成 MCP 设置，或查阅供应商文档。

工具（在 MCP 中查找名称）

商家发现： 在任何服务器上列出时，使用 discoveryResource（或该服务器上完全一致的名称）及其 inputSchema。在发现服务器上调用，而不是在支付服务器上调用，除非两个工具都在同一服务器上列出。如果任何地方都没有列出，则跳过发现调用。

工具	分类	副作用级别	用途	参数
discoveryResource	读取（列表）	无（不支付）	GatePay 目录搜索——仅返回可调用资源 + 元数据（不支付／下单）	resourceDes、resourceType（http|mcp）、可选的 pageNum、pageSize、tenantId——参见实时 inputSchema
x402_place_order	读取 / HTTP	仅商家 I/O；后续工具才会签名	发送商家 HTTP 请求；读取状态、标头、正文	参见 x402_place_order 的 MCP inputSchema
x402_request	混合	用于 HTTP／登录时为低；当架构驱动组合签名／支付时为高——任何支付前仍需征得同意	仅在列出时使用——某些版本使用此工具处理 HTTP + 402 + 可选签名，和／或通过 quick_wallet / sign_mode 进行 MCP Wallet 登录	参见 x402_request 的 MCP inputSchema
x402_quick_wallet_auth	写入（会话）	建立钱包会话	MCP Wallet 设备／OAuth 认证（quick_wallet 通道）	参见 x402_quick_wallet_auth 的 MCP inputSchema
x402_gate_pay_auth	写入（会话）	用于集中支付的 OAuth 会话	用户使用 centralized_payment 时的 Gate Pay OAuth（根据工具文档，提交时使用 Bearer 令牌）	参见 x402_gate_pay_auth 的 MCP inputSchema
x402_sign_payment	写入（支付）	高——签署并提交支付	解析 402、签名、提交支付（一步完成）	参见 x402_sign_payment 的 MCP inputSchema
x402_create_signature	写入（签名）	高——生成签名材料	仅创建已签名载荷／编码后的签名	参见 x402_create_signature 的 MCP inputSchema
x402_submit_payment	写入（支付）	高——提交支付	使用签名提交支付（拆分流程）	参见 x402_submit_payment 的 MCP inputSchema
x402_centralized_payment	写入（支付）	高——当服务器提供此工具时，用于集中结算	根据 MCP 使用账户中心／集中支付流程（如有列出）	参见 x402_centralized_payment 的 MCP inputSchema

商家的 url / method / body 来自用户消息、对话上下文或上游发现（资源／outputSchema／MCP 发现响应——根据 inputSchema 进行映射）；将字段名映射为架构要求的名称（仅限已连接服务器上列出的 x402_place_order 和／或 x402_request）。

执行工作流

将用户意图映射为参数提取 → MCP 连接探测（步骤 0）→ 预检（inputSchema 必填字段、环境通道）→ 工具调用 → 面向用户的摘要：

1. 提取用户及上下文中的商家 URL／方法／正文或发现条件。如果适用**discoveryResource 必须调用**，则在支付 MCP 上进行任何 x402_place_order / x402_request 调用之前，先在发现 MCP 上调用发现工具，然后根据选定的目录项推导步骤 4 的字段。
2. 根据 MCP Server Connection Detection 和 Authentication State 进行预检；如果用户正在设置通道，则完成 Wallet configuration procedure。
3. 按 Workflow 中的顺序调用工具；每次调用之前，根据该工具的 inputSchema 重新构建 arguments。
4. 按 Report Template 输出；失败时使用 Error handling。

工作流

x402 支付流程

Step 0: MCP detection (once per session) — payment MCP (§A) + discovery MCP (§B) when catalog is required — see **MCP Server Connection Detection**
  |
Step 1: Payment intent checks — PAYMENT_METHOD_PRIORITY + env + user balance acknowledgment (user-confirmed)
  |
Step 2: Choose rail
  |- gate_exchange -> Gate Exchange MCP tools only (read each tool's inputSchema there)
  +- Gate Pay x402 -> Continue
  |
Step 3: Before each **`x402_*`** tool call on the **payment MCP** -> read that tool's inputSchema and build arguments
  |
Step 4: Merchant HTTP + 402 on **payment MCP**: `x402_place_order` **or** (if listed) `x402_request` — per live tool list and schema
  |- Non-402 -> handle per merchant rules
  +- 402 -> extract payment challenge from response per MCP/tool docs (e.g. headers); keep url/method/body for retry
  |
Step 5: If MCP Wallet (`quick_wallet`) -> before sign: `x402_quick_wallet_auth` **if listed**, else (if listed) satisfy login via `x402_request` per schema (e.g. `sign_mode`); on expiry -> same auth once then retry sign once (per product limits)
  |
Step 6: x402_sign_payment (default) OR x402_create_signature -> x402_submit_payment (split); **or** if `x402_request` is listed: further `x402_request` calls per schema for sign/pay
         For each step: arguments strictly from that tool's inputSchema; wire outputs only as schema/response shapes allow
  |
Step 7: Summarize success to the user in their language; **addresses** may be in chat; **private keys** only via terminal/temp-file flow per **Safety Rules** and **Wallet configuration procedure** Section 1 step 5

发现与支付确认： 目录：如果适用必须使用 discoveryResource，请先在发现服务上调用目录工具 → 选择资源 → 在支付 MCP 上从第 3–4 步继续。如果用户已按架构提供足够的商户 HTTP 字段，则跳过目录。如果没有任何服务列出发现工具，则跳过目录（仅使用用户提供的网址/上下文），除非用户必须根据设置指南 — 发现 MCP添加发现 MCP。支付同意：用户看到明确价格（报价或 402 摘要）后，在第 5–6 步之前取得明确的支付同意（必要时与第 1 步合并，以免重复询问）。完整规则：GatePay 商户发现与 Agent 编排。

同一服务规则：同一商户订单 / 402 挑战的所有 x402_* 步骤都必须使用相同的支付 MCP 服务 ID。发现可以使用不同的服务 ID。

判断逻辑摘要

• 使用路由规则选择本文中的小节（钱包设置、发现、x402 支付、Exchange、MCP 连接）。
• 必须时先发现：如果（任一服务上）列出了发现目录工具，且用户要购买/下单，但未提供足以满足 inputSchema 的商户 HTTP 参数，则在支付服务上调用 x402_place_order / x402_request 之前，先在该发现工具所在的服务上调用它 — 参见必须使用 discoveryResource 的情形。
• **以架构为准：**每个 MCP arguments 对象都必须符合目标工具的 inputSchema；若有冲突，以 inputSchema 为准。
• 写入前取得同意：在获得明确价格和用户明确确认之前，不得调用签名、提交或集中式支付工具；用户确认必须涵盖流程中的所有写入步骤（参见一般规则和安全规则）。
• 同一服务（支付）：一个 402 挑战 → 所有相关 x402_* 调用使用一个支付 MCP 服务 ID（发现可使用其他服务）。
• 支付通道：仅在第 4 节规定的范围内切换或添加默认的 PAYMENT_METHOD_PRIORITY（需用户明确选择）。

回复模板

完成钱包设置或支付后，使用用户的语言回复：

• **结果：**成功、失败、已取消或受阻（说明原因）。
• **金额 / 资产 / 链：**仅当 MCP 或商户返回了这些信息时才提供；切勿编造数值。
• **参考信息：**仅在工具输出中存在时提供（ID、哈希）。
• **后续步骤：**重试、更换支付通道、重新加载 MCP 或结束 — 不得捏造订单或支付状态。

场景

面向 QA 的上下文 / 提示词示例 / 预期行为模板位于 references/scenarios.md。

错误处理

情况	建议操作
MCP 超时 / 传输错误	重试一次；若问题仍然存在，建议重启 MCP 主机或检查网络；重新运行 MCP 服务连接检测。
身份验证已过期 / quick_wallet 尚未就绪	根据架构，运行 x402_quick_wallet_auth，或在列出登录工具时运行 x402_request；然后再重试签名一次，之后再升级处理。
用户看到价格后拒绝支付	停止；不要调用签名/支付工具；提供其他商户选项或结束。
402 / 余额不足	显示 MCP 错误文本；仅当有其他已配置的支付通道且用户同意时，才建议使用其他通道（参见钱包与支付通道）。
缺少 402 挑战或无法解析	不要编造支付参数；根据架构重新运行服务列出的 HTTP 工具（x402_place_order 和/或 x402_request），或询问用户提供商户上下文；绝不要伪造支付成功。
缺少工具 / 没有 inputSchema	按设置指南完成安装；不要猜测参数。
discoveryResource 错误或 items 为空	扩展搜索文本，检查 resourceType（http 与 mcp）；如果仍为空，则改用用户提供的商户网址或结束 — 不要编造目录条目。

数据处理与资格要求

• 数据流：****支付流量和钱包 env 会发送到支付 MCP（gatepay-local-mcp）。发现查询会发送到列出目录工具的服务器（可能是一个远程 URL MCP）。密钥（EVM_PRIVATE_KEY、完整的 PLUGIN_WALLET_TOKEN、工具输出中的私钥）保留在支付 MCP 环境变量或集成终端流程中，不得出现在聊天中（参见安全规则）。
• 年龄：支付和关联账户的流程默认用户已年满 18 周岁，并遵守适用的 Gate 用户协议；如果用户无法满足这些要求，请勿继续进行支付设置。

---

子模块

此技能使用单文件路由处理流程逻辑：钱包设置、发现、工作流和 Exchange 流程都位于此 SKILL.md 中。使用路由规则跳转到相应部分。references/scenarios.md 存放面向 QA 的场景（提示词形式和预期行为）；它不是运行时路由子模块。面向人工读者的文档：README.md、CHANGELOG.md。

---

Gate Exchange 流程

选择 gate_exchange 且 Gate Exchange MCP 可用时：下单/支付只能使用 Exchange MCP 工具。每次调用前，读取 Exchange 服务器上相应工具的 inputSchema。不得使用第三方 x402 MCP 完成同一笔 Gate Pay x402_place_order 订单。

---

后续路由

流程后的用户意图	目标
更改默认支付方式 / 添加第二个钱包	此文件 — 钱包配置流程第 4 节
MCP Wallet（quick_wallet）过期后重试	此文件 — 工作流第 5–6 步
缺少商户参数	询问用户或上游；然后根据架构，使用服务器列出的 HTTP 工具执行第 4 步（x402_place_order 和/或 x402_request）
发现结果为空 / 无法选择	GatePay 商户发现与 Agent 编排——放宽 resourceDes / 筛选条件或停止；如果列出了目录工具，请在发现 MCP上使用更宽泛的词语重试
用户看到价格后拒绝支付	停止调用支付工具；提供其他商户选项或结束流程
插件支付通道失败，且没有其他已配置的支付通道	GatePay 商户发现与 Agent 编排——不要自动启动未配置的 quick_wallet

---

跨技能协作

其他技能或上游层可以提供商户的 url / method / body 或发现上下文。此技能会编排发现（存在时在发现 MCP上进行）→ 选择 → 可选的报价查询 → 支付确认 → 在支付 MCP（以及可选的 Gate Exchange MCP）上调用 x402_*，并在每次工具调用时使用 inputSchema。它不会替代 MCP 范围之外的完整商户目录。

---

支持的网络与资产

网络、代币和金额由商户的 402 / 需支付载荷及 MCP 行为决定，此处不逐一列出。遵循工具响应和商户规则。

---

安全规则

1. 优先遵循架构定义进行调用： 调用 MCP 前，始终先根据目标工具的 inputSchema 调整 arguments。Skill 与 inputSchema 冲突时，以 inputSchema 为准（与顶部的 Gate Pay x402 层说明和 如何构建 arguments 相同）。
2. 敏感载荷 — MCP Wallet（quick_wallet）： 工具返回的私钥、种子和导出的签名密钥只能发送到集成终端（或写入 gitignore 忽略的临时文件，再通过终端指向该文件），绝不能发送到 Agent 聊天 — 请参阅钱包配置流程第 1 节第 5 步；在 Windows、macOS、Linux 上可通过 node/python 或文件回退方案使用。公开的充值地址 / 钱包地址可以出现在聊天中。不要将大量原始 JSON 倾倒到聊天中；在聊天中对秘密信息进行脱敏。
3. 私钥 — 方式和用户粘贴内容： local_private_key： 用户只能在本地 MCP env 中设置 EVM_PRIVATE_KEY — 绝不要在聊天中收集或复述该密钥（第 3 节）。MCP Wallet： 工具返回的秘密信息只能发送到终端（第 1 节第 5 步）。如果用户在聊天中粘贴了任何私钥： 不要复述该密钥、从聊天中保存该密钥或基于聊天内容签名；告知用户只能将其放入 env，并停止在聊天中发送密钥。签名时使用 env，因为 MCP 会读取其中的密钥。
4. Open API 令牌： 存储在 env 中；在聊天中遮蔽或确认令牌，但不要暴露完整值。
5. 对单笔 Gate x402_place_order 订单，必须使用同一服务端 / 不得混用不同供应商：请参阅工作流。
6. 会话与聊天： 不要依赖聊天记忆来保存 MCP Wallet 登录状态；根据架构定义，使用 x402_quick_wallet_auth，和/或（列出时）使用 x402_request 进行 MCP Wallet 登录；用户使用 centralized_payment 时，如果列出了 x402_gate_pay_auth，则使用该工具（请参阅钱包配置流程第 1 节）；按照文档说明依赖 MCP 响应。