x402 V2 刚刚发布：每位 AI Agent Builder 必须了解的 5 项安全变更

发布: 3天前 (2026年2月8日 GMT+8 06:44)

15 分钟阅读

Source: Dev.to

（请提供需要翻译的正文内容，我将为您翻译成简体中文，并保留原始的格式、Markdown 语法以及代码块和 URL。）

Source: …

x402 V2 有哪些变化

背景： x402 是基于 402 状态码的原生 HTTP 支付协议。它让 AI 代理可以在 HTTP 请求‑响应流程中直接为 API 调用付款——无需账户、无需重定向、无需订阅。Coinbase 推出了该协议，Cloudflare 将其集成，并在首几个月内处理了超过 1 亿笔支付流。

V2 是一次从头开始的重新架构。以下是五个关键变化。

1. 支付标识符标准化（基于 CAIP）

V2 使用 CAIP（链无关改进提案）统一网络和资产的标识方式。过去使用链特定的标识符，而现在有一种通用的支付格式，可在 Base、Solana、新兴 L2 以及传统渠道（如 ACH、SEPA）之间通用。

V2 之前： 每条链都有自定义的资产标识逻辑。新增链需要修改核心协议代码。
V2 之后： 资产和链统一使用相同的标识方式。

eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

标识 Base 上的 USDC。每条链都遵循相同的模式。

2. 动态 payTo 路由

这是最大的变化。V2 支持在每个请求中根据输入参数路由到不同的地址、角色或基于回调的支付逻辑。payTo 字段不再是静态的——它可以在每次请求时变化。

这使得市场平台和多租户 API 能够在每笔交易中更改收款方（例如，AI 代理调用某个市场平台的 API，底层提供者会根据查询内容而变化）。

3. 基于钱包的身份和会话访问

V2 引入了钱包控制的会话机制。代理在为资源付款后，可在后续访问时使用基于 CAIP‑122（Sign‑In‑With‑X）的会话跳过完整的付款流程。相同的数据不再需要二次付费。

这对需要重复调用同一 API 的代理尤为关键——如聊天补全、数据流、搜索端点等。

4. 模块化 SDK 架构

参考 SDK 重新从头编写，以实现模块化。链、资产和支付方案现在通过 @x402 npm 组织的插件进行注册。核心包 @x402/paywall 可完全抽离，并开箱即支持 EVM 与 Solana。

5. HTTP Header 现代化

V2 用符合标准的替代方案取代了已废弃的 X-* 头部：

PAYMENT-SIGNATURE
PAYMENT-REQUIRED
PAYMENT-RESPONSE

支付数据现在全部通过 HTTP 头部传递，而不再放在响应体中。

没有人在谈论的安全影响

每一次更改对协议而言都是净正面，但每一次也会改变威胁模型。以下是新的风险及其缓解措施。

动态 payTo 路由 → 接收方操纵攻击

在 V1 中，付款接收方是静态的。V2 中，payTo 地址可以在每个请求中变化——服务器告诉你的代理该把钱发送到哪里，代理便遵从。

攻击方式： 被攻陷或恶意的 API 在任意请求中返回一个不同的 payTo 地址。你的代理忠实地把资金发送到攻击者的钱包。响应仍然返回有效数据（可能是缓存的，也可能是生成的），因此代理看不出异常。

危险之处： 市场场景期望动态路由，这使得代理很难在没有明确白名单的情况下区分合法的新提供者地址和被攻击者注入的地址。

缓解措施

为每个 API 端点维护接收方白名单。 若 payTo 地址不在名单中，则拒绝付款。
记录每一个遇到的唯一 payTo 地址。 对首次出现的地址触发警报。
对于市场 API，要求提供者通过签名清单发布其地址集合。

// Recipient allowlist enforcement
const TRUSTED_RECIPIENTS = {
  'api.example.com': [
    'eip155:8453/erc20:0xABC...', // Primary treasury
    'eip155:8453/erc20:0xDEF...', // Operations wallet
  ],
};

function validateRecipient(host, payTo) {
  const allowed = TRUSTED_RECIPIENTS[host];
  if (!allowed || !allowed.includes(payTo)) {
    throw new PaymentSecurityError(
      `Untrusted recipient ${payTo} for ${host}. ` +
      `Allowed: ${allowed?.join(', ') || 'none configured'}`
    );
  }
}

基于钱包的身份 → 会话劫持风险

基于会话的访问意味着你的代理在首次付款后获得一个令牌，以后可重复使用该令牌访问资源。便利的同时，也成为了新的攻击目标。

攻击向量

会话令牌窃取 – 攻击者通过日志、中间件或被攻陷的中介捕获令牌，从而免费获取代理已付款的所有资源。
会话固定 – 攻击者在代理认证之前设置会话令牌，随后在代理付款后复用该令牌。
会话无限期 – 若未设置明确的过期时间，泄露的令牌将授予无限制访问；相反，代理可能持有本应被撤销的会话。

缓解措施

将会话令牌绑定到特定钱包地址 以及请求指纹（User‑Agent、IP 范围）。
设置激进的 TTL（存活时间）。 对于 AI 代理，15–30 分钟通常足够。
实现会话预算上限 – 即使拥有有效会话，也要对每个会话窗口的最大支出进行限制。

// Example session validation
function validateSession(token, walletAddress, req) {
  const payload = decodeSessionToken(token);
  if (payload.wallet !== walletAddress) {
    throw new SessionError('Wallet mismatch');
  }
  if (payload.ip !== req.ip || payload.ua !== req.headers['user-agent']) {
    throw new SessionError('Fingerprint mismatch');
  }
  if (Date.now() > payload.expiresAt) {
    throw new SessionError('Session expired');
  }
}

TL;DR AI 代理构建者检查清单

✅	操作
1	为每个端点保持一个受信任的 `payTo` 地址的静态白名单。
2	记录并在首次出现的 `payTo` 值上发出警报。
3	要求提供商发布用于动态路由的已签名地址清单。
4	将会话令牌绑定到钱包 + 请求指纹；强制使用短 TTL（15‑30 分钟）。
5	对每个会话应用支出上限，以限制令牌被盗造成的损害。
6	定期审计 SDK 插件，以防出现异常行为或过时的依赖。
7	监控 HTTP 头部（如 `PAYMENT‑SIGNATURE` 等）以发现异常或缺失的签名。

通过将 x402 V2 的新灵活性视为功能驱动的攻击面，您可以让 AI 代理既保持功能性又确保安全。祝构建愉快！

会话范围的预算强制执行

const sessionPolicy = {
  maxSessionDuration: 30 * 60 * 1000, // 30 minutes
  maxTransactionsPerSession: 100,
  maxSpendPerSession: 5.00,           // $5 USD equivalent
  requireWalletBinding: true,
  rotateTokenOnThreshold: 0.8,       // Rotate at 80% budget
};

function validateSession(session, transaction) {
  const age = Date.now() - session.createdAt;
  if (age > sessionPolicy.maxSessionDuration) {
    throw new SessionExpiredError('Session TTL exceeded');
  }
  if (session.totalSpend + transaction.amount > sessionPolicy.maxSpendPerSession) {
    throw new BudgetExceededError(
      `Session budget: $${sessionPolicy.maxSpendPerSession}. ` +
      `Current: $${session.totalSpend}. Requested: $${transaction.amount}`
    );
  }
}

模块化 SDK → 插件信任边界问题

V2 的插件架构允许任何人注册新的链、资产和支付方案。这虽然提升了可扩展性，但也为供应链攻击打开了大门。

攻击方式：
恶意插件如果以“支付方案”的形式注册，可能拦截交易数据、修改金额、重定向资金或窃取钱包密钥。由于插件运行在支付流程内部，它们可以访问所有相关信息。

应对措施

在安装前审计每个 @x402/* 插件。检查 npm 包的来源可信度。
锁定确切版本。对支付关键的包绝不要使用 ^ 或 ~ 版本范围。
尽可能在受限权限的隔离环境中运行支付插件。
监控插件注册表的拼写抢注（例如 @x4O2/paywall 与 @x402/paywall）。

CAIP 标识符 → 链混淆攻击

标准化的标识符本来很有用——直到攻击者利用了这种标准化。

攻击方式：
一个 API 在 eip155:8453（Base）上请求支付，但代理的钱包默认使用 eip155:1（以太坊主网），其 gas 费用高出 100 倍。更糟的是：标识符指向一个测试网链，代币毫无价值，却仍然让服务提供生产数据。

应对措施

保持显式的链白名单。仅允许代理已配置可操作的链。
验证请求的链是否与每个 API 端点预期的链相匹配。
对于在该上下文中代理未见过的任何链标识符进行标记。

标头迁移 → 检测盲点

将 X-PAYMENT 标头迁移到 PAYMENT-* 标头看似微小，但如果你的日志、监控或 WAF 规则仍然过滤旧的标头名称，在迁移期间就会出现检测空白。

该怎么做

在过渡期间，将所有监控规则更新为同时匹配旧的和新的标头模式。
测试你的日志管道，确保能够捕获 PAYMENT-SIGNATURE 和 PAYMENT-RESPONSE 标头。

综合示例：V2 安全策略引擎

所有这些风险背后的模式都是相同的：V2 为代理提供了更大的灵活性，这意味着代理需要更多的约束。 按路由的支出策略、收款人验证以及会话范围并非可选项——它们是最低要求。

// x402 V2 Security Policy Configuration
const v2SecurityPolicy = {
  global: {
    maxTransactionAmount: 1.00,          // $1 max per transaction
    dailySpendLimit: 50.00,              // $50/day across all APIs
    allowedChains: ['eip155:8453'],      // Base only
    allowedAssets: ['erc20:USDC'],
    blockTestnetPayments: true,
    requireRecipientAllowlist: true,
  },

  routes: {
    'api.example.com/v2/completions': {
      maxPerRequest: 0.10,
      dailyLimit: 10.00,
      allowedRecipients: ['eip155:8453/0xABC...'],
      sessionPolicy: {
        enabled: true,
        maxDuration: 1800,                // 30 min
        maxSpend: 5.00,
        bindToWallet: true,
      },
    },

    'marketplace.example.com/*': {
      maxPerRequest: 0.50,
      dailyLimit: 25.00,
      allowedRecipients: 'MANIFEST_VERIFIED', // Dynamic, but verified
      requireManifestSignature: true,
      alertOnNewRecipient: true,
    },
  },

  plugins: {
    allowedPackages: [
      '@x402/paywall@2.1.0',          // Pinned versions only
      '@x402/facilitator-base@2.1.0',
    ],
    blockUnverifiedPublishers: true,
    auditLogEnabled: true,
  },

  monitoring: {
    headerPatterns: [
      'PAYMENT-SIGNATURE',            // V2 headers
      'PAYMENT-REQUIRED',
      'PAYMENT-RESPONSE',
      'X-PAYMENT-*',                  // V1 legacy (transition)
    ],
    alertOn: [
      'new_recipient_address',
      'chain_mismatch',
      'session_budget_threshold',
      'unknown_plugin_loaded',
    ],
  },
};

像 PaySentry 这样的工具可以在 SDK 层强制执行这些策略，为你的 x402 客户端包装按路由的支出上限、收款人验证以及会话预算控制——无需修改代理的核心逻辑。

V2 迁移安全检查清单

测试网链标识符的交易

结论

x402 V2 是协议的一个重要进步。CAIP 标准化、动态路由和模块化 SDK 使其在大规模生产代理支付方面真正可行。

但每一种新功能都会带来新的攻击面。动态 payTo 意味着收款人操控。会话意味着会话劫持。插件意味着供应链攻击。这些并非理论上的假设——它们是为支付协议添加灵活性后自然产生的后果。

解决方案不是回避 V2，而是用同等细粒度的安全策略来匹配 V2 的灵活性。

x402 V2 刚刚发布：每位 AI Agent Builder 必须了解的 5 项安全变更

x402 V2 有哪些变化

1. 支付标识符标准化（基于 CAIP）

2. 动态 payTo 路由

3. 基于钱包的身份和会话访问

4. 模块化 SDK 架构

5. HTTP Header 现代化

没有人在谈论的安全影响

动态 payTo 路由 → 接收方操纵攻击

缓解措施

基于钱包的身份 → 会话劫持风险

攻击向量

缓解措施

TL;DR AI 代理构建者检查清单

会话范围的预算强制执行

模块化 SDK → 插件信任边界问题

CAIP 标识符 → 链混淆攻击

标头迁移 → 检测盲点

综合示例：V2 安全策略引擎

V2 迁移安全检查清单

测试网链标识符的交易

结论

相关文章

OwlPulse vs StatusCake vs Pingdom：正常运行时间监控比较 2025

UX/UI 排版

Claude Code 礼貌地请求。Aye Chat 默认采取行动。

运行低功耗 AI 服务器 24/7 — 我的 15W 以下配置