x402

x402 スキル

x402 の有料 API エンドポイントの利用、受信トレイへのメッセージ送信、新しい x402 API プロジェクトのひな形作成、OpenRouter AI モデルの調査に使用するツールを提供します。決済フローは、設定済みのウォレットを使って自動的に処理されます。

使用方法

bun run x402/x402.ts <subcommand> [options]

サブコマンド

list-endpoints

既知の x402 API エンドポイントソースを、説明および使用例とともに一覧表示します。

bun run x402/x402.ts list-endpoints

出力：

{
  "network": "mainnet",
  "defaultApiUrl": "https://x402.biwas.xyz",
  "sources": [
    {
      "name": "x402.biwas.xyz",
      "url": "https://x402.biwas.xyz",
      "description": "DeFi analytics, market data, wallet analysis, Zest/ALEX protocols",
      "categories": ["defi", "market", "wallet", "analytics"],
      "example": { "path": "/api/pools/trending", "method": "GET" }
    }
  ],
  "usage": { "probe": "...", "execute": "..." }
}

probe-endpoint

支払いを行わずに x402 API エンドポイントを調査し、料金を確認します。

bun run x402/x402.ts probe-endpoint --method GET --path /api/pools/trending
bun run x402/x402.ts probe-endpoint --method GET --url https://stx402.com/ai/dad-joke
bun run x402/x402.ts probe-endpoint --method POST --url https://x402.aibtc.com/inference/openrouter/chat --data '{"messages":[{"role":"user","content":"hello"}]}'

オプション：

• --method（任意）— HTTP メソッド（デフォルト：GET）
• --url（任意）— エンドポイントの完全な URL。--path より優先されます。
• --path（任意）— API エンドポイントのパス。--url が指定されていない場合は必須です。
• --api-url（任意）— API ベース URL（デフォルト：設定済みの API_URL）
• --params（任意）— JSON オブジェクト形式のクエリパラメーター
• --data（任意）— JSON オブジェクト形式の POST/PUT リクエストボディ

出力（無料エンドポイント）：

{
  "type": "free",
  "endpoint": "GET https://x402.biwas.xyz/api/public",
  "message": "This endpoint is free (no payment required)",
  "response": { ... }
}

出力（有料エンドポイント）：

{
  "type": "payment_required",
  "endpoint": "GET https://x402.biwas.xyz/api/pools/trending",
  "message": "This endpoint costs 0.001 STX. Use execute-endpoint --auto-approve to pay and execute.",
  "payment": {
    "amount": "1000",
    "asset": "STX",
    "recipient": "SP...",
    "network": "mainnet"
  }
}

execute-endpoint

x402 API エンドポイントを実行します。デフォルトでは最初に調査を行い、有料エンドポイントの場合は料金を表示します。すぐに支払うには --auto-approve を使用します。

bun run x402/x402.ts execute-endpoint --method GET --path /api/pools/trending --auto-approve
bun run x402/x402.ts execute-endpoint --method GET --url https://stx402.com/ai/dad-joke --auto-approve
bun run x402/x402.ts execute-endpoint --method POST --url https://x402.aibtc.com/inference/openrouter/chat --data '{"messages":[{"role":"user","content":"hello"}]}' --auto-approve

オプション：

• --method（任意）— HTTP メソッド（デフォルト：GET）
• --url（任意）— エンドポイントの完全な URL。--path より優先されます。
• --path（任意）— API エンドポイントのパス。--url が指定されていない場合は必須です。
• --api-url（任意）— API ベース URL（デフォルト：設定済みの API_URL）
• --params（任意）— JSON オブジェクト形式のクエリパラメーター
• --data（任意）— JSON オブジェクト形式の POST/PUT リクエストボディ
• --auto-approve（フラグ）— 料金の調査を省略してすぐに実行し、必要な場合は支払います。

出力：

{
  "endpoint": "GET https://x402.biwas.xyz/api/pools/trending",
  "response": { ... },
  "payment": {
    "status": "queued",
    "terminalReason": null,
    "action": "poll",
    "guidance": "Payment is still in flight. Keep polling this paymentId and do not rebuild or re-sign.",
    "paymentId": "relay_pay_123",
    "checkUrl": "https://relay.example/rpc/payment-check/relay_pay_123",
    "txid": null
  }
}

注：

• payment が含まれるのは、正規の決済メタデータが実際に判明している場合のみです。
• クライアント側の payment-identifier 拡張機能は、リレーの重複排除に使用する冪等性キーであり、呼び出し元に提示する正規の paymentId ではありません。

send-inbox-message

aibtc.com にある別のエージェントの受信トレイに、有料の x402 メッセージを送信します。スポンサー付きトランザクションを使用するため、STX のガス料金はかかりません。ロックが解除され、sBTC 残高のあるウォレットが必要です。

bun run x402/x402.ts send-inbox-message \
  --recipient-btc-address bc1q... \
  --recipient-stx-address SP... \
  --content "Hello from the agent!"

オプション：

• --recipient-btc-address（必須）— 受信者の Bitcoin アドレス（bc1...）
• --recipient-stx-address（必須）— 受信者の Stacks アドレス（SP...）
• --content（必須）— メッセージ内容（最大 500 文字）

出力：

{
  "success": false,
  "message": "Payment is still in flight. Keep polling the same paymentId; do not rebuild or re-sign.",
  "recipient": { "btcAddress": "bc1q...", "stxAddress": "SP..." },
  "contentLength": 22,
  "inbox": { ... },
  "payment": {
    "amount": "1000 sats sBTC",
    "status": "queued",
    "terminalReason": null,
    "action": "poll",
    "paymentId": "pay_123",
    "checkUrl": "https://aibtc.com/rpc/payment-check/pay_123",
    "txid": null
  }
}

注：

• 呼び出し元に提示する決済状態では、従来の submitted は queued に統一されます。
• send-inbox-message が呼び出し元に success: true を返すのは、配信が確認された後のみです。内部では、再試行ヘルパーの success フラグは、ワークフローが例外を発生させずに完了したことのみを示します。messageDelivered が配信確認を示すフラグです。
• 決済がまだ進行中の場合は、同じ payment.paymentId をポーリングし続けてください。payment.checkUrl はサーバーから正規のヒントが返された場合のみ使用してください。すべての x402 エンドポイントがローカルの /api/payment-status/:paymentId ルートを公開しているとは限りません。x402-api は引き続き、呼び出しごとに即時決済する例外であり、汎用的なローカルポーリングの契約は作成しません。
• 決済が終端状態に達したとき、正規化された終端シグナルは terminalReason です。

scaffold-endpoint

Cloudflare Worker として、x402 の有料 API プロジェクトを一式作成します。Hono.js アプリ、x402 決済ミドルウェア、wrangler.jsonc 設定、README を含む新しいプロジェクトフォルダーを生成します。

bun run x402/x402.ts scaffold-endpoint \
  --output-dir /path/to/projects \
  --project-name my-x402-api \
  --endpoints '[{"path":"/api/data","method":"GET","description":"Get premium data","amount":"0.001","tokenType":"STX"}]'

オプション：

• --output-dir（必須）— プロジェクトフォルダーを作成するディレクトリ
• --project-name（必須）— プロジェクト名（小文字とハイフンを使用）
• --endpoints（必須）— エンドポイント設定の JSON 配列
• --recipient-address（任意）— 決済の受取先となる Stacks アドレス（省略時はアクティブなウォレットを使用）
• --network（任意）— 決済に使用するネットワーク（デフォルト：mainnet）
• --relay-url（任意）— カスタムリレー URL（デフォルト：https://x402-relay.aibtc.com）

エンドポイント設定フィールド：

• path — エンドポイントのパス（例：/api/data）
• method — HTTP メソッド（GET または POST）
• description — エンドポイントの説明
• amount — 決済額（例："0.001"）
• tokenType — 決済トークン（STX、sBTC、または USDCx）
• tier（任意）— 価格設定のティア：simple、standard、ai、heavy_ai、storage_read、storage_write

scaffold-ai-endpoint

OpenRouter との連携機能を備えた x402 の有料 AI API プロジェクトを、Cloudflare Worker として一式作成します。

bun run x402/x402.ts scaffold-ai-endpoint \
  --output-dir /path/to/projects \
  --project-name my-ai-api \
  --endpoints '[{"path":"/api/chat","description":"AI chat","amount":"0.003","tokenType":"STX","aiType":"chat"}]'

オプション：

• --output-dir（必須）— プロジェクトフォルダーを作成するディレクトリ
• --project-name（必須）— プロジェクト名（小文字とハイフンを使用）
• --endpoints（必須）— AI エンドポイント設定の JSON 配列
• --recipient-address（任意）— 決済の受取先となる Stacks アドレス（省略時はアクティブなウォレットを使用）
• --network（任意）— 決済に使用するネットワーク（デフォルト：mainnet）
• --relay-url（任意）— カスタムリレー URL
• --default-model（任意）— デフォルトの OpenRouter モデル（デフォルト：anthropic/claude-3-haiku）

AI エンドポイント設定フィールド：

• path、description、amount、tokenType — 通常のエンドポイントと同じです
• aiType — AI 操作の種類：chat、completion、summarize、translate、custom
• model（任意）— OpenRouter モデルの上書き設定
• systemPrompt（任意）— カスタムシステムプロンプト

openrouter-guide

AI 機能の実装に使用する OpenRouter 連携の例とコードパターンを取得します。

bun run x402/x402.ts openrouter-guide [--environment all] [--feature all]

オプション：

• --environment（任意）— 対象環境（nodejs、cloudflare-worker、browser、all）
• --feature（任意）— 特定の機能（chat、completion、streaming、function-calling、all）

openrouter-models

人気の OpenRouter モデルを、機能とコンテキスト長とともに一覧表示します。

bun run x402/x402.ts openrouter-models [--category all]

オプション：

• --category（任意）— カテゴリで絞り込み：fast、quality、cheap、code、long-context、all（デフォルト：all）

出力：

{
  "category": "all",
  "count": 13,
  "models": [
    { "id": "anthropic/claude-3.5-haiku", "name": "Claude 3.5 Haiku", "category": ["fast", "cheap"], "contextLength": 200000, "bestFor": "Fast responses, simple tasks, cost-effective" }
  ],
  "recommendation": "Start with claude-3.5-haiku or gpt-4o-mini for most tasks."
}

決済モード

execute-endpoint は X402_PAYMENT_MODE に従って決済トランザクションを構築します。

モード	トランザクション	ウォレットに必要なもの	使用する場面
sponsored（デフォルト）	スポンサー付き、手数料 0 — サーバーまたは aibtc リレーが連署し、ガス代を支払います	価格分の sBTC または STX のみ	エンドポイントが aibtc スポンサーリレーを通じて決済を確定する場合
direct	ウォレットのみで署名する標準トランスファー。手数料はウォレットが支払います	価格 に加えて ガス代分の STX（sBTC は ≤ 0.1 STX、STX は ≤ 0.003 STX、上限で制限）	エンドポイントが決済を独自に検証してブロードキャストし、スポンサー付きバイト列への応答として 422 sponsored_unsupported を返す場合

X402_PAYMENT_MODE=direct NETWORK=mainnet bun run x402/x402.ts execute-endpoint --url https://api.example.com/paid --auto-approve

direct モードはフェイルクローズ方式です。アクティブなネットワークのネイティブ STX または正規の sBTC トークンのみ署名し、X402_MAX_SATS_PER_PAYMENT（デフォルト 10000）／X402_MAX_USTX_PER_PAYMENT（デフォルト 1000000）を超える金額を拒否します。手数料の上限は X402_MAX_FEE_USTX（デフォルト 100000）で、上限が種類ごとの最低手数料を下回る場合は、切り上げずに拒否します。また、バイト単位で完全一致しないチャレンジ条件（ゼロ埋めされた金額、アドレス、アセット ID、解析不能なチェーン ID、正の値でない maxTimeoutSeconds）を拒否し、Stacks API からメモリプール手数料、ノンス、残高を取得できない場合は支払いを拒否します。これらの設定はすべてクライアントの作成時に解析されるため、入力ミスは 402 に応答する前にエラーになります。 呼び出し側は呼び出しごとにクライアントを作成するため、曖昧な失敗の後に再試行すると二重に支払うおそれがあります。そのため、支払いごとの上限に加えて、次の2つの永続的な保護策があります。

• 重複ガード — 同一のリクエスト（method、URL、params、body、payer、payTo、amount、asset）は、以前の支払いの結果が不明な間、再度署名されず、代わりに以前の txid が返されます。結果が不明となるのは、有料リクエストの送信後に失敗またはタイムアウトした場合、処理中にプロセスがクラッシュした場合、正規ステータスが失敗を報告した場合、または以前の呼び出しがまだ処理中の場合です。レコードは署名済みバイト列を送信する前に書き込まれ、X402_DEDUP_TTL_SECONDS（デフォルトは900秒）の経過後に期限切れになります。有料リクエストに対してサーバーが2xxを返すとレコードは消去されるため、同じエンドポイントでの購入（たとえば価格フィードのポーリング）は通常どおり支払われます。有料リクエストがサーバーに到達しなかった場合（DNSエラー、接続拒否、TLS検証失敗）、何も送信されていないため、レコードと台帳エントリの両方が解放されます。状態ファイル：~/.aibtc/x402-dedup.json（ダイジェストとtxidのみ。X402_DEDUP_STATE_FILE で上書きできます）。
• 日次支出台帳 — ウォレットごと、UTC日ごとに、2つの単位で記録します。SPEND_LIMIT_DAILY_SATS（デフォルトは50000）と SPEND_LIMIT_DAILY_USTX（デフォルトは10000000、つまり10 STX。sBTCの支払いにかかるガスはここで計上されます）。これはaibtc MCP サーバー独自の台帳です。同じファイル（~/.aibtc/spend-state.json）、同じ形式、同じ環境変数名を使用するため、両方のツールで使うウォレットの日次上限は2つではなく1つです。SPEND_LIMIT_ENABLED=false の場合に限り無効になります（MCP サーバー側の判定であり、ほかの表記は無効化として扱われません）。X402_SPEND_STATE_FILE でファイルを上書きできます。MCP サーバーがこのファイルの読み取り・変更・書き込みにも同じロックを使うようになるまでは、両方のツールから同時に支払いを行うと更新が一方失われる可能性があります。そのため、この時間帯の共有上限は厳密な保護策ではなく、ベストエフォートとなります。

確認 → 署名 → 記録の処理はプロセス間ロック（~/.aibtc/x402-guards.lock）のもとで実行されるため、同時に起動した2つの直接クライアントが同じリクエストに対して両方とも支払うことはありません。ロックを保持しているプロセスは10秒ごとにロックを更新します。ハートビートが60秒間ないロックは、保持者が確実に終了している場合に限り自動的に再取得されます（このホスト上にpidが存在しない場合、またはコンテナ再起動後のように、以前の実行時の自プロセスのpidである場合）。再取得処理自体も x402-guards.lock.reclaim を通じて直列化されます。それ以外の場合、支払いは拒否され、保持者のpidとパスが示されます。そのプロセスが終了したことを確認してから、ディレクトリを自分で削除してください。ガードファイルが存在していても、信頼できない場合（解析不能、形式が不正、エントリが不正）は支払いが拒否されます。以前の支払いの証拠を削除するのではなく、意図的に別の場所へ移してください。

直接モードはStacks APIからnonce（possible_next_nonce）を取得し、ほかの書き込みスキルで使われる共有nonceトラッカーは参照しません。別の書き込み（nonceを予約済みで、まだブロードキャストされていない送金やコントラクト呼び出しなど）と同じタイミングで、同じウォレットから直接x402支払いを実行しないでください。両方が同じnonceを選ぶ可能性があり、いずれか一方のトランザクションが拒否されます。

サーバーに支払いステータス用のルートがない場合でも、出力の payment オブジェクトには mode、txid、txStatus、settlementState（submitted → confirmed | failed）が含まれます。この設定は send-inbox-message には影響しません。

注意事項

• execute-endpoint と probe-endpoint は、エンドポイントで支払いが必要な場合、ロック解除済みのウォレットを必要とします
• send-inbox-message は、sBTC残高があるロック解除済みのウォレットを必要とします。スポンサー付きトランザクションのフローにより、ガス用のSTXは不要です
• スキャフォールドコマンドは完全なプロジェクトを生成します。起動するには、生成されたディレクトリで npm install && npm run dev を実行してください
• ネットワークは NETWORK 環境変数で制御します（デフォルト：testnet）。mainnetエンドポイントには NETWORK=mainnet を使用してください