数据截至 (上游 commit 230e6a9a7eeb)
x402 — 架构与原理
30 秒导读： x402 把 30 年来几乎没人用的 HTTP
402 Payment Required状态码做成了真协议。服务器对未付费请求回402+ 一份机器可读的报价；客户端（人或 AI agent）签一笔链上稳定币授权塞回请求头；一个叫"facilitator（设施方）"的中间服务替服务器验签、上链结算。对客户端来说，这一切像"自动重试一次"那么简单——它不用碰 gas、RPC、私钥管理这些链上脏活。
1. 这是什么（零基础也能懂）
一句话定义： x402 是一套让 HTTP 请求自带付款的开放标准——付款被编码进请求/响应的 header，按需、按次、链无关。
解决什么问题、给谁用
想象你写了个 AI agent，要它自己去调一个付费天气 API。今天的世界里这件事极其别扭：
- 你得预先去那家公司注册账号、绑信用卡、拿 API key、塞进环境变量。
- 每家服务都是一套不同的账号体系、不同的计费后台。
- agent 没法"临时遇到一个没见过的付费资源就当场付钱"——它只能用你提前配好的那几个 key。
x402 把这套"先注册后使用"的模式翻过来：付款变成请求的一部分。agent 直接请求资源，撞到 402 就当场签一笔小额稳定币付款、重试，拿到数据。没有账号、没有 API key、没有月度账单——一次请求一次付款。
谁会用它：
| 用户 | 场 景 |
|---|---|
| AI agent | 自主地为 API/工具/数据按次付费，无需预置账号 |
| API 提供方 | 给端点挂个中间件就能收费，不用自建计费/账号系统 |
| 内容站 / RPC 服务 | 按调用收费（pay-per-use），而不是订阅 |
| 人类用户 | 浏览器里弹出钱包付款墙（paywall），点一下付费看内容 |
它能做什么
- 报价：服务器告诉客户端"想要这个资源，请按 A/B/C 几种方式之一付款"。
- 付款：客户端选一种、用钱包签一笔授权（不广播、只签名）。
- 验证 + 结算：facilitator 替服务器检查这笔授权有效、然后真正上链转账。
- 多链多币多方案：同一套消息格式，底下可以是 EVM、Solana、Aptos…，可以是
exact（精确额）、upto（封顶额）、batch-settlement（批量）。 - 多传输层：同一套消息可以跑在 HTTP、MCP（AI 工具协议）、A2A（agent 间协议）上。
用起来什么样
服务端：给一条路由挂中间件，声明"GET /weather 收 $0.001"。
// 示意，基于 typescript/packages/http/express/src/index.ts 的真实 API
import { paymentMiddleware } from "@x402/express";
app.use(
paymentMiddleware(
{
"GET /weather": {
accepts: {
scheme: "exact", // 精确额方案
network: "eip155:8453", // Base 主网（CAIP-2 写法）
price: "$0.001", // 人类可读价，框架自动换成原子单位
payTo: "0x209693Bc...287C", // 收款地址
},
description: "Weather data",
},
},
resourceServer, // 预先配好 facilitator + scheme
),
);
客户端：把普通 fetch 包一层，付款全自动。
// 示意，基于 typescript/packages/http/fetch/src/index.ts 的真实 API
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
const client = new x402Client().register("eip155:8453", new ExactEvmScheme(myWalletSigner));
const fetchWithPay = wrapFetchWithPayment(fetch, client);
// 第一次请求若收到 402，库会自动签名 + 重试，调用方完全无感
const res = await fetchWithPay("https://api.example.com/weather");
一句话直觉 / 类比
把它想成饭馆的"先吃后结"。 你（客户端）点菜（请求资源），服务员（资源服务器）说"这道菜 8 块"（402 + 报价）；你不用现金、只"签个单"（签一笔链上授权，但不立刻转账）；收银台（facilitator）拿着你签的单去刷你的卡（上链结算）。你不用懂 POS 机怎么连银行、走哪条清算网络——那是收银台的事。x402 里"收银台"这层就叫 facilitator，它的存在就是为了把链上的复杂度从你和饭馆身上抽走。
2. 顶层全景（它大概怎么转）
三个角色
x402 的世界里只有三个角色，记住它们就抓住了全局：
| 角色 | 干什么 | 类比 |
|---|---|---|
| Client（客户端） | 想要资源、愿意付钱的一方。签付款授权。 | 食客 |
| Resource Server（资源服务器） | 提供受保护资源、要求付款的一方。 | 饭馆 |
| Facilitator（设施方） | 替服务器验签 + 上链结算的中间服务。 | 收 银台 / 清算行 |
资源服务器不直接碰链——它把验证和上链都委托给 facilitator。这是 x402 的核心解耦：饭馆只管做菜，不管刷卡清算。
主线：一次付费请求怎么走完
Client Resource Server Facilitator
│ │ │
│ ① GET /weather (无付款) │ │
├────────────────────────────>│ │
│ │ 没带付款 → 生成报价 │
│ ② 402 + PaymentRequired │ │
│<───── ───────────────────────┤ (header 里带 accepts[]) │
│ │ │
选一种 accepts，钱包签授权 │ │
(不广播，只产出签名) │ │
│ │ │
│ ③ GET /weather + 付款 header │ │
├────────────────────────────>│ │
│ │ ④ POST /verify (验签) │
│ ├───────────────────────────>│
│ │ isValid: true │
│ │<───────────────────────────┤
│ │ 跑业 务逻辑、生成响应 │
│ │ ⑤ POST /settle (上链转账) │
│ ├───────────────────────────>│
│ │ success + txHash │
│ │<───────────────────────────┤
│ ⑥ 200 + 数据 + 结算回执 │ │
│<────────────────────────────┤ (PAYMENT-RESPONSE header) │
│ │ │
怎么读： 上→下是时间顺序。注意①②是"没付款被退回"，③才是"带着付款重试"——所以一次成功的付费请求其实是两个 HTTP 往返。④⑤是服务器在背后偷偷找 facilitator 办的事，客户端看不见。
一个微妙但关键的点： ④验证（verify）和⑤结算（settle）是分开的两步，而且⑤夹在"跑业务逻辑"之后。意思是：服务器先确认"这笔钱签得没问题"，等真的把活干完了，才真正扣款。活没干成（handler 报错或返回 4xx/5xx），就不结算。这条"先干活、成功才收钱"的纪律是 x402 的安全底线，第 4 章细讲。
部件一句话职责（TypeScript 参考实现）
| 部件 | 干什么 | 在哪个文件 |
|---|---|---|
x402Client | 客户端编排器：挑报价、调 scheme 造付款、跑 hook | typescript/packages/core/src/client/x402Client.ts |
x402ResourceServer | 服务器编排器：造报价、调 facilitator 验证/结算 | typescript/packages/core/src/server/x402ResourceServer.ts |
x402Facilitator | 设施方编排器：按 scheme/network 路由到具体实现 | typescript/packages/core/src/facilitator/x402Facilitator.ts |
SchemeNetwork* 三件套接口 | 一个"方案×网络"要实现的客户端/服务器/设施方逻辑 | typescript/packages/core/src/types/mechanisms.ts |
| HTTP 传输适配 | 把抽象消息编进 base64 header；Express/Next/Hono 等中间件 | typescript/packages/core/src/http/、typescript/packages/http/ |
ExactEvm* 等 mechanism | exact 方案在某条链上的真实签名/校验/上链 | typescript/packages/mechanisms/evm/src/exact/ |
3. 阅读地图（建议顺序）
这是个多语言 monorepo（TS / Go / Python / Java + Solidity 合约 + 一份规范），但值钱的核心概念是统一的。本套文档以 TypeScript 参考实现 + v2 规范为主线，按"由浅入深"分章：
-
01 — 协议数据结构与四步流程 先认识三个核心 JSON 结构和那条
402→签名→verify→settle循环。读完你能手写出一对请求/响应。所有人从这里开始。 -
02 — 三层架构与编排器 x402 怎么把"消息格式""付款逻辑""传输方式"三件事彻底解耦，从而一套代码支持多链多方案多传输。讲
SchemeNetwork*接口和三个注册表编排器。想理解"为什么它能这么通用"读这章。 -
03 — exact 方案在 EVM 上的真身 把"付款"这个抽象动作落到真实链上：EIP-3009
transferWithAuthorization怎么实现"客户端签名、facilitator 代付 gas"的 gasless 转账，facilitator 验证的 6 道关卡。想看链上是怎么真扣钱的读这章。 -
04 — HTTP 传输与结算时序 抽象消息怎么塞进
PAYMENT-REQUIRED/PAYMENT-SIGNATURE/PAYMENT-RESPONSE三个 header；以及 Express 中间件"缓冲响应、handler 成功才结算"的精巧时序。想集成进自己的服务读这章。 -
05 — 巧妙之处、边界、横向对比 值得带走的设计精华、它刻意不做的事、和 MCP/A2A/传统支付的取舍对比，以及一张可 grep 的代码地图。
给 AI agent 的提示： 只想知道"消息长什么样"→读 01。只想集成服务端/客户端→读 01+04。要实现一个新 scheme 或新链→读 02+03。