## 什么是 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 的代理需要:

- 在承诺*之前*发现价格
- 以编程方式支付,无需人工批准
- 在几秒内完成交易结算,而不是几天
- 接收 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 响应中,就像状态码一样 — 一等的传输元数据,而不是纸面工作。

## 关键概念

- **协调者(Facilitator)**:验证和结算支付的服务。在 x402.json 中设置 `"facilitator": "coinbase"` 以在 Base 主网上使用 Coinbase 的协调者。
- **Envelope v2**:当前的头部格式。添加了结构化的服务目录、Bazaar 发现和更丰富的支付选项。始终使用 v2。
- **网络**:支付在 Base(`eip155:8453`)上使用 USDC 进行。Base 上的 USDC 合约是 `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`。
- **按请求定价**:每次 API 调用都有自己的价格 — 没有订阅、没有分级计划、没有 API 密钥。
- **可发现服务**:使用 `"discoverable": true` 标记服务以出现在 [x402 Bazaar](/kb/zh/bazaar) 中 — 代理浏览的付费端点目录。

## 谁在使用 x402

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

- **Coinbase Developer Platform** — 协议的发起者。提供 TypeScript、Go 和 Python 的官方 SDK;在 Base 主网上运行规范协调者。
- **Tempo [MPP](/kb/zh/mpp)** — 由 Paradigm 和 Stripe 支持的支付代理。Tempo 运行 `*.mpp.tempo.xyz` 代理,为尚未原生实现 x402 的站点在 x402 和传统支付轨道之间进行翻译。

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

## 如何将 x402 添加到你的服务

### 1. 安装 SDK

```bash
npm install @coinbase/x402-express
```

### 2. 向 Express 应用添加中间件

```javascript
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` 让代理可以找到你的付费端点:

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

### 4. 测试流程

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

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

## 常见错误和调试

- **没有 Payment-Required 头部的 402**:中间件未配置。确认中间件调用上设置了 `payTo` 和 `amount`。
- **Payment 头部被拒绝**:收据金额错误、资产错误或已过期。大多数协调者拒绝几分钟前的收据。
- **钱包地址不匹配**:中间件中的 `payTo` 与收据的收款人不匹配。必须完全匹配。
- **网络不匹配**:收据在与声明的不同的链上。确认中间件和 x402.json 中 `network` 都是 `base`。
- **无法访问协调者**:协调者服务宕机。使用备用协调者,或在中断期间失败开放。

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 已准备好用于生产吗?

是的。x402 v2 由 Coinbase 通过 TypeScript、Go 和 Python 的官方 SDK 支持。规范协调者在生产中运行,付费服务的生态系统正在增长。

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

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

### 为什么是 USDC 而不是 ETH?

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

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

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

### x402 端点的可发现性如何?

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

## 规范成熟度

**生产就绪。** x402 v2 是当前的 envelope,由 Coinbase 通过 TypeScript、Go 和 Python 的官方 SDK 支持。协议稳定,规范协调者在生产中运行,生态系统跨 MCP 工具提供者、数据 API 和代理市场不断扩展。

## 了解更多

- [x402.org](https://www.x402.org/) — 协议规范
- [Coinbase x402 文档](https://docs.cdp.coinbase.com/x402/docs/welcome) — SDK 和集成指南
- [x402 npm 包](https://www.npmjs.com/package/@coinbase/x402-express) — Express 中间件
- [代理就绪度](/agent-readiness) — x402 如何融入更广泛的代理就绪度格局

## 相关

- [OpenAPI](/kb/zh/openapi)
- [A2A](/kb/zh/a2a)