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。

1. 这是什么（零基础也能懂）​

解决什么问题、给谁用​

它能做什么​

用起来什么样​

一句话直觉 / 类比​

2. 顶层全景（它大概怎么转）​

三个角色​

主线：一次付费请求怎么走完​

部件一句话职责（TypeScript 参考实现）​

3. 阅读地图（建议顺序）​