区块链

外观

X402 协议 ​

基于 HTTP 402（Payment Required）的程序化支付协议，用于让 API、服务与 AI Agent 能够在不建立账户关系的前提下，按请求进行链上结算。X402 并非为传统 Web3 DApp 登录或用户交互而设计，而是面向 机器优先（machine-first） 的互联网支付场景。

一句话定位（避免误解版） ​

X402 是为「AI Agent / 程序 ↔ API / 服务」提供的 HTTP 原生付费机制，而不是新一代 Web3 钱包登录方案。

  • ❌ 不是用来替代 Connect Wallet
  • ❌ 不是为普通用户网页体验优化
  • ❌ 不是订阅制 / 账户制支付
  • ✅ 是 按请求（pay-per-request）的机器可支付协议

适用场景（明确边界） ​

主要适用 ​

  • API 按次计费（数据接口、行情、搜索、分析）
  • AI Agent 调用外部能力（模型推理、工具、插件）
  • 程序化微支付（毫秒级 / 次级定价）
  • 无账户服务售卖（无需注册、无需 API Key）

非设计目标 ​

  • 普通 Web3 DApp 登录
  • NFT / DeFi / GameFi 用户交互
  • 长期订阅 / 会员体系
  • 面向人的复杂前端支付 UX

设计理念 ​

X402 的核心思想是：

把“付费”变成 HTTP 协议的一部分，而不是应用层逻辑。

  • 使用标准 HTTP 状态码 402 Payment Required
  • 不引入新网络、不修改浏览器
  • 客户端（包括 AI Agent）可自动理解价格并决定是否支付

这使得 机器也能像人一样“看价格 → 决策 → 付款 → 重试”。

参与角色 ​

角色说明
Client（买家）程序、AI Agent 或受控的钱包客户端
Resource Server（卖家）提供 API / 内容 / 服务的 HTTP 服务端
Facilitator可选的支付撮合与结算方，负责验证签名并提交链上交易

Facilitator 可以是 Coinbase Developer Platform 提供的托管服务，也可以是自建实现。

网络与资产 ​

  • 协议本身链无关（chain-agnostic）

  • 常见生产配置：

    • Base 主网 + USDC（CAIP-2: eip155:8453）
    • 测试：Base Sepolia（eip155:84532）

  • EVM 网络通常基于 EIP-3009（transferWithAuthorization）

  • Solana 使用 SPL / Token-2022 的交易或授权模型

核心语义（非固定 Header 名） ​

下列为 语义概念，具体 Header 名称可能因实现而异。

  • Payment Required Metadata 卖家在 402 响应中返回的支付要求，包含：

    • 可接受的网络 / 资产
    • 金额与定价说明
    • 支付方案（scheme）

  • Payment Authorization Payload 客户端选择方案后，生成的一次性支付授权签名，用于证明“我愿意为这次请求付费”。

  • Payment Receipt Metadata 卖家在支付验证/结算成功后返回的回执信息，用于标识该请求已完成支付。

完整交互流程（真实语义） ​

  1. Client 请求资源
  2. Resource Server 返回 402 Payment Required，并附带支付要求
  3. Client 选择一种支付方案
  4. Client 使用钱包对支付授权进行签名（必须显式签名）
  5. Client 携带支付授权重新请求资源
  6. Server 本地验证或委托 Facilitator 验证并结算
  7. 结算成功后返回资源与支付回执

⚠️ 链上结算通常由 Facilitator 异步提交，HTTP 层关注的是“是否接受该支付授权”。

安全模型（非常重要） ​

私钥与钱包 ​

  • 私钥永远不应离开钱包

  • X402 使用的是：

    • 离线签名
    • 一次性授权
    • 金额 / 接收方 / 有效期受限

任何要求用户粘贴私钥或助记词的 X402 实现，都是错误或恶意的。

关于钱包弹窗 ​

  • 所有合法的 X402 支付授权：

    • ✅ 必须唤起钱包
    • ✅ 必须用户/Agent 明确确认
    • ❌ 不允许静默扣费

卖家快速开始（Express 示例） ​

以下示例展示如何为 HTTP 资源增加“按请求付费”能力。

ts
import express from 'express'
import { paymentMiddleware } from '@x402/express'

const app = express()

app.use(
  paymentMiddleware({
    'GET /weather': {
      description: 'Weather data (pay-per-request)',
      accepts: [], // 具体支付方案由实现或 Facilitator 提供
    },
  }),
)

app.get('/weather', (_, res) => {
  res.json({ ok: true })
})

app.listen(4021)

买家示例（⚠️ 重要说明） ​

⚠️ 以下示例仅适用于 AI Agent / Server-side Wallet 场景 ❌ 不适用于浏览器端普通用户

ts
import { createWalletClient, http } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { baseSepolia } from 'viem/chains'
import { wrapFetchWithPayment } from 'x402-fetch'

// Agent / Server-side wallet only
const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`)

const wallet = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
})

const fetchWithPay = wrapFetchWithPayment(fetch, wallet)

const res = await fetchWithPay('https://api.example.com/weather')
const data = await res.json()

浏览器用户应使用 注入式钱包（MetaMask / Coinbase Wallet / Phantom） 进行签名。

Facilitator 的真实作用 ​

Facilitator 不是中心化支付商，而是：

  • 验证支付授权签名
  • 防止重放与重复结算
  • 提交链上交易并确认
  • 向卖家提供确定性的结算结果

使用 托管 Facilitator 的好处：

  • 卖家无需直接处理链上交易
  • 更稳定的结算与重试机制
  • 降低链上与安全实现成本

最佳实践 ​

  • 明确资源定价与单位（如：0.01 USDC / request）
  • 为 Client 设置最大可支付额度与次数
  • 将 X402 作为 付费闸门，支付成功后可下发短期访问凭证
  • AI Agent 场景下，结合 session key / delegation 使用

常见误解澄清（FAQ） ​

X402 是不是新的钱包连接方式？ ​

不是。X402 解决的是 “如何为一次 HTTP 请求付费”，不是身份登录。

X402 会不会暴露私钥？ ​

不会。私钥只用于本地签名，从不发送给服务端或 Facilitator。

为什么不用订阅制？ ​

因为 AI Agent / 程序化调用需要：

  • 动态定价
  • 按次决策
  • 即时结算

这是订阅制无法满足的。

总结 ​

如果你的用户是“人”，X402 可能不是你需要的；如果你的调用方是“程序或 AI Agent”，X402 正是为此而生。

X402 并不试图重塑 Web3 UX，而是在为 下一代机器互联网 补上一块长期缺失的支付基础设施。

基于 MIT 许可发布

Copyright © 2025-present MOFAN