x402

x402 支付协议

使用 npx [email protected] x402 命令，通过 X402 支付协议发现、检查并调用付费 API 端点。使用 USDC 在 Base 上付款。

工作流

典型的 x402 工作流如下：

1. 查找服务 - 搜索市集，或获取已知端点的详情
2. 检查要求 - 检查价格、方法和输入架构
3. 发送请求 - 调用端点并自动使用 USDC 付款

命令

搜索市集

使用 CDP 的向量搜索，按关键词查找付费服务：

npx [email protected] x402 bazaar search <query> [-k <n>] [--network <network>] [--scheme <scheme>] [--max-price <price>] [--json]

选项	描述
-k, --top <n>	结果数量，1–20（默认值：20）
--network <name>	按链筛选（base、base-sepolia、polygon、solana、solana-devnet）
--scheme <scheme>	按支付方案筛选：exact 或 upto
--max-price <price>	最高价格（美元）（例如 0.01）
--asset <address>	按支付资产地址筛选
--pay-to <address>	按收款钱包地址筛选
--extensions <type>	按扩展类型筛选（例如 outputSchema、bazaar）
--json	以 JSON 格式输出

列出市集资源

浏览所有可用资源：

npx [email protected] x402 bazaar list [--network <network>] [--full] [--refresh] [--json]

选项	描述
--network <name>	按链筛选（base、base-sepolia、polygon、solana、solana-devnet）
--full	显示完整详情，包括架构
--refresh	从 CDP API 重新获取资源索引
--json	以 JSON 格式输出

发现支付要求

在不付款的情况下检查端点的 x402 支付要求：

npx [email protected] x402 details <url> [--json]

通过逐一尝试各个 HTTP 方法（GET、POST、PUT、DELETE、PATCH），自动检测正确的方法，直到收到 402 响应，然后显示价格、接受的支付方案、网络以及输入/输出架构。

发送付费请求

调用 x402 端点并自动使用 USDC 付款：

npx [email protected] x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]

选项	描述
-X, --method <method>	HTTP 方法（默认值：GET）
-d, --data <json>	JSON 字符串格式的请求正文
-q, --query <params>	JSON 字符串格式的查询参数
-h, --headers <json>	JSON 字符串格式的自定义 HTTP 标头
--max-amount <amount>	USDC 最小单位的最高支付金额（1000000 = $1.00）
--correlation-id <id>	对相关操作进行分组
--json	以 JSON 格式输出

示例

# Search for weather-related paid APIs
npx [email protected] x402 bazaar search "weather"

# Search with more results
npx [email protected] x402 bazaar search "sentiment analysis" -k 10

# Check what an endpoint costs
npx [email protected] x402 details https://example.com/api/weather

# Make a GET request (auto-pays)
npx [email protected] x402 pay https://example.com/api/weather

# Make a POST request with body
npx [email protected] x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'

# Limit max payment to $0.10
npx [email protected] x402 pay https://example.com/api/data --max-amount 100000

# Browse all bazaar resources with full details
npx [email protected] x402 bazaar list --full

USDC 金额

X402 使用 USDC 最小单位（6 位小数）：

最小单位	美元
1000000	$1.00
100000	$0.10
50000	$0.05
10000	$0.01

前置条件

• 搜索/详情：无需身份验证
• 付款：必须通过身份验证（npx [email protected] auth login <email>），并确保 USDC 余额充足（npx [email protected] balance）

错误处理

• “未通过身份验证”——请先运行 npx [email protected] auth login <email>
• “未找到 X402 付款要求”——该 URL 可能不是 x402 端点
• “CDP API 返回 429”——请求受到速率限制；如果有缓存数据，将使用缓存数据
• “余额不足”——请为钱包充值 USDC（运行 npx [email protected] balance 查看余额）