Kernel8901/ai-agent-skills-classification

x402 支付协议

x402 通过使用 402 Payment Required 状态码，直接在 HTTP 上实现即时稳定币支付。非常适合 AI 代理按需支付 API、数据或计算资源。

快速开始

安装 SDK

npm install x402
# 或
pnpm add x402

环境设置

# 安全存储钱包私钥
export WALLET_PRIVATE_KEY="0x..."

# 可选：指定网络 RPC
export BASE_RPC_URL="https://mainnet.base.org"

x402 工作原理

1. 请求 → 客户端调用付费 API
2. 402 响应 → 服务器在 PAYMENT-REQUIRED 头中返回支付详情
3. 支付并重试 → 客户端签名支付，使用 PAYMENT-SIGNATURE 头重试请求
4. 访问资源 → 服务器验证、结算，返回资源

使用 x402 客户端

TypeScript/Node.js

import { x402Client } from 'x402';

const client = x402Client({
  privateKey: process.env.WALLET_PRIVATE_KEY,
  network: 'base', // 或 'ethereum', 'arbitrum' 等
});

// 自动处理 402
const response = await client.fetch('https://api.example.com/paid-endpoint');
const data = await response.json();

使用 fetch 封装器

import { wrapFetch } from 'x402';

const fetch402 = wrapFetch(fetch, {
  privateKey: process.env.WALLET_PRIVATE_KEY,
});

// 像普通 fetch 一样使用 - 402 自动处理
const res = await fetch402('https://paid-api.com/data');

手动流程 (curl)

步骤 1：发现支付要求

curl -i https://api.example.com/paid-resource
# 返回 402，并包含 PAYMENT-REQUIRED 头 (base64 JSON)

步骤 2：解码支付详情

# PAYMENT-REQUIRED 头包含 base64 编码的 JSON：
# {
#   "amount": "1000000",      # 1 USDC (6 位小数)
#   "currency": "USDC",
#   "network": "base",
#   "recipient": "0x...",
#   "scheme": "exact"
# }

步骤 3：签名并支付

# 使用 x402 CLI 或 SDK 创建支付签名
npx x402 pay \
  --amount 1000000 \
  --recipient 0x... \
  --network base

步骤 4：携带证明重试

curl -H "PAYMENT-SIGNATURE: <base64_payload>" \
  https://api.example.com/paid-resource

常见模式

支付 API 调用

// 每次调用花费 0.001 USDC 的天气预报 API
const weather = await client.fetch('https://weather-api.x402.org/forecast?city=NYC');

支付 AI 推理

// 按 Token 计费的 LLM API
const completion = await client.fetch('https://llm.example.com/v1/chat', {
  method: 'POST',
  body: JSON.stringify({ prompt: '你好' }),
});

支付前检查余额

import { getBalance } from 'x402';

const balance = await getBalance({
  address: walletAddress,
  network: 'base',
  token: 'USDC',
});

if (balance < requiredAmount) {
  console.log('USDC 余额不足');
}

支持的网络

网络	链 ID	状态
Base	8453	✅ 主要
Ethereum	1	✅ 支持
Arbitrum	42161	✅ 支持
Optimism	10	✅ 支持
Polygon	137	✅ 支持

支付方案

• exact：支付固定金额（例如，每次 API 调用 $0.01）
• upto：根据使用量最多支付指定上限（例如，LLM Token）
• subscription：基于钱包的会话访问（V2）

错误处理

try {
  const res = await client.fetch(url);
} catch (err) {
  if (err.code === 'INSUFFICIENT_BALANCE') {
    // 需要为钱包充值
  } else if (err.code === 'PAYMENT_FAILED') {
    // 链上交易失败
  } else if (err.code === 'INVALID_PAYMENT_REQUIREMENTS') {
    // 服务器发送了格式错误的 402 响应
  }
}

安全注意事项

• 切勿在日志或聊天中暴露私钥
• 使用环境变量存储钱包凭据
• 优先使用 op run 或类似工具注入密钥
• 确认大额交易前检查支付金额

V2 功能 (2025 年 12 月)

• 基于钱包的身份：无需每次调用都重新支付，支持会话
• 自动发现：API 在 /.well-known/x402 公开支付元数据
• 多协调器：在多个支付处理商之间选择
• CAIP 标准：通用链/资产标识符

资源

• 规范：https://github.com/coinbase/x402
• 文档：https://docs.cdp.coinbase.com/x402
• 演示 API：https://www.x402.org