主页
一个只加两个 HTTP 头的支付协议,已经在生产里跑了上亿笔;同一个月,三篇论文系统性地证明了它有洞。这份文档讲清楚它是什么、怎么接、什么时候别用。
A payment protocol that adds just two HTTP headers, already running hundreds of millions of transactions in production — and in the same month, three papers systematically proved it has holes. This document covers what it is, how to wire it up, and when not to.
一句话:x402 是一个开放的 HTTP 原生支付协议——服务端用 402 Payment Required 回一份「报价单」,客户端把一个签名后的付款授权塞进请求头再发一次,服务端验签放行,链上结算异步发生。全程不需要账号、不需要 API key、不需要人点确认。
In one sentence: x402 is an open, HTTP-native payment protocol — the server answers with 402 Payment Required plus a machine-readable quote, the client puts a signed payment authorization in a request header and retries, the server verifies it and serves the resource, and on-chain settlement happens asynchronously. No account, no API key, no human clicking Approve.
为什么现在值得学:
Why it's worth learning now:
x402 把同步的 HTTP 授权和异步的链上结算缝在一起,这条缝制造了传统 Web 支付和纯链上支付都没有的跨层攻击面。签名的付款凭据本质是 bearer credential(拿到就能用),协议本身没有应用层 nonce。任何生产接入都必须自己补上花费策略、幂等与重放防护。
x402 stitches synchronous HTTP authorization onto asynchronous on-chain settlement, and that seam creates a cross-layer attack surface absent from both conventional web payments and pure on-chain payments. A signed payment payload is effectively a bearer credential, and the protocol has no application-layer nonce of its own. Any production integration must add its own spending policy, idempotency, and replay protection.
HTTP 规范里一直有一个 402 Payment Required,自 1990 年代起就被标记为「保留供未来使用」。原因很实际:那时没有一种能在一次请求往返里完成、金额可以低到几分钱、且不需要人工介入的结算方式。信用卡的最小手续费就把微支付判了死刑。
The HTTP spec has always had a 402 Payment Required, marked "reserved for future use" since the 1990s. The reason was practical: there was no settlement method that could complete inside a single request round-trip, go as low as fractions of a cent, and require no human in the loop. Credit-card minimum fees alone killed micropayments.
x402 的判断是:稳定币 + 可由第三方代付 gas 的签名授权让这三个条件同时成立了。它由 Coinbase Developer Platform 提出,白皮书发布于 2025-05-06;V2 于 2025-12 发布。事实
The x402 bet is that stablecoins plus signed authorizations whose gas a third party can pay make all three conditions true at once. It came out of Coinbase Developer Platform, with the whitepaper published on 2025-05-06 and V2 in Dec 2025. fact
传统 API 变现的路径是:注册 → 拿 API key → 绑卡 → 按月结算。这套流程里的每一步都预设了一个人。一个自主 agent 想临时调用一个它三秒钟前才发现的数据源,这套流程完全走不通——它没有邮箱、没有信用卡、也没有耐心等人工审批。
The classic path to API monetization is: sign up → get an API key → attach a card → settle monthly. Every step of that presumes a person. An autonomous agent that wants to call a data source it discovered three seconds ago cannot walk that path — it has no inbox, no credit card, and no patience for manual approval.
x402 把这条链路压缩成:请求 → 收到报价 → 签名 → 重发 → 拿到资源。服务方不需要认识调用方是谁,只需要确认「这笔钱到账了」。推断这本质上是把 API 的商业模型从「身份授权」换成了「按次结算」——身份问题被绕开,而不是被解决。
x402 compresses that into: request → receive a quote → sign → retry → get the resource. The provider never needs to know who the caller is, only that the money arrived. inference In effect this swaps the API business model from "identity-based authorization" to "per-call settlement" — the identity problem is routed around rather than solved.
MCP 2026-07-28 规范之后,一个远程 MCP server 就是一个普通 HTTP 负载。这意味着任何针对 HTTP 的支付中间件都能直接套在 MCP server 上——`tools/list` 保持免费,`tools/call` 里的付费工具走 402。MCP 官方路线图(2026-08-22)把 agent 身份与企业安全列为五大优先领域之一,但当前规范里没有支付原语;x402 填的正是这块空白。推断
After the MCP 2026-07-28 specification, a remote MCP server is just an ordinary HTTP workload. That means any HTTP payment middleware drops straight onto an MCP server — keep `tools/list` free, and gate priced tools inside `tools/call` behind a 402. The official MCP roadmap (2026-08-22) lists agent identity and enterprise security among its five priority areas, but the current specification has no payment primitive; x402 fills exactly that gap. inference
参与方有三个:客户端(付费的 agent)、资源服务器(卖东西的 API)、facilitator(验签并把钱真正搬上链的第三方)。下图是一次完整的往返。
Three parties are involved: the client (the paying agent), the resource server (the API selling something), and the facilitator (the third party that verifies signatures and actually moves the money on-chain). The diagram below is one complete round-trip.
服务端在 402 里返回一份结构化的支付要求,告诉客户端:多少钱、什么资产、哪条链、付给谁、这份报价多久失效。推断字段名在不同实现与版本间略有出入,以你选用的 SDK 文档为准;下面是概念示意:
The server returns a structured set of payment requirements inside the 402: how much, which asset, which network, who gets paid, and how long the quote is good for. inference Exact field names vary a little across implementations and versions, so follow your SDK's docs; the shape below is illustrative:
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"accepts": [{
"scheme": "exact",
"network": "base",
"asset": "USDC",
"maxAmountRequired": "1000", // 最小单位 / smallest unit
"payTo": "0xYourPayoutAddress",
"resource": "https://api.example.com/weather",
"maxTimeoutSeconds": 60
}]
}客户端读懂后构造签名载荷,base64 编码放进 X-PAYMENT 头重发原请求。服务端在放行前把这个头交给 facilitator 的 /verify;返回给客户端的 200 里带 X-PAYMENT-RESPONSE,里面是结算凭据(交易哈希等)。
The client builds a signed payload, base64-encodes it into the X-PAYMENT header, and retries the original request. Before serving, the server hands that header to the facilitator's /verify; the 200 that goes back carries X-PAYMENT-RESPONSE with the settlement receipt (transaction hash and so on).
x402 把付款塞在请求头里,这就要求:客户端只出一个签名,由别人代为提交上链,而且事先不需要 approve 额度。EVM 上恰好有这么一个标准——EIP-3009 的 transferWithAuthorization,USDC 实现了它。事实 不支持 EIP-3009 的普通 ERC-20 走 Permit2 路线。
x402 puts the payment in a request header, which requires that the client produce only a signature, that someone else submits it on-chain, and that no allowance is set up beforehand. On EVM there is exactly one standard for that — EIP-3009's transferWithAuthorization, which USDC implements. fact Plain ERC-20s without EIP-3009 go through Permit2 instead.
不是「没有 gas」,而是付款方不出 gas。用户/agent 只做链下签名,由 facilitator 这个 relayer 掏 gas 把交易打上链。这也意味着:agent 的钱包里只需要有稳定币,不需要持有原生代币——对一个自动创建的 agent 钱包来说,这个差别是「能不能用」的级别。推断
Not "no gas" — the payer pays no gas. The user or agent only signs off-chain, and the facilitator, acting as a relayer, pays the gas to land the transaction. Which also means the agent's wallet needs only stablecoins, not the chain's native token — for an automatically provisioned agent wallet that difference is the difference between usable and not. inference
facilitator 把「懂区块链」这件事从服务端剥离出去,分两个阶段:
The facilitator takes "knowing about blockchains" off the server's plate, in two phases:
| 阶段 | 时机 | 做什么 | 失败会怎样 |
|---|---|---|---|
/verify | 业务逻辑执行之前 | 校验 EIP-3009 签名、检查付款方余额、比对付款参数是否与报价一致 | 服务端拒绝请求,不执行业务逻辑 |
/settle | 响应发回客户端之后(异步) | 把签名提交上链,执行实际转账 | 钱没到账,但资源已经给出去了 |
| Phase | When | What it does | What failure means |
|---|---|---|---|
/verify | Before the handler runs | Validates the EIP-3009 signature, checks the payer's balance, confirms the payment parameters match the quote | Server rejects the request and never runs the handler |
/settle | After the response is sent (async) | Submits the signature on-chain and executes the actual transfer | The money never arrives — but the resource has already been handed over |
Coinbase 通过 CDP 提供公共 facilitator,覆盖 Base、Solana、Stellar,免费。事实 你也可以自建 facilitator——代价是你要自己处理 RPC、nonce、gas 与重试。
Coinbase runs public facilitators through CDP for Base, Solana, and Stellar, at no cost. fact You can also self-host one — at the cost of owning RPC access, nonces, gas, and retries yourself.
最小接入是一行中间件:声明收款地址和每条路由的价格。中间件负责在没有 X-PAYMENT 头时返回 402,在有的时候完成验证再让 handler 执行。
The minimum integration is one middleware line: declare your payout address and a price per route. The middleware returns a 402 when there is no X-PAYMENT header, and verifies before letting the handler run when there is.
import express from "express";
import { paymentMiddleware } from "@x402/express";
const app = express();
app.use(paymentMiddleware(
"0xYourPayoutAddress", // 收款地址 / payout address
{ "/weather": "$0.001" } // 每次调用 0.001 美元 / $0.001 per call
));
app.get("/weather", (req, res) => {
// 走到这里说明支付已验证通过
// reaching here means the payment already verified
res.json({ tempC: 21, city: "Shanghai" });
});
app.listen(3000);中间件默认在 /verify 通过后就放行 handler,而 /settle 是响应之后才发生的。也就是说,「已验证」不等于「已到账」。对于单次成本很低的只读接口这没问题;对于每次调用要烧掉几秒 GPU 的接口,你需要自己决定是否等结算确认——这正是「白嫖算力」那篇论文的攻击面。
By default the middleware lets the handler run once /verify passes, while /settle happens after the response. So "verified" is not "settled". For cheap read-only endpoints that's fine; for an endpoint that burns seconds of GPU per call, you have to decide for yourself whether to wait for settlement — which is precisely the attack surface in the free-riding paper.
模式很清晰:tools/list 保持免费(否则 agent 连你有什么工具都不知道,更不会付钱),把付费工具的 tools/call 挡在 402 后面。Vercel 的 x402-mcp 是 mcp-handler 的薄封装,支持定义带价格的 paidTools;FlowMCP 的 x402-mcp-middleware 是 Express 兼容的网关型实现,在缺少支付签名头时查工具的价格元数据、构造 402 信封(链、资产、金额、收款方、nonce 窗口)返回。
The pattern is clean: keep tools/list free (otherwise the agent never learns what you sell, let alone pays for it), and gate tools/call for priced tools behind a 402. Vercel's x402-mcp is a thin wrapper over mcp-handler that lets you declare paidTools with prices; FlowMCP's x402-mcp-middleware is an Express-compatible gateway that, when the payment signature header is missing, looks up the tool's price metadata and returns a 402 envelope (chain, asset, amount, recipient, nonce window).
// 概念示意 / conceptual sketch
paidTools: {
"generate_report": {
price: "$0.05",
network: "base",
handler: async (args) => { /* ... */ }
}
}
// tools/list 免费:agent 先看得见,才谈得上买
// tools/list stays free: the agent must see it before it can buy it客户端 SDK 通常包装成一个 fetch 拦截器:遇到 402 → 读报价 → 对照策略 → 签名 → 自动重发。「对照策略」这一步是你必须自己写的部分,至少要有:单次上限、单会话累计上限、允许的收款地址白名单或允许的资产/网络白名单、以及重复付款的去重键。
Client SDKs typically wrap this as a fetch interceptor: see a 402 → read the quote → check it against policy → sign → retry automatically. The "check against policy" step is the part you must write yourself, and it needs at minimum: a per-call cap, a per-session cumulative cap, an allowlist of payee addresses or of assets and networks, and a dedupe key for repeat payments.
恶意的 402 服务端可以回一个虚高的价格、一个伪造的 facilitator 地址、或者一个循环重定向来触发反复微支付。没有花费策略的 agent 没有任何断路器。这不是理论——它是 Halborn 与多篇论文共同点名的头号风险。
A malicious 402 server can return an inflated price, a falsified facilitator address, or a looping redirect that triggers repeated micropayments. An agent with no spending policy has no circuit breaker at all. This isn't theoretical — it's the number-one risk named by both Halborn and multiple papers.
2026 年的代理支付格局大致落定为四个协议,它们大体互补而非互斥——搞混它们是最常见的选型错误。
By 2026 the agentic-payments landscape settled into four protocols, and they are largely complementary rather than competing — confusing them is the most common selection mistake.
| 协议 | 主导方 | 解决什么 | 典型场景 |
|---|---|---|---|
| x402 | Coinbase(x402 基金会,与 Cloudflare 共治) | 执行层:按次结算,钱怎么当场付 | API、数据、算力、内容的按请求付费 |
| AP2 | 授权层:agent 有没有权限代表用户花这笔钱;它是框架不是支付轨道 | 商家 / 支付机构 / 用户三方之间的意图与授权证明 | |
| ACP | OpenAI + Stripe(规范开源,beta) | 商务层:agent 在商家处完成结账的交互模型 | 商品 feed、支付委托、订单生命周期(如 ChatGPT Instant Checkout) |
| MPP | — | 会话层:基于 session 的机器花费 | 一段持续交互内的额度管理 |
| Protocol | Driven by | What it solves | Typical use |
|---|---|---|---|
| x402 | Coinbase (x402 Foundation, co-governed with Cloudflare) | Execution layer: per-request settlement — how the money actually moves, now | Pay-per-request for APIs, data, compute, content |
| AP2 | Authorization layer: whether an agent had permission to spend on the user's behalf; a framework, not a payment rail | Proof of intent and authorization across merchant / PSP / user | |
| ACP | OpenAI + Stripe (open spec, in beta) | Commerce layer: the interaction model for an agent checking out at a merchant | Product feeds, payment delegation, order lifecycle (e.g. ChatGPT Instant Checkout) |
| MPP | — | Session layer: session-based machine spending | Budget management across a continuing interaction |
适合 x402:单价极低(几厘到几分)、调用方是软件而非人、资源是可即时交付的数字产品(一次 API 响应、一段数据、一次推理)、你不想也不需要建账号体系。
Good fit for x402: very low unit price (fractions of a cent up), the caller is software rather than a person, the resource is a deliverable-on-the-spot digital good (one API response, one dataset, one inference), and you neither want nor need an account system.
不适合 x402:需要退款、争议处理、发票与合规凭证的交易(链上转账天然不可逆);单笔金额大到值得攻击的场景;涉及实物商品与履约周期的电商(那是 ACP 的地盘);需要向监管解释「这笔钱是谁授权的」(那是 AP2 要回答的问题)。推断
Poor fit for x402: transactions that need refunds, dispute resolution, invoices, or compliance receipts (on-chain transfers are inherently irreversible); amounts large enough to be worth attacking; e-commerce with physical goods and fulfillment windows (that's ACP's territory); anything where you must explain to a regulator who authorized the spend (that's AP2's question to answer). inference
这是本文最该被读完的一节。2026 年围绕 x402 出现了一批安全研究,共同结论是:协议在设计与实现两个层面都存在可利用的弱点,而这些弱点的根源是那条「同步授权 + 异步结算」的缝。
This is the section most worth finishing. A cluster of 2026 security research on x402 converges on one conclusion: the protocol is exploitable at both the design and the implementation level, and the root cause is that "synchronous authorization plus asynchronous settlement" seam.
论文《Five Attacks on x402 Agentic Payment Protocol》给出五个具体攻击,覆盖授权、绑定、重放保护、Web 层处理四个薄弱面。被点名的攻击类别包括:
"Five Attacks on x402 Agentic Payment Protocol" presents five concrete attacks across four weak spots — authorization, binding, replay protection, and web-layer handling. The named classes include:
《Free-Riding the Agentic Web》指出这条缝会同时坑两边:逻辑缺陷让请求方消耗算力却不付钱,结算缺陷让商家收了钱却不干活。论文观察到,早期部署里前者更常见——因为 Web 服务倾向于优先保证客户体验和响应速度,于是在「资金真正落定之前就开始干活」这件事上留出了窗口。
"Free-Riding the Agentic Web" shows the seam cuts both ways: logic flaws let requesters consume compute without paying, and settlement flaws let merchants collect funds without delivering work. The paper observes that in early deployments the former dominates, because web services err toward customer experience and speed — which opens a window where compute starts before funds are truly secured.
如果你的付费接口每次调用成本可观(GPU 推理、第三方转发计费、长时间任务),不要在 /verify 通过后就无条件开工。可选做法:对高成本操作等待结算确认;或先返回一个便宜的「任务已受理」响应,等结算落定后再执行;或对同一付款方设置未结算敞口上限。
If each call to your paid endpoint costs real money (GPU inference, metered third-party calls, long jobs), do not start work unconditionally the moment /verify passes. Options: wait for settlement confirmation on expensive operations; return a cheap "accepted" response first and execute after settlement lands; or cap the unsettled exposure you'll carry for any one payer.
《Hardening x402: PII-Safe Agentic Payments via Pre-Execution Metadata Filtering》关注一个容易忽略的点:支付流转的元数据里可能夹带个人信息,方案是在执行前对元数据做过滤。推断对国内团队而言,这条和数据出境、个人信息保护的合规要求直接相关,接入前值得先过一遍法务。
"Hardening x402: PII-Safe Agentic Payments via Pre-Execution Metadata Filtering" targets an easily missed issue: payment metadata can carry personal information, and the proposal is to filter it before execution. inference For teams under privacy regimes like GDPR or China's PIPL, this maps directly onto data-transfer and personal-information rules, and is worth a legal review before you integrate.
X-PAYMENT-RESPONSE 凭据,便于对账与事后取证;链上转账不可逆,对账是唯一的补救入口。X-PAYMENT-RESPONSE receipt for reconciliation and forensics — on-chain transfers are irreversible, so reconciliation is your only remedy.| 项 | 情况 | 日期 / 口径 |
|---|---|---|
| 累计交易量 | Base 逾 1.19 亿笔,Solana 3500 万笔;年化约 6 亿美元;协议层零手续费 | 截至 2026-03(Chainalysis)事实 |
| 版本 | 白皮书 2025-05-06;V2 于 2025-12 发布 | —事实 |
| 支持网络 | Base、Ethereum、Arbitrum、Polygon、Solana;CDP 公共 facilitator 覆盖 Base / Solana / Stellar | 2026事实 |
| 治理 | x402 基金会,由 Coinbase 与 Cloudflare 共治 | 2026事实 |
| 主要集成 | Stripe(2026-02,Base 上)、Cloudflare Workers、Solana 原生开发工具、World 的 AgentKit | 2026事实 |
| 最新推进 | Cloudflare 在 Agents Week 随 Kitesurf 一起上线 x402 支持,20+ 家公司参与 agent 发起的支付流 | 2026-08-06 前后事实 |
| Item | Status | Date / basis |
|---|---|---|
| Cumulative volume | 119M+ transactions on Base, 35M on Solana; ~$600M annualized; zero protocol fees | as of Mar 2026 (Chainalysis)fact |
| Versions | Whitepaper 2025-05-06; V2 shipped Dec 2025 | —fact |
| Networks | Base, Ethereum, Arbitrum, Polygon, Solana; CDP public facilitators cover Base / Solana / Stellar | 2026fact |
| Governance | x402 Foundation, co-governed by Coinbase and Cloudflare | 2026fact |
| Notable integrations | Stripe (Feb 2026, on Base), Cloudflare Workers, Solana native dev tooling, World's AgentKit | 2026fact |
| Most recent move | Cloudflare shipped x402 support alongside Kitesurf during Agents Week, with 20+ companies in agent-initiated payment flows | around 2026-08-06fact |
怎么读这组数字 推断:1.19 亿笔配 6 亿美元年化,意味着平均单笔金额极小——这与「按 API 请求付费」的画像一致,而不是电商。换句话说,x402 目前跑的是机器与机器之间的微支付,而不是人在买东西。判断它是否成功,应该看有多少真实服务把价格挂上去,而不是看交易笔数——笔数在微支付里很容易被少数高频循环撑起来。
How to read these numbers inference: 119M transactions against ~$600M annualized implies a very small average ticket — consistent with pay-per-API-request, not with retail. In other words, what x402 is running today is machine-to-machine micropayments, not people buying things. The honest success metric is how many real services have put a price up, not transaction count — in micropayments, count is easily inflated by a handful of high-frequency loops.
| 术语 | 含义 |
|---|---|
| x402 | 基于 HTTP 402 状态码的开放支付协议,由 Coinbase Developer Platform 提出。 |
| facilitator | 中继方。负责验签(/verify)与上链结算(/settle),让服务端不必自己接区块链。 |
EIP-3009 / transferWithAuthorization | 以太坊标准,允许用户只出签名、由第三方提交转账,无需事先 approve 额度。USDC 实现了它。 |
| Permit2 | 面向不支持 EIP-3009 的 ERC-20 的替代授权方案。 |
| gasless | 付款方不出 gas,由 relayer(facilitator)代付。不是「没有 gas」。 |
X-PAYMENT | 客户端重发请求时携带的头,内含 base64 编码的签名付款授权。 |
X-PAYMENT-RESPONSE | 服务端在成功响应里回给客户端的结算凭据。 |
| bearer credential | 「持有即有效」的凭据。谁拿到都能用,因此必须自己做重放防护。 |
| AP2 / ACP / MPP | 分别是 Google 的授权框架、OpenAI+Stripe 的商务结账协议、基于 session 的机器花费协议。 |
| Term | Meaning |
|---|---|
| x402 | An open payment protocol built on the HTTP 402 status code, originated by Coinbase Developer Platform. |
| facilitator | The relay. Handles signature verification (/verify) and on-chain settlement (/settle) so the server never touches a blockchain. |
EIP-3009 / transferWithAuthorization | An Ethereum standard letting a user produce only a signature while a third party submits the transfer, with no prior allowance. USDC implements it. |
| Permit2 | The alternative authorization path for ERC-20 tokens that don't support EIP-3009. |
| gasless | The payer pays no gas; a relayer (the facilitator) covers it. Not "no gas exists." |
X-PAYMENT | The header the client attaches on retry, carrying a base64-encoded signed payment authorization. |
X-PAYMENT-RESPONSE | The settlement receipt the server returns inside a successful response. |
| bearer credential | A credential valid for whoever holds it. Anyone who intercepts it can use it, so replay protection is on you. |
| AP2 / ACP / MPP | Google's authorization framework, OpenAI+Stripe's merchant checkout protocol, and a session-based machine-spending protocol, respectively. |
本文所有事实性陈述均来自以下公开来源;标注「推断」的是作者基于这些来源做出的判断,请自行验证。
Every factual claim above comes from the public sources below; anything tagged "inference" is the author's reading of them and should be verified independently.