x402 Wallet

@three-ws/x402-mcp

あらゆる AI エージェントにセルフカストディ型の x402 ウォレットを提供します。自分の Solana キーを使って、USDC で有料サービスを検索、確認、支払いできます。

---

あらゆる AI アシスタントを、x402 ネットワーク上の自律的な経済エージェントに変える Model Context Protocol サーバーです。稼働中のマーケットプレイスで有料サービスを検索し、支払いを確定する前にエンドポイントの価格を確認してから、USDC で任意の x402 サービスに pay_and_call できます。Solana 上で自分のキーを使って決済します。カストディアルウォレットは使用しません。

これは、three.ws のエージェント経済における 購入者 側です。支払いのやり取りと Solana の exact スキームによる署名には、実際の @x402/* ライブラリを使用しており、モックは一切ありません。

インストール

npm install @three-ws/x402-mcp

または、npx で実行します。

SOLANA_SECRET_KEY=<base58> npx @three-ws/x402-mcp

クイックスタート

Claude Code の場合は、1 行です。

claude mcp add x402 --env SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/x402-mcp

Claude Desktop / Cursor の場合（claude_desktop_config.json または mcp.json）：

{
	"mcpServers": {
		"x402": {
			"command": "npx",
			"args": ["-y", "@three-ws/x402-mcp"],
			"env": {
				"SOLANA_SECRET_KEY": "<base58 secret of the wallet that holds USDC>",
				"SOLANA_RPC_URL": "https://your-rpc-provider",
				"MAX_PAY_USD": "1"
			}
		}
	}
}

SOLANA_SECRET_KEY が必要なのは、支払いを行う場合（pay_and_call と、デフォルトでウォレットを使用する x402_wallet）のみです。find_services と inspect_endpoint はキーなしで使用できます。

ツール

ツール	種類	説明
x402_wallet	読み取り専用	ウォレットのアドレスと、リアルタイムの SOL／USDC 残高です。デフォルトでは署名者のウォレットを使用します。支払い前に資金を確認してください。
find_services	読み取り専用	ライブの x402 バザール（PayAI + Coinbase CDP）を検索し、価格付きの有料 HTTP／MCP サービスを探します。
inspect_endpoint	読み取り専用	任意のエンドポイントの 402 支払い要件（方式、ネットワーク、アセット、価格、支払先）を、支払いなしで確認します。
pay_and_call	実行	Solana キーを使ってエンドポイントへの支払いを USDC で行い、結果を返します。MAX_PAY_USD によって上限が設定されます。
spending_report	読み取り専用	pay_and_call と以下の名前付きツールが支払った金額の合計を、販売者別、日別に表示します。

さらに、固定の three.ws x402 サービスごとに 1 つ、合計 17 個の名前付きツールがあります。各ツールは、正しく呼び出す場合、pay_and_call(url) を直接組み立てるよりもモデルにとって低コストです。

ツール	価格	エンドポイント
weather_forecast	$0.001	/api/x402/weather-guard-forecast
weather_go_no_go	$0.002	/api/x402/weather-guard-decision
carbon_now	$0.001	/api/x402/carbon-now
carbon_best_window	$0.002	/api/x402/carbon-best-window
domain_rdap_check	$0.001	/api/x402/domains-check
domain_rdap_check_bulk	$0.005	/api/x402/domains-bulk
research_search	$0.002	/api/x402/research-search
research_paper	$0.003	/api/x402/research-paper
research_bibliography	$0.005	/api/x402/research-bibliography
book_search	$0.001	/api/x402/books-search
book_read	$0.01	/api/x402/books-read
news_wire_search	$0.003	/api/x402/news-wire-query
news_wire_poll	$0.002	/api/x402/news-wire-pulse
transit_plan	$0.002	/api/x402/transit-plan
transit_delays	$0.001	/api/x402/transit-delays
places_search	$0.002	/api/x402/places-search
places_detail	$0.002	/api/x402/places-detail

各ツールは対応するエンドポイントと同じ引数を受け取り（完全なスキーマについては src/tools.json を参照）、pay_and_call と同じ SOLANA_SECRET_KEY／session_token の決済モードで支払います。また、同じ MAX_PAY_USD 上限と REQUIRE_CONFIRM フラグが適用されます。必要なエンドポイントに対応する名前付きツールがある場合は、pay_and_call よりもそちらを優先してください。固定スキーマと明示された価格により、モデルが誤った呼び出し方をする可能性を大幅に抑えられます。

安全性

pay_and_call には destructiveHint: true が設定されているため、注釈に対応したクライアント（Claude Code、Claude Desktop、Cursor）では実行前に確認を求めます。クライアント側のヒントに加え、すべての支払いにはサーバー側で上限が設定されています。まず 402 を照会し、価格が max_usd または MAX_PAY_USD（デフォルトは $1）を超える場合は、資金が移動する前に拒否します。また、REQUIRE_CONFIRM が有効（デフォルト）な場合、confirm: true を指定して再発行するまで呼び出しは拒否されます。決済されるのは、制御下にあるキーを使った Solana（solana:*）の exact 方式の要件のみです。

入力パラメーター

x402_wallet — address（任意のbase58形式。デフォルトは署名者のウォレットです）。

find_services — query（必須）、type（http | mcp、デフォルトは http）、network（CAIP-2フィルター）、max_price_usdc、limit（1～100）。

inspect_endpoint — url（必須）、method（GET | POST）、body（オブジェクト）。

pay_and_call：url（必須）、method（GET | POST）、body（オブジェクト）、max_usd（この呼び出しの上限を引き下げます）、secret（呼び出しごとの署名者の上書き）、confirm（REQUIRE_CONFIRM が有効な場合は true が必須です）、session_token、token、idempotency_key。

決済方式は2種類あります。

• セルフカストディ（デフォルト）。 SOLANA_SECRET_KEY または呼び出しごとの secret で署名します。秘密鍵はご自身で管理します。
• セッション管理。 three.ws Payment Session のトークンである session_token を渡すと、プラットフォームウォレットがお客様に代わって署名し、そのセッションの予算、ホストの許可リスト、トランザクションごとの上限を適用します。秘密鍵は不要です。Solana USDC と Base USDC のセッションをどちらも利用でき、このモードでは secret と token は無視されます。

token では決済アセットを選択します。usdc（デフォルト）、またはエンドポイントが対応している場合はプラットフォームトークンの $THREE を指定する three です。idempotency_key は呼び出しの重複を防ぎます。再試行による二重課金を防ぐため、session_token と併用することを推奨します。

例

// inspect_endpoint — what does it cost? (no payment)
> { "url": "https://three.ws/api/x402/vanity?prefix=ab" }
{
  "ok": true, "paid": true,
  "accepts": [
    { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "asset": "EPjFW…", "price": 50000 }
  ],
  "payable_with_this_wallet": true
}

// pay_and_call — confirm:true required by default
> { "url": "https://three.ws/api/x402/vanity?prefix=ab", "confirm": true }
{ "ok": true, "paid": true, "payer": "Gx5E…", "price_usd": 0.05, "settlement": { … }, "result": { … } }

使用例

決済なしで実行できるサンプルは examples/ にあります。

node examples/list-tools.mjs      # every tool with its full input schema
node examples/inspect-price.mjs   # find_services + inspect_endpoint on live data

どちらもこのサーバーをstdio経由で起動し、実際のbazaarにアクセスします。どちらもキーを読み取ったり、pay_and_call を呼び出したりしないため、署名も支払いも発生しません。期待される出力については examples/README.md を参照してください。

プロトコルのバージョン

pay_and_call は、同じSolanaキーで2種類のx402ワイヤーフォーマットに対応しています。v2（CAIP-2のネットワーク文字列。例：solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp）と、v1（フラット形式のネットワーク文字列。例：solana）です。オープンなx402 bazaarの大半や、元の x402／x402-fetch パッケージを基盤とするサービスでは、現在も後者の形式が使われています。販売者が両方を提示している場合は、常にv2が優先されます。決済レシートは、どちらのバージョンで支払った場合も同じ形式（success、transaction、network、payer）で返されるため、後続の処理で使用したバージョンを把握する必要はありません。

要件

• Node.js >= 20。
• Solana mainnet RPCエンドポイント（https。開発環境では http://localhost のみ許可されます）。読み取りにはパブリッククラスターを利用できます。決済トラフィックには独自のエンドポイントをご用意ください。
• 支払いには、USDCを保有するSolanaウォレットが必要です。SOLANA_SECRET_KEY（base58形式）または呼び出しごとの secret として指定します。

環境変数

変数	必須	デフォルト
SOLANA_SECRET_KEY	支払い時のみ	—
SOLANA_RPC_URL	いいえ	https://api.mainnet-beta.solana.com
MAX_PAY_USD	いいえ	1
REQUIRE_CONFIRM	いいえ	true
THREE_WS_BASE	いいえ	https://three.ws
X402_MCP_LEDGER_PATH	いいえ	~/.three-ws/x402-mcp-ledger.jsonl

X402_MCP_LEDGER_PATH は、決済済みのすべての支払い（pay_and_call および名前付きツール）が記録される追記専用のJSON Linesファイルを指定します。spending_report はこのファイルを読み取ります。

リンク

• ホームページ：https://three.ws
• MCPカタログ：https://three.ws/docs/mcp
• 変更履歴：https://three.ws/changelog
• 問題の報告：https://github.com/nirholas/three.ws/issues
• ライセンス：Apache-2.0。LICENSE を参照してください。

---

_{3D AIエージェント、オンチェーンID、エージェント決済を提供するthree.ws SDKスイートの一部です。
ウェブサイト · 変更履歴 · GitHub}