x402 支払いプロトコル は何をしますか？
x402 は、402 Payment Required ステータスコードを使用して、HTTP 経由で即座にステーブルコインの支払いを可能にします。AIエージェントがオンデマンドでAPI、データ、またはコンピューティングリソースの支払いを行うのに最適です。
クイックスタート
SDKのインストール
npm install x402
# または
pnpm add x402
環境設定
# ウォレットの秘密鍵を安全に保存
# Store wallet private key securely
export WALLET_PRIVATE_KEY="0x..."
# オプション: ネットワークRPCを指定
# Optional: specify network RPC
export BASE_RPC_URL="https://mainnet.base.org"
x402の仕組み
- リクエスト → クライアントが有料APIを呼び出す
- 402レスポンス → サーバーが
PAYMENT-REQUIREDヘッダーに支払い詳細を返す - 支払いと再試行 → クライアントが支払いに署名し、
PAYMENT-SIGNATUREヘッダー付きで再試行する - アクセス → サーバーが検証し、決済して、リソースを返す
x402クライアントの使用
TypeScript/Node.js
import { x402Client } from 'x402';
const client = x402Client({
privateKey: process.env.WALLET_PRIVATE_KEY,
network: 'base', // または 'ethereum', 'arbitrum' など
});
// 自動402処理
// Automatic 402 handling
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は自動処理
// Use like normal fetch - 402s handled automatically
const res = await fetch402('https://paid-api.com/data');
手動フロー (curl)
ステップ 1: 支払い要件を発見
curl -i https://api.example.com/paid-resource
# 402とPAYMENT-REQUIREDヘッダー（base64 JSON）を返す
# Returns 402 with PAYMENT-REQUIRED header (base64 JSON)
ステップ 2: 支払い詳細をデコード
# PAYMENT-REQUIREDヘッダーにはbase64エンコードされたJSONが含まれます:
# {
# "amount": "1000000", # 1 USDC (6桁)
# "currency": "USDC",
# "network": "base",
# "recipient": "0x...",
# "scheme": "exact"
# }
ステップ 3: 署名して支払い
# x402 CLIまたはSDKを使用して支払い署名を作成
# Use x402 CLI or SDK to create payment signature
npx x402 pay \
--amount 1000000 \
--recipient 0x... \
--network base
ステップ 4: 証明書付きで再試行
curl -H "PAYMENT-SIGNATURE: <base64_payload>" \
https://api.example.com/paid-resource
一般的なパターン
APIコールの支払い
// 1回の呼び出しに0.001 USDCかかる天気API
// Weather API that costs 0.001 USDC per call
const weather = await client.fetch('https://weather-api.x402.org/forecast?city=NYC');
AI推論の支払い
// トークンごとの価格設定のLLM API
// LLM API with per-token pricing
const completion = await client.fetch('https://llm.example.com/v1/chat', {
method: 'POST',
body: JSON.stringify({ prompt: 'Hello' }),
});
支払い前に残高を確認
import { getBalance } from 'x402';
const balance = await getBalance({
address: walletAddress,
network: 'base',
token: 'USDC',
});
if (balance < requiredAmount) {
console.log('USDC残高が不足しています');
// console.log('Insufficient USDC balance');
}
サポートされているネットワーク
| ネットワーク | チェーンID | ステータス |
|---|---|---|
| Base | 8453 | ✅ プライマリ |
| Ethereum | 1 | ✅ サポート |
| Arbitrum | 42161 | ✅ サポート |
| Optimism | 10 | ✅ サポート |
| Polygon | 137 | ✅ サポート |
支払いスキーム
- exact: 固定額を支払う（例：API呼び出しごとに$0.01）
- upto: 使用量に基づいて最大額まで支払う（例：LLMトークン）
- subscription: セッションを使用したウォレットベースのアクセス（V2）
エラーハンドリング
try {
const res = await client.fetch(url);
} catch (err) {
if (err.code === 'INSUFFICIENT_BALANCE') {
// ウォレットに資金を入れる必要がある
// Need to fund wallet
} else if (err.code === 'PAYMENT_FAILED') {
// オンチェーンでトランザクションが失敗
// Transaction failed on-chain
} else if (err.code === 'INVALID_PAYMENT_REQUIREMENTS') {
// サーバーが不正な402レスポンスを送信した
// Server sent malformed 402 response
}
}
セキュリティに関する注意
- 秘密鍵をログやチャットに絶対に公開しないでください
- ウォレットの認証情報には環境変数を使用してください
- シークレットインジェクションには
op runなどを使用することを推奨します - 大規模なトランザクションを確認する前に支払い金額を確認してください
V2機能（2025年12月）
- ウォレットベースのID: セッションを使用して呼び出しごとに再支払いをスキップ
- 自動発見: APIは
/.well-known/x402で支払いメタデータを公開 - マルチファシリテーター: 支払い処理業者を選択可能
- CAIP標準: ユニバーサルチェーン/アセット識別子