x402 Agent 技能

当您的 AI 代理遇到 HTTP 402 Payment Required 响应时，自动检测并支付 x402 加密付费墙。

何时激活

当 HTTP 响应返回 状态码 402 Payment Required 且响应体包含带有描述支付选项的 accepts 数组的 x402Version 字段时，激活此技能。

检测模式：

• - HTTP 状态码：402
• 响应体：包含 x402Version（数字）和 accepts（支付需求数组）的 JSON
• 响应头：PAYMENT-REQUIRED（Base64 编码的支付需求）

如何使用

步骤 1：安装

bash
npm install @x402-kit/agent @x402-kit/shared

步骤 2：设置代理 Fetch 包装器

typescript
import { createAgentFetch } from @x402-kit/agent;

const agentFetch = createAgentFetch({
walletPrivateKey: process.env.X402WALLETPRIVATE_KEY as 0x${string},
network: eip155:8453, // Base 主网
policy: {
maxPerRequest: 1.00, // 每次请求最多 1 USDC
maxDailySpend: 10.00, // 每天最多 10 USDC
allowedNetworks: [eip155:8453],
allowedAssets: [0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913], // Base 上的 USDC
requireHumanApproval: false,
},
logFilePath: ./x402-payments.jsonl,
});

步骤 3：作为直接替换的 Fetch 使用

typescript
// 像使用普通 fetch 一样使用 agentFetch
const response = await agentFetch(https://api.example.com/premium/data);
const data = await response.json();

内部工作流程

1. 1. 正常发起初始请求
2. 如果服务器返回带有 x402 支付需求的 HTTP 402，技能将：

1. 3. 如果策略拒绝支付，则返回原始 402 响应而不产生支出

配置

环境变量

策略配置

策略对象控制代理允许支出的内容：

typescript
interface X402Policy {
maxPerRequest: string; // 单次请求最大 USDC（例如 1.00）
maxDailySpend: string; // 每天最大 USDC（例如 10.00）
allowedNetworks: string[]; // CAIP-2 网络（例如 [eip155:8453]）
allowedAssets: string[]; // 代币合约地址
domainAllowlist?: string[]; // 仅支付这些域名（可选）
domainDenylist?: string[]; // 绝不支付这些域名（可选）
requireHumanApproval: boolean;
}

支持的网络

完整配置参考

typescript
interface AgentFetchConfig {
walletPrivateKey: Hex; // 来自环境变量：X402WALLETPRIVATE_KEY
policy: X402Policy; // 支出规则
network: Network; // CAIP-2 格式（例如 eip155:8453）
spendFilePath?: string; // 每日支出持久化（默认：.x402/daily-spend.json）
logFilePath?: string; // 支付日志文件路径
rpcUrl?: string; // 自定义 JSON-RPC URL
tokenDecimals?: number; // 代币小数位数（USDC 默认：6）
}

示例

基础：支付高级 API 数据

代理调用 api.example.com/premium，收到 402，支付 0.10 USDC，获取数据：

typescript
const agentFetch = createAgentFetch({
walletPrivateKey: process.env.X402WALLETPRIVATE_KEY as 0x${string},
network: eip155:8453,
policy: {
maxPerRequest: 0.50,
maxDailySpend: 5.00,
allowedNetworks: [eip155:8453],
allowedAssets: [0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913],
requireHumanApproval: false,
},
});

const response = await agentFetch(https://api.example.com/premium/weather);
// 第一次请求返回 402 -> 代理自动支付 0.10 USDC -> 重试 -> 获取 200 和数据

域名限制：仅支付受信任的 API

typescript
const agentFetch = createAgentFetch({
walletPrivateKey: process.env.X402WALLETPRIVATE_KEY as 0x${string},
network: eip155:8453,
policy: {
maxPerRequest: 1.00,
maxDailySpend: 20.00,
allowedNetworks: [eip155:8453],
allowedAssets: [0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913],
domainAllowlist: [api.trusted-service.com, data.partner.io],
requireHumanApproval: false,
},
});

测试网开发

typescript
const agentFetch = createAgentFetch({
walletPrivateKey: process.env.X402WALLETPRIVATE_KEY as 0x${string},
network: eip155:84532, // Base Sepolia 测试网
policy: {
maxPerRequest: 10.00,
maxDailySpend: 100.00,
allowedNetworks: [eip155:84532],
allowedAssets: [0x036CbD53842c5426634e7929541eC2318f3dCF7e], // Base Sepolia 上的 USDC
requireHumanApproval: false,
},
});

安全规则

1. 1. 绝不暴露私钥。 始终从环境变量加载 X402WALLETPRIVATE_KEY。切勿在源文件或日志中硬编码。
2. 遵守支出限制。 策略引擎强制执行每次请求和每日限制。为生产环境配置保守的限制。
3. 记录所有支付。 设置 logFilePath 以维护审计追踪。日志文件以 JSONL 格式记录每次支付尝试（批准、拒绝或失败）。
4. 使用域名过滤。 设置 domainAllowlist 或 domainDenylist 以限制代理可以支付的服务。
5. 从测试网开始。 在开发期间使用 Base Sepolia（eip155:84532）。仅在生产环境切换到主网（eip155:8453）。
6. 每日支出在 UTC 午夜重置。 支出跟踪器持久化到磁盘并每天自动重置。

支付日志格式

每个支付事件作为 JSON 行记录在日志文件中：

json
{
timestamp: 2026-02-27T12:00:00.000Z,
url: https://api.example.com/premium/data,
amount: 0.1,
asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913,
network: eip155:8453,
facilitator: ,
success: true,
policyDecision: approved
}