AgentGrade
EnglishEspañolDeutsch日本語中文
← 知识库

x402 — HTTP 支付协议

什么是 x402？

x402 将 HTTP 402 "Payment Required" 状态码变成了一个真正的支付协议。当一个代理访问付费端点时,服务器会返回一个 402 响应,其中包含一个 Payment-Required 头部,该头部包含结构化的支付指令。代理(或其钱包)检查头部,决定价格是否可接受,在链上支付,将收据附加到重试中,然后接收响应。

从概念上讲,x402 终于完成了自 1996 年以来一直在 HTTP 规范中未被使用的 HTTP 402 状态码 — 规范为 "Payment Required" 保留了该代码,但从未指定客户端应该如何支付。x402 指定了机制:Base 上的 USDC、签名的支付意图、由协调者中介的结算,以及让代理在调用前找到付费端点的发现格式。

为什么 x402 重要

传统的 API 货币化是为人类构建的:注册、生成 API 密钥、管理信用卡、收到月度发票。每一步都需要 UI、账户,以及 API 提供者和开发者之间的带外关系。

自主代理没有这些。第一次调用付费 API 的代理需要:

x402 用一个机制解决了所有四个问题。价格在 402 头部中。支付是 Base 上的签名交易。结算是亚秒级的。收据是链上确认。

这使 x402 成为代理网络的基础支付原语 — 类似于 TLS 之于商业网络,或 OAuth 之于委托授权:一个将以前由人类中介的事物转变为机器可以端到端协商的协议。

工作原理

  1. 代理向付费端点发送请求
  2. 服务器返回 HTTP 402,带有 base64 编码的 Payment-Required 头部
  3. 头部包含:金额、资产(USDC)、网络(Base)、接收钱包和协调者
  4. 代理通过协调者(例如 Coinbase)支付
  5. 代理使用包含收据的 Payment 头部重试请求
  6. 服务器通过协调者验证支付并提供响应

整个流程端到端只需几秒钟。没有 API 密钥。没有订阅。没有人类参与。

x402 与传统 API 货币化的对比

方面API 密钥 + 订阅x402
注册需要创建账户无
认证每个账户的 API 密钥每次请求支付
计费模式月度订阅按请求付费
发现带外(文档、销售)协议内(402 头部)
结算发票周期(约 30 天)亚秒级(链上)
失败模式配额超出 → 429支付不足 → 402
代理兼容性困难(账户管理)原生
地理限制常见(Stripe 限制)最小(链上)

关键转变:x402 将价格放入协议本身,任何代理都可以读取。使用 API 密钥时,价格只存在于人类之间协商的合同中。使用 x402,价格在 HTTP 响应中,就像状态码一样 — 一等的传输元数据,而不是纸面工作。

关键概念

谁在使用 x402

x402 生态系统围绕两个支柱形成:

除了这些支柱之外,个别 API 提供者、代理运行时和 MCP 服务器运营商正在为按调用计费集成 x402 — 付费 MCP 工具、计量数据 API、AI 推理端点和代理市场。

如何将 x402 添加到你的服务

1. 安装 SDK

npm install @coinbase/x402-express

2. 向 Express 应用添加中间件

import { paymentMiddleware } from '@coinbase/x402-express';

app.use('/api/paid-endpoint', paymentMiddleware({
  payTo: '0xYourWalletAddress',
  amount: '100000', // 0.10 USDC(最小单位)
  network: 'base',
  facilitator: 'coinbase',
}));

3. 发布发现文件

提供 /.well-known/x402.json 让代理可以找到你的付费端点:

{
  "x402Version": 2,
  "name": "你的服务",
  "network": "base",
  "facilitator": "coinbase",
  "payTo": "0xYourWalletAddress",
  "services": [{
    "method": "POST",
    "path": "/api/paid-endpoint",
    "amount": "100000",
    "discoverable": true
  }]
}

4. 测试流程

curl -i https://your-domain.com/api/paid-endpoint
# 预期: HTTP/1.1 402 Payment Required
# 预期: Payment-Required: <base64 编码的支付指令>

解码 Payment-Required 头部(base64 → JSON),确认金额、资产、收款人和协调者与你的中间件配置匹配。

常见错误和调试

AgentGrade 的扫描器直接探测这些 — 其 x402 检查验证实时 402 响应可以干净地解析,并且发现文件与端点实际返回的内容匹配。

常见问题

x402 是区块链协议还是 HTTP 协议?

两者都是。传输是 HTTP(带有结构化头部的 402 状态)。结算是链上(Base 上的 USDC)。x402 是桥梁 — 让 HTTP 服务器和 HTTP 客户端协商由区块链结算的支付的协议。

我需要加密钱包来接受 x402 支付吗?

是的。你需要一个 Base 钱包来接收 USDC。Coinbase 的 CDP 让非加密原生团队也能管理这一切 — 你可以通过 API 配置托管钱包,无需接触密钥。

x402 和 Stripe 有什么区别?

Stripe 是主导的传统轨道:按账户 API 密钥、月度订阅、基于人类买家训练的欺诈检测。x402 是按请求、代理原生,并在链上结算。它们是互补的 — Stripe 用于人类结账,x402 用于代理计量访问。Tempo MPP 为想要两者的站点充当桥梁。

x402 已准备好用于生产吗?

是的。该协议现由 Linux Foundation 旗下的 x402 Foundation 管理(2026 年 7 月投入运营),提供 TypeScript、Go 和 Python 的官方 SDK。规范协调者在生产中运行,Cloudflare 已为其 x402 Monetization Gateway 开放候补名单,Amazon Bedrock AgentCore Payments(预览版)以托管服务形式处理 x402 协商。

代理可以使用 x402 互相付款吗?不仅仅是付给 API 提供者?

是的。x402 不关心"服务器"是人类运营的 API、代理还是 MCP 工具。任何 HTTP 响应者都可以返回 402,任何 HTTP 请求者都可以支付。代理之间的计量工作是最活跃的用例之一。

为什么是 USDC 而不是 ETH?

稳定。价格可预测。大多数 API 提供者以美元定价,并希望使用稳定美元资产进行结算;波动资产会产生会计摩擦,从而破坏按请求模式。

如果代理没有资金会怎样?

钱包返回资金不足,调用失败。协议本身没有重试-购买信用流程 — 资金是钱包的事,不是 API 的事。

x402 端点的可发现性如何?

在 x402.json 中标记为 "discoverable": true 的端点出现在 x402 Bazaar — 付费服务的公共目录中。代理浏览 Bazaar 的方式与开发者浏览 npm 的方式相同。

规范成熟度

生产就绪,由基金会治理。 Coinbase 将 x402 捐赠给 x402 Foundation,该基金会于 2026 年 7 月在 Linux Foundation 旗下投入运营,拥有约 40 个成员组织 —— 高级成员包括 Visa、Mastercard、Stripe、Google、AWS、Cloudflare 和 Shopify。规范仓库现位于 github.com/x402-foundation/x402(coinbase/x402 作为开发分支继续存在)。规范将 v2 的头部传输记述为当前版本,同时仍包含 v1 的正文传输。Chainalysis 统计,协议第一年在 Base 上产生了超过 1 亿笔 x402 智能体支付;平台级支持也在到来:Cloudflare 的 Monetization Gateway(候补名单)和 Amazon Bedrock AgentCore Payments(预览版)都原生支持 x402。

了解更多

相关

相关阅读：什么是 AI 智能体就绪？ · 立即测试: x402 Checker