x402 付款测试

x402 收费资源先返回 402 Payment Required 和付款要求。Agent Payments 会在策略、预算、审批和签名器约束内完成付款，再携带付款签名重新发送同一份 HTTP 请求。购买流程支持 HTTPS GET、POST、PUT、PATCH 和 DELETE 请求。

开始前请先完成快速开始，并确认运行时 MCP 与签名伴随服务正常。建议首次使用沙盒钱包和小额测试资产，并让付款进入人工审批。

本教程使用 Base Sepolia USDC。如果其它收费服务要求不同网络，请确认付款要求与支持范围所列网络和 USDC 一致，再从需要人工审批的小额付款开始。

1. 检查付款要求

下面的面板会按照你填写的资源地址、HTTP 请求方法、查询参数和请求体读取服务实际返回的 402 挑战。网络、资产、金额、收款地址和付款方案都以响应为准，面板不预设 Base Sepolia、USDC 或 exact。它不会在浏览器中持有私钥、创建 Intent 或付款。

检查器能够读取的挑战范围有意宽于 Agent Payments 的实际购买范围。成功显示挑战不代表可以购买。付款要求仍必须使用受支持的 x402 版本、付款方案、HTTPS 请求方法、网络和 USDC。批准付款前先执行预检，确认 StableOps 能否继续。

跨域服务还需允许文档站来源、所选请求方法和 Content-Type，并通过 Access-Control-Expose-Headers 公开 PAYMENT-REQUIRED 或 X-PAYMENT-REQUIRED，否则浏览器无法读取完整挑战。

2. 让 Agent 预检资源

如果已有收费资源，请准备包含路径和查询参数的完整 HTTPS 地址。没有目标时，可以让 Agent 先发现候选服务。把下面的指令交给已配置运行时 MCP 的 Agent：

请使用 StableOps Agent Payments MCP 准备一笔沙盒 x402 付款。

- 目标网址：<填写完整 HTTPS 地址，没有目标时先发现候选服务并让我选择>
- 请求方法：POST
- 内容类型：application/json
- 准确请求体：{"query":"stablecoins","limit":10}
- 先检查运行身份、支持网络、预算和签名伴随服务状态
- 对最终选定的准确网址执行付款预检
- 展示网址、网络、资产、金额、收款地址、策略结论、警告和预计预算
- 保存预检返回的 preview_token
- 不要创建付款 Intent，等待我确认

Agent 会调用 stableops_preview_x402_purchase。预检是只读操作，不创建付款 Intent，也不占用预算。对于非 GET 请求，不透明的 preview_token 还会绑定请求方法、准确请求体和内容类型。请求体只保留在 MCP 进程内存中并直接发给资源服务。StableOps 只接收其 SHA-256 摘要和内容类型。继续前应核对请求方法、准确网址、请求体、网络、资产、金额和收款地址。预检拒绝或返回内容与预期不符时不要付款。

直接使用 SDK 时写法相同：

const result = await agent.x402Fetch('https://resource.example.com/search', {
  method: 'POST',
  body: JSON.stringify({ query: 'stablecoins', limit: 10 }),
  contentType: 'application/json',
  idempotencyKey: 'research-task-284:search:v1',
})

请求体可以是字符串或准确的 Uint8Array 字节。Agent Payments 会对这些准确字节计算摘要并原样重发，不会代替调用方序列化 JavaScript 对象。非 GET 请求可以使用空请求体，此时会绑定空请求体的 SHA-256 摘要。GET 请求不能携带请求体或内容类型。

3. 确认并发起付款

确认预检结果后，向同一个 Agent 发送：

确认购买刚才预检的准确网址。
使用刚才的 preview_token，并把 idempotency_key 设为 x402-first-purchase-001。
不得更换请求方法、网址、查询参数、请求体、内容类型、收款地址或提高金额。
如果需要人工审批，保存 intent_id 后停止，不要创建另一笔付款。
如果付款成功，返回资源响应和 intent_id。

Agent 会调用 stableops_x402_fetch。正式购买会重新发送原请求以读取最新付款要求，并再次检查策略、预算、钱包、风控和预检约束。签名后，SDK 会使用同一请求方法和请求体，并加入 PAYMENT-SIGNATURE 后再次发送。同一笔业务购买的所有重试必须复用相同的 idempotency_key。

对于 POST 等可能产生业务副作用的操作，资源服务必须在执行受保护操作前返回 402。SDK 在发现和刷新付款挑战时可能多次发送该请求。如果卖方接口提供业务幂等字段，应把稳定值写入请求体。StableOps 的 idempotency_key 只用于去重付款 Intent，不能代替卖方应用自身的业务幂等机制。

4. 处理人工审批

如果结果为 awaiting_approval，在 StableOps 控制台核对并审批该付款，然后让 Agent 恢复原付款：

付款 Intent <填写 intent_id> 已批准。
请恢复原付款，继续使用原请求方法、准确网址、请求体、内容类型和 preview_token。
不要创建新 Intent，也不要更换 idempotency_key。

Agent 会调用 stableops_resume_x402_purchase 恢复原付款。付款被拒绝时不要恢复。

如果 MCP 已重启，应使用同一请求方法、准确网址、请求体和内容类型重新预检，再用新的 preview_token 恢复同一个 intent_id。Control API 会在签发授权前比较请求方法、完整网址哈希、请求体摘要、内容类型和最新付款要求。Agent 不得用另一笔付款替代等待审批或状态未知的付款。

5. 核对结果

• paid 表示付费 HTTP 请求已经得到可靠资源响应。
• settled 表示控制面已经确认链上结算。
• settlement_unknown 表示结果尚不确定，只能查询原 intent_id，不能重新付款。

让 Agent 使用 stableops_get_payment 查询原付款，并返回资源响应、付款状态和收据。需要异步接收审批、结算或异常状态时，配置签名 Webhook。