Back to Details

x402

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

x402 Payment Protocol

x402支付协议

Use the 
npx awal@latest x402
commands to discover, inspect, and call paid API endpoints using the X402 payment protocol. Payments are made in USDC on Base.
使用
npx awal@latest x402
命令，通过X402支付协议发现、查看并调用付费API端点。支付以Base网络上的USDC进行。

Workflow

工作流程

The typical x402 workflow is:
  1. Find a service - Search the bazaar or get details for a known endpoint
  2. Check requirements - Inspect price, method, and input schema
  3. Make the request - Call the endpoint with automatic USDC payment
典型的x402工作流程如下：
  1. 查找服务 - 搜索集市，或获取已知端点的详细信息
  2. 查看要求 - 检查价格、请求方法和输入 schema
  3. 发起请求 - 调用端点并自动完成USDC支付

Commands

命令

Search the Bazaar

搜索集市

Find paid services by keyword using BM25 relevance search:
bash
npx awal@latest x402 bazaar search <query> [-k <n>] [--force-refresh] [--json]
OptionDescription
-k, --top <n>
Number of results (default: 5)
--force-refresh
Re-fetch resource index from CDP API
--json
Output as JSON
Results are cached locally at 
~/.config/awal/bazaar/
and auto-refresh after 12 hours.
通过BM25相关性搜索，按关键词查找付费服务：
bash
npx awal@latest x402 bazaar search <query> [-k <n>] [--force-refresh] [--json]
选项描述
-k, --top <n>
结果数量（默认值：5）
--force-refresh
从CDP API重新获取资源索引
--json
以JSON格式输出
结果会缓存在本地
~/.config/awal/bazaar/
目录，12小时后自动刷新。

List Bazaar Resources

列出集市资源

Browse all available resources:
bash
awal x402 bazaar list [--network <network>] [--full] [--json]
OptionDescription
--network <name>
Filter by network (base, base-sepolia)
--full
Show complete details including schemas
--json
Output as JSON
浏览所有可用资源：
bash
awal x402 bazaar list [--network <network>] [--full] [--json]
选项描述
--network <name>
按网络筛选（base, base-sepolia）
--full
显示完整详情，包括schema
--json
以JSON格式输出

Discover Payment Requirements

了解支付要求

Inspect an endpoint's x402 payment requirements without paying:
bash
awal x402 details <url> [--json]
Auto-detects the correct HTTP method (GET, POST, PUT, DELETE, PATCH) by trying each until it gets a 402 response, then displays price, accepted payment schemes, network, and input/output schemas.
无需支付即可查看端点的x402支付要求：
bash
awal x402 details <url> [--json]
会自动检测正确的HTTP方法（GET、POST、PUT、DELETE、PATCH），直到获取到402响应，然后显示价格、支持的支付方案、网络以及输入/输出schema。

Make a Paid Request

发起付费请求

Call an x402 endpoint with automatic USDC payment:
bash
awal x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]
OptionDescription
-X, --method <method>
HTTP method (default: GET)
-d, --data <json>
Request body as JSON string
-q, --query <params>
Query parameters as JSON string
-h, --headers <json>
Custom HTTP headers as JSON string
--max-amount <amount>
Max payment in USDC atomic units (1000000 = $1.00)
--correlation-id <id>
Group related operations
--json
Output as JSON
调用x402端点并自动完成USDC支付：
bash
awal 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>
自定义HTTP头（JSON字符串格式）
--max-amount <amount>
最大支付金额（USDC原子单位，1000000 = $1.00）
--correlation-id <id>
分组相关操作
--json
以JSON格式输出

Examples

示例

bash
undefined
bash
undefined

Search for weather-related paid APIs

搜索天气相关的付费API

awal x402 bazaar search "weather"
awal x402 bazaar search "weather"

Search with more results

搜索并获取更多结果

awal x402 bazaar search "sentiment analysis" -k 10
awal x402 bazaar search "sentiment analysis" -k 10

Check what an endpoint costs

查看端点的费用

awal x402 details https://example.com/api/weather
awal x402 details https://example.com/api/weather

Make a GET request (auto-pays)

发起GET请求（自动支付）

awal x402 pay https://example.com/api/weather
awal x402 pay https://example.com/api/weather

Make a POST request with body

发起带请求体的POST请求

awal x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'
awal x402 pay https://example.com/api/sentiment -X POST -d '{"text": "I love this product"}'

Limit max payment to $0.10

将最大支付金额限制为0.10美元

awal x402 pay https://example.com/api/data --max-amount 100000
awal x402 pay https://example.com/api/data --max-amount 100000

Browse all bazaar resources with full details

浏览集市所有资源并查看完整详情

awal x402 bazaar list --full
undefined
awal x402 bazaar list --full
undefined

USDC Amounts

USDC金额

X402 uses USDC atomic units (6 decimals):
Atomic UnitsUSD
1000000$1.00
100000$0.10
50000$0.05
10000$0.01
X402使用USDC原子单位（6位小数）：
原子单位美元
1000000$1.00
100000$0.10
50000$0.05
10000$0.01

Prerequisites

前提条件

  • Search/Details: No authentication needed
  • Pay: Must be authenticated (
    awal auth login <email>
    ) with sufficient USDC balance (
    awal balance
    )
  • 搜索/查看详情：无需认证
  • 支付：必须完成认证（
    awal auth login <email>
    ），且USDC余额充足（可通过
    awal balance
    查看）

Error Handling

错误处理

  • "Not authenticated" - Run 
    awal auth login <email>
    first
  • "No X402 payment requirements found" - URL may not be an x402 endpoint
  • "CDP API returned 429" - Rate limited; cached data will be used if available
  • "Insufficient balance" - Fund wallet with USDC (
    awal balance
    to check)
  • "Not authenticated" - 先运行
    awal auth login <email>
  • "No X402 payment requirements found" - 该URL可能不是x402端点
  • "CDP API returned 429" - 触发速率限制；若有缓存数据则使用缓存
  • "Insufficient balance" - 为钱包充值USDC（可通过
    awal balance
    查看余额）