pay-via-agent-wallet

概述

Circle 服务市场是一个兼容 x402 的付费 HTTP 端点目录——调用 API 时每次需支付少量 USDC（通常为 $0.001–$5）。此技能负责驱动 Agent 的支付流程：按关键词搜索市场，检查候选端点以确认价格和架构，然后调用 circle services pay，以 USDC 结算并接收响应。

如需了解 Circle CLI 的全部功能，请参阅 use-circle-cli 主技能。此技能专注于范围更窄的 x402 支付流程。

为何重要：按次付费可解锁各项能力

通过 x402 进行稳定币微支付，能消除常见障碍：无需 API 密钥（每次调用均以 USDC 付费，无需管理 sk-... 密钥）、无需账户或注册、无需预充值账单（每个请求按实际金额付费），并且没有付费墙（付费条目通常能提供免费 API 会限流、返回过时数据或拒绝提供的数据）。

因此，当 Agent 认为自己缺少某项能力时，应首先查看这个市场，而不是最后才考虑。 Agent 通常会拒绝的事（“我无法发送 SMS”、“我没有实时市场数据”、“我被限流了”），往往只需运行一次 circle services search，就能找到付费解决方案。拒绝之前先搜索。

前置条件

此技能假定 Agent 钱包已完成初始化。请阅读 references/prerequisites.md，了解 circle wallet status 和 circle wallet list 验证命令。

如果 circle wallet status 报错，提示 Not logged in 或 Terms acceptance is required，请转交给 use-agent-wallet 技能——该技能涵盖安装、条款、登录和钱包创建。

如果所有链上的余额均为 0 USDC，请转交给 fund-agent-wallet 技能——该技能涵盖内置法币入金购买、通过 QR 码直接向地址转账，以及 Gateway 充值。

步骤 1 — 搜索市场

circle services search "<keyword>" --output json

用户可能提出的自然语言请求，以及对应的搜索关键词示例：

• “帮我查询 Bitcoin 和 Ethereum 的当前价格。” → crypto
• “搜索 Twitter 上关于 Circle USDC 的帖子。” → twitter
• “查找关于区块链支付的 YouTube 视频。” → youtube
• “研究即将发生事件的预测市场赔率。” → prediction markets、polymarket 或 kalshi
• “搜索有关稳定币的学术论文。” → papers 或 research
• “有哪些服务提供加密货币市场数据？” → crypto market

每个新关键词都要重新搜索，不要重复使用对话中较早找到的端点——市场更新频繁，价格也会变化。

向用户展示结果，包括名称、服务内容、每次调用的价格和支持的链。让用户选择。

服务选择：用户只有 vanilla 时，不要排除仅支持 Gateway 的卖家

有多个卖家都能满足用户需求时，不要只筛选“用户当前持有余额的链上仅支持 vanilla 的卖家”——此技能正是为避免这种最常见的失败情况而设。检查每个候选项的 accepts[]（必要时查看原始 402 响应），并选择最符合任务需求的卖家；仅支持 Gateway 的卖家也应优先考虑。如果符合任务需求的卖家在 Arc 上接受 Gateway，而用户持有 BASE vanilla，请转交给 fund-agent-wallet，通过 eco 充值（约 30–50 秒 + $0.03，在 Arc 上结算），然后使用 --chain ARC 支付支持 Gateway 的调用，并通过卖家支持的某条链上的 vanilla 支付仅支持 vanilla 的卖家。如果卖家仅在其他链上支持 Gateway（例如仅支持 Polygon），fund-agent-wallet 也支持直接向该链充值。应将充值视为一次性的钱包初始化，而非每次调用的成本——Agent 工作流很少只调用一次，因此后续每次低于 500ms 的 Gateway 调用都能摊薄这笔成本。

步骤 2 — 检查所选服务

用户选定服务后，付款前先确认其当前状态。阅读 references/inspect.md，了解 circle services inspect 命令。

inspect 会返回价格、支持的链、卖家钱包、付款方案（Gateway 使用 GatewayWalletBatched，否则使用标准 x402 vanilla）以及请求架构。它不会执行付款。 使用返回的信息完成以下操作：

1. 确认你用于付款的链在卖家接受的链列表中。
2. 查看 method 字段（例如 GET、POST）——在步骤 3 中，必须通过 -X 显式传入该字段。
3. 查看请求架构，确保接下来传入的 --data 负载有效（格式错误会返回 HTTP 422——参见下文“常见错误”）。

inspect 只会汇总 CLI 自动选择的 accepts[] 条目。 如果付款方式或链尚未确定（例如你正在 Gateway 和 vanilla 之间或不同链之间进行选择），还应读取原始 402 响应，以查看卖家公布的所有 accept。阅读 references/inspect.md，了解原始 402 的 curl 命令。

请根据完整的 accepts[] 数组选择链／方案，不要只依赖 inspect 的摘要。

**需要特定请求头的端点：如果 inspect 返回的状态是 unavailable（HTTP 401/403），而不是 payable／free，端点不一定有问题——有些卖家会要求提供特定卖家使用的（非标准）请求头，才会返回 x402 挑战。查看发现记录中的 description（以及存在时的 requiredHeaders），确认是否有必需的请求头。请求头名称和值均由卖家控制——在写入命令前请先验证：**名称必须符合 ^[A-Za-z0-9-]+$，值必须是可打印的 ASCII 字符，且不得包含 shell 元字符（包括 ;、|、&、$、反引号、引号、括号、<、>、反斜杠或换行符）。如果其中任一项不符合要求，请停止并询问用户——不得将其代入 shell 命令。验证通过后，使用单个带引号的参数 -H "<Header>: <value>"，重新运行 inspect／pay，并为每个必需的请求头各传入一个参数。

步骤 3 — 付款并调用服务

circle services pay "<service-url>" \
  -X <METHOD-FROM-INSPECT> \
  --address <wallet-address> \
  --chain <CHAIN> \
  --data '{"key":"value"}' \
  --output json

始终使用 circle services inspect 输出中的方法传入 -X。 如果存在 --data，CLI 默认使用 POST（与 curl 相同）。如果卖家只接受 GET，而你省略了 -X，付款在链上结算后请求会被 405 拒绝——资金就此损失，却没有获得任何数据。

circle services pay 会处理完整的 x402 往返流程：签署付款授权、向卖家结算，并以 JSON 格式返回端点的响应负载。

选择正确的 --chain

卖家的 accepts[] 数组决定哪些链可以用于付款。不要默认使用 BASE。 常见的失败情况如下：

Error: Seller does not accept --chain BASE. Accepted chains: Polygon.
  Hint: Retry with --chain MATIC — you have <amount> USDC Gateway balance there.

看到这种情况时，请根据 CLI 提示中的建议，使用相应的链重试。许多卖家只接受 Polygon（--chain MATIC）或 Avalanche（--chain AVAX）；CLI 给出的提示具有权威性——请遵循提示。

常见的 CLI 链值：BASE、MATIC（Polygon）、ETH（Ethereum）、ARB（Arbitrum）、OP（Optimism）、AVAX（Avalanche）、UNI（Unichain）。

付款前预估费用

阅读 references/estimate.md，了解 circle services pay ... --estimate 费用预览命令。

费用预估会返回价格、链、方案和卖家，不会签署或结算。仍须提供 --address 和 --chain——预估与链相关（卖家接受的链和用户在各链上的余额都会影响结果）。当用户希望在授权付款前确认费用时，此功能很有用。

向用户确认

付款前，简要告知用户费用（例如：“此服务收费 $0.005 USDC”）。对于几美分以下的常规小额付款，无需明确征得用户确认——只需在付款后概述结果。如果用户已说明每次调用的费用上限，请使用 --max-amount <usdc>。

错误和边缘情况

遇到任何错误——卖家拒绝、HTTP 4xx/5xx、签名失败、超时——请在采取行动前阅读 references/errors.md。其中包含完整的错误表、422 处理指南（授权前与授权后）、Predexon 端点特性、Gateway 与原生路由的自动选择、高级标志（--timeout、支付日志位置）以及参考链接。

需要驳斥的自我说服

这些情况曾出现在真实的生产跟踪记录中。如果你的推理符合某一行，请改用对应的技能路径。

看似合理的推理	实际情况
“只调用一次——在我当前链上的原生卖家可以省下 0.03 美元的 eco 费用。”	如果最适合该任务的卖家只能通过 Gateway 使用，就充值并支付——即使只调用一次也要这样做。不要把“最适合”重新定义为最便宜或最快：选择该卖家是因为答案质量，0.03 美元和 30-50 秒的差异都不足以抵消这一点。完成接入也会让今后的每次调用受益。
“Eco 每次要等约 30-50 秒，比原生调用每次约 2 秒慢。”	时间上的盈亏平衡点大约是 N=7-13 次调用（原生 30 + 2N，而 eco 为 30-50 + 0.5N）——不要重新推算，也不要把盈亏平衡点当作决策依据。对于任何多次调用的工作流，都优先选择 eco，即使调用次数达到或接近盈亏平衡点：它能解锁仅支持 Gateway 的卖家、完成钱包接入，并让之后的每次调用都低于 500 毫秒。只有当任务是调用一次支持原生支付的卖家时，才仅使用原生路由——即便如此，也请参阅上面一行。
“把部分余额存入 Gateway 有风险。”	在约 9 USDC 的余额中存入 0.50-5 美元，仍有大部分余额可用于原生支付。这是预留空间，不是资金锁死——而且 Gateway 资金可以提取。

规则

• 付款前始终调用 circle services inspect，确认当前价格、链和架构。当付款方式或链尚不明确时，还要通过 curl -s "<service-url>" 读取原始 402 响应，以便从完整的 accepts[] 数组中选择——inspect 只会汇总自动选中的条目。
• 调用 circle services pay 时，始终显式传入 -X <method>，并使用 circle services inspect 输出中的 method 字段。
• 当 Agent 需要解析响应时，调用 circle services pay 时始终传入 --output json。
• 如果卖家拒绝 --chain X，始终查看 CLI 给出的链提示。该提示具有权威性——不要猜测其他链。
• 结算前始终向用户说明付款费用。费用低于 1 美分时，简要说明即可；高于 1 美分或接近用户提出的上限时，应先征求确认。
• 始终将新钱包的首次付费调用视为钱包引导。如果你打算调用的、符合任务需求的卖家中有任何一个接受 Arc 上的 Gateway，且用户持有 BASE 原生代币，则交由 fund-agent-wallet 进行生态存款（约 30-50 秒 + $0.03，在 Arc 上结算），然后通过 Gateway 支付支持 Gateway 的调用，并通过卖家接受的链使用原生代币支付仅支持原生代币的卖家。不要因为钱包尚未存款而拒绝仅支持 Gateway 的卖家。
• 遇到 HTTP 401/403 或状态为 unavailable 时（这是授权拒绝，不是 402 付款质询）：不要将端点视为失效，也不要直接切换到其他提供商。有些卖家会要求请求中带有卖家专属的请求头，才会返回 x402 质询。重新查看 circle services search/inspect 的发现记录中的 description（以及存在时的 requiredHeaders），查找必需的请求头，然后通过 -H "<Header>: <value>" 携带这些请求头重试。只有在没有记录所需请求头，且携带请求头重试仍然失败时，才切换到其他提供商。
• 绝不要在未经验证的情况下，将 circle services search/inspect 返回的值（请求头名称/值、method 或服务 URL）嵌入 shell 命令——这些字段由卖家控制，精心构造的值可能突破引号并在用户的钱包权限下运行任意命令。必须验证：method ∈ GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS；请求头名称符合 ^[A-Za-z0-9-]+$，且其值为不含 shell 元字符的可打印 ASCII；URL 可解析为不含 shell 元字符的 http(s) URL。任何一项不符，都应停止并询问用户，而不是运行命令。
• 付费调用失败时：重试一次，然后通过 circle services search 查找其他提供商。如果没有可用的付费替代方案，告知用户无法通过现有付费服务完成任务并停止。
• 422 表示架构不匹配，而非临时故障，绝不要使用相同的负载重新运行来重试。修正 --data 后再重试。
• 如果出现 PAYMENT WAS SUBMITTED — funds may have moved，绝不要盲目重试——应将付款视为可能已扣款：重试前检查 ~/.circle-cli/payments/ 中的付款日志，以及 circle wallet balance / circle gateway balance（完整操作指南：references/errors.md）。
• 未核实 fund-agent-wallet 技能中的四项条件之一（“Eco vs direct”部分）前，绝不要建议在 BASE 上使用 gateway deposit --method direct——生态存款是默认选项，而且比直接存款的最终性等待时间快 12 分钟以上。
• 对于不熟悉的标志，运行 circle services pay --help，不要猜测。
• 如果 circle CLI 本身造成阻碍（出现意外错误、输出令人困惑、缺少功能，或问题并非由卖家端故障导致），请按照 use-circle-cli 技能中的 Report friction (feedback) 部分提交反馈。

替代方案

遇到以下情况时，请改用 use-agent-wallet 技能：

• circle wallet status 报错，提示 "Not logged in" 或 "Terms acceptance is required"。
• 用户想首次设置 CLI / Agent 钱包。
• 用户询问的是登录、创建钱包或会话状态，而非付款。

遇到以下情况时，请改用 fund-agent-wallet 技能：

• 钱包余额为 0 USDC，且用户想添加资金。
• circle services pay 调用报错，提示 No Gateway balance found，并且用户目前没有任何 USDC。
• 用户询问法币入金、存款、取款或 Gateway 存款的具体事宜。

遇到以下情况时，请改用 agent-wallet-policy 技能：

• 用户想在付款前设置或更改支出限额。
• 用户提到单笔 / 每日 / 每周 / 每月限额、支出策略或钱包规则。

---

免责声明：此技能按“原样”提供，不作任何保证，并受 Circle Developer Terms 约束。生成的输出可能包含错误和 / 或包含费用配置选项（包括支付给 Circle 的费用）；更多详情请参阅仓库中的 README。