跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt

Use this file to discover all available pages before exploring further.

​
什麼是 x402？

x402 是一個圍繞 HTTP 402 Payment Required 建構的機器對機器支付協議。它讓 AI 代理能夠自動支付 API 存取費用，無需人工介入。AgentWallex 實作了 x402 v2，搭配 EIP-3009 授權酬載。

​
x402 v2 標頭

該協議使用三個 HTTP 標頭：
標頭方向用途
PAYMENT-REQUIRED伺服器到用戶端含定價資訊的 402 挑戰
PAYMENT-SIGNATURE用戶端到伺服器已簽名的付款酬載
PAYMENT-RESPONSE伺服器到用戶端結算確認

​
付款流程

Client Agent               Paid API               AgentWallex
    |                        |                         |
    |-- GET /resource ------>|                         |
    |<-- 402 + PAYMENT-REQUIRED                        |
    |                        |                         |
    |-- POST /api/v1/x402/pay -----------------------> |
    |                        |     (sign + policy)     |
    |<-- payment_info        |                         |
    |                        |                         |
    |-- GET /resource + PAYMENT-SIGNATURE -----------> |
    |<-- 200 + PAYMENT-RESPONSE                        |
1

代理請求資源

代理向付費 API 端點發送標準 HTTP 請求。
2

伺服器回傳 402

API 回應 HTTP 402 和 PAYMENT-REQUIRED 標頭，包含定價詳情（金額、代幣、區塊鏈、payTo 地址）。
3

代理透過 AgentWallex 付款

代理將付款詳情發送至 POST /x402/pay。AgentWallex 評估策略並簽署付款。
4

代理附帶付款證明重試

代理使用附加的 PAYMENT-SIGNATURE 標頭重試原始請求。
5

伺服器驗證並回應

API 驗證付款簽名（透過 AgentWallex facilitator）並回傳資源。

​
使用 x402 API

​
檢查 URL 是否支援 x402

curl -X POST https://api.agentwallex.com/api/v1/x402/check \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paid-api.example.com/v1/data"}'

​
建立工作階段預算

工作階段讓您可以為重複的 API 呼叫預先授權支出預算： 
curl -X POST https://api.agentwallex.com/api/v1/x402/sessions \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_uuid",
    "budget_limit": "100.00",
    "chain": "eip155:84532",
    "ttl_seconds": 3600,
    "allowed_urls": ["https://paid-api.example.com/v1/data"]
  }'

​
觸發付款協商

curl -X POST https://api.agentwallex.com/api/v1/x402/pay \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_uuid",
    "target_url": "https://paid-api.example.com/v1/data",
    "session_id": "optional_session_uuid",
    "chain": "eip155:84532"
  }'
回應包含 payment_info，其中包括：
欄位說明
ledger_id內部帳本記錄 ID
amount付款金額
fee_amount扣除的平台費用
fee_rate套用的費率百分比
token使用的代幣（例如 USDC）
chain用於結算的區塊鏈
status付款狀態

​
SDK 整合

​
自動 HTTP 攔截器

TypeScript SDK 提供了一個自動處理完整 x402 流程的攔截器： 
const fetchWithPayment = aw.x402.httpInterceptor({
  agentId: "agent_abc123",
  chain: "eip155:84532",
});

// This automatically handles 402 challenges
const response = await fetchWithPayment("https://paid-api.example.com/v1/data");
const data = await response.json();

​
手動流程

// 1. Create a session budget
const session = await aw.x402.createSession({
  agentId: "agent_abc123",
  budgetLimit: "100.00",
  chain: "eip155:84532",
  ttlSeconds: 3600,
  allowedUrls: ["https://paid-api.example.com/v1/data"],
});

// 2. Pay for an API call
const result = await aw.x402.pay({
  agentId: "agent_abc123",
  targetUrl: "https://paid-api.example.com/v1/data",
  sessionId: session.id,
  chain: "eip155:84532",
});

// 3. Or pay using the session directly
await aw.x402.sessionPay(session.id, {
  targetUrl: "https://paid-api.example.com/v1/data",
});

​
給服務供應商

如果您提供付費 API，您的伺服器在缺少付款時應回傳 x402 v2 挑戰。

​
回傳 402 與 PAYMENT-REQUIRED

將 JSON 挑戰（base64）編碼到 PAYMENT-REQUIRED 標頭中： 
{
  "x402Version": 2,
  "resource": "https://your-api.com/v1/data",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "0.10",
      "asset": "USDC",
      "payTo": "0xYourAddress",
      "maxTimeoutSeconds": 300
    }
  ]
}

​
驗證與結算

使用 AgentWallex facilitator 端點： 
# Verify a payment signature
POST /api/v1/x402/facilitator/verify

# Settle a verified payment
POST /api/v1/x402/facilitator/settle

# Query supported chains
GET /api/v1/x402/facilitator/supported

​
運作預設值

參數值
結算間隔300 秒
結算門檻$10.00
最大結算延遲3,600 秒
支援的區塊鏈eip155:84532, eip155:8453, eip155:1, eip155:137