零依赖实现x402微支付API：AI代理按次付费调用

为什么402状态码突然重要了

HTTP 402 "Payment Required" 从1997年就存在于规范中，但直到 x402 协议出现，它才真正被用起来。一位开发者最近在 Cloudflare Pages 免费计划上，用一个 _worker.js 和零 npm 依赖，搭建了一个真正可用的按次付费 API。AI 代理调用接口时收到 402，附带机器可读的支付条款，签名授权后重试，立刻拿到数据。没有注册、没有 API key、没有 Stripe 账户。

这篇文章将拆解其实现逻辑，并探讨它对 AI 代理经济的基础设施意义。

x402协议实现示意图

x402支付流程拆解

三段式握手

整个流程分三步：

代理发起请求 GET /api/apis/search?q=weather，不带支付信息，服务端返回 402，响应头包含 base64 编码的 PAYMENT-REQUIRED（x402 v2），响应体同时给出 JSON 格式的支付要求（x402 v1，兼容老客户端）。内容明确：在 Base 链上支付 5000 个 USDC 原子单位，即 0.005 美元，收款地址明确。
客户端签署 EIP-3009 的 transferWithAuthorization，然后带 PAYMENT-SIGNATURE 头重试。
Worker 将签名载荷 POST 到 facilitator 的 /verify 接口验证，验证通过后执行处理逻辑，最后调用 /settle 结算。Facilitator 负责广播转账并支付 gas，USDC 直接进入作者钱包。

这套流程的关键在于：支付和业务逻辑解耦。Worker 本身不碰私钥、不管理资金，只负责验证签名和触发结算。

EIP-3009 与 transferWithAuthorization：EIP-3009 是以太坊上针对 USDC 等 ERC-20 代币的“免 gas 转账授权”标准。它允许代币持有者离线签署一条 transferWithAuthorization 消息，其中指定 from、to、value、validAfter、validBefore 和 nonce，任何第三方（如 facilitator）都可以拿着这份签名代替持有者发起链上转账。由于签名本身不消耗 gas，持有者无需持有原生代币即可完成支付；gas 由广播方承担。x402 正是利用这一机制，让 AI 代理只需用私钥签署授权，而无需管理链上 gas，也无需提前把 USDC 换成本链原生币。

Facilitator：在 x402 协议中，facilitator 是一个独立的中介服务，负责两件事：/verify 检查客户端提交的支付签名是否有效（金额、收款方、有效期、nonce 等），/settle 在验证通过后把签名交易广播到链上并支付 gas，完成 USDC 的实际转移。服务提供者（Worker）不接触私钥、不管理资金、不运行区块链节点，只把签名载荷转发给 facilitator，因此支付层可以做到完全无状态。

不需要API密钥的Facilitator

原作者发现，Coinbase 的 facilitator 在主网上需要 CDP 密钥，但有一些公共 facilitator 完全不需要认证。他使用了 PayAI（facilitator.payai.network）作为首选，xpay（facilitator.xpay.sh）作为备用。代码很简单：遍历 facilitator 列表，POST 载荷，返回结果中包含 isValid 或 success 字段即视为成功。这降低了搭建付费 API 的门槛——你不需要在 Coinbase 开账户、申请密钥，只需要一个钱包地址。

PAYMENT-REQUIRED 与 PAYMENT-SIGNATURE 头：这两个自定义 HTTP 头是 x402 协议的数据载体。服务端在 402 响应中返回 PAYMENT-REQUIRED，其内容经 base64 编码，包含 x402 版本、支付网络（如 Base）、资产合约地址、金额（以原子单位表示）、收款地址、有效期等机器可读条款。客户端解析后，构造并签署 EIP-3009 授权，再把签名结果放入 PAYMENT-SIGNATURE 请求头重试。由于这些头是自定义的，普通浏览器或未适配的客户端只会看到 402 和 JSON 响应体，不会误触发支付；只有理解 x402 的代理才会继续握手。

零成本测试与按结果收费的设计

用空钱包验证签名正确性

作者用一个由 viem 生成的全新空钱包，签署正确的授权信息并发送到线上 API。Facilitator 返回了 invalid_exact_evm_insufficient_balance 错误。这个错误恰好说明：签名格式、EIP-712 域（USD Coin、版本 2、链 ID 8453）、金额和收款方全部被接受，唯一缺失的是余额。这是一种零成本的端到端检查——不花一分钱，就能确认支付通道的完整性。

先执行后结算

代码逻辑是 verify → 执行 → settle。如果执行步骤失败（比如参数错误、URL 无效），直接返回 400，绝不调用 settle，代理不需要支付任何费用。这个细节很重要，因为 AI 代理会频繁重试，如果先扣费再执行，失败请求也会产生费用，破坏信任。

verify → 执行 → settle 的顺序为何重要：在传统支付中，扣款通常发生在服务交付之前，以避免坏账。但 AI 代理的调用模式不同：代理会基于不完整信息发起试探性请求，失败重试极其频繁。如果先 settle 再执行，任何参数错误、超时或上游数据源故障都会让代理为未获得的服付费，累积起来会迅速破坏代理对端点的信任，甚至导致代理在发现层中拉黑该 API。x402 推荐先 verify（只检查签名有效性和余额，不广播交易），再执行业务逻辑，只有执行成功才调用 settle。这样失败请求零成本，代理可以放心重试，而服务提供者也不会因为执行失败而损失 gas。

让AI代理发现你的付费API

付费 API 如果没人能找到，收入就是零。作者列出了几个有效的发现渠道：

Bazaar 元数据：在 402 响应中嵌入 extensions.bazaar，提供输入/输出 JSON schema，让代理市场能索引。
OpenAPI 规范：每个付费操作附带 x-payment-info，并提供 /.well-known/x402 端点。
x402dash：每个端点向 https://api.x402dash.com/v1/register POST 一次，它会实时探测 402 响应。
x402scan：需要钱包签名（Sign-In-With-X），由 @x402/extensions 处理。

作者强调，发现是真正的工作量所在，不要把全部精力放在代码上。

Bazaar 与 x402 发现层：Bazaar 是 x402 生态中用于索引付费端点的元数据机制。服务端在 402 响应的 extensions.bazaar 字段中声明每个端点的输入/输出 JSON schema、价格和描述，代理市场或爬虫可以据此自动发现并调用 API。与之配合的是 /.well-known/x402 端点，它返回整个服务的 OpenAPI 规范，其中每个付费操作带有 x-payment-info 扩展，说明价格和支付网络。x402dash 和 x402scan 则是第三方目录，前者通过主动探测 402 响应来收录端点，后者要求钱包签名（Sign-In-With-X）以证明端点所有权。这些机制共同构成代理经济的“搜索引擎”，但目前仍处于早期，注册流程分散且需要手动操作。

这个API卖什么？

作者上线的 API 提供四个付费端点，每个定价 0.001 美元：

/api/apis/search：搜索 2,230 个经过链接检查的公开和免费层 API，支持 auth=none&alive=yes 等过滤条件。
/api/free-tiers：开发者服务和 LLM API 的当前免费额度。
/api/robots-check：检查某个 user-agent 是否被允许爬取指定 URL。
/api/page-meta：提取公开页面的标题、OG 标签和标题结构（遵守 robots.txt）。

免费端点包括 /api/apis/sample、/openapi.json 和 /health。这个产品思路很清晰：卖数据，而不是卖计算。对代理来说，一次调用 0.001 美元的成本可以忽略不计，但省去了自己爬取和清洗数据的麻烦。

对AI代理经济的启示

这个项目的核心贡献不在于技术复杂度，而在于证明了几个关键点：

x402 可以在免费的边缘运行时上运行。不需要服务器、数据库或任何 API 密钥。Cloudflare Workers 的免费计划足以支撑。
支付层可以完全无状态。签名验证和结算都委托给 facilitator，服务提供者只关心业务逻辑。
代理原生支付是可行的。没有人类交互，代理自主完成支付决策和签名，这在 API 经济中是一个结构性变化——从“订阅制”转向“按调用付费”。
发现层是瓶颈。当前生态还在早期，列出 API 需要手动操作多个注册表。

作者建议同时返回 v1 和 v2 两种挑战格式，因为现实世界中的客户端两种都在用。这个细节说明 x402 还处于过渡期，兼容性需要手动处理。

对于想要尝试的开发者，可以直接读取线上 API 的 402 响应，理解格式后自己实现。作者也提供了包含测试和列表步骤的付费 starter kit。

总结

x402 让 1997 年就存在的 402 状态码终于有了实际用途。一个零依赖的 Worker、一个公共 facilitator、一个钱包地址，就能构建面向 AI 代理的按次付费 API。技术门槛已经很低，真正的门槛在于发现和流量——这也是任何 API 经济早期的典型特征。