MCP Agentic Wallet — open-source session management for x402

MCP Agentic Wallet

AI エージェント向けの、オープンソースの EIP-2612 Permit ベースのウォレットセッションです。 有料 MCP サーバーのリファレンス実装です。署名を検証し、セッションを管理し、オンチェーンで決済します。API キーも、定期的な課金もありません。

これは何か

人が暗号資産ウォレットを接続し、1 回限りの EIP-2612 Permit に署名すると（ガスレスのため、トランザクション手数料はかかりません）、セッショントークンを受け取ります。AI エージェントはこのトークンを MCP リクエストで使用し、Base 上の USDC でツール呼び出しの料金を支払います。サーバーは transferFrom を介して、各呼び出しをオンチェーンで決済します。

API キーは不要です。定期的な課金もありません。呼び出しごとのウォレット署名も不要です。 Permit がポリシーとなります。

これは、MCP サーバー向けの x402 決済ファシリテーターである mcpvot.xyz で使用されているリファレンス実装です。オープンソースのコア（@mcp-agentic-wallet/core）はフレームワークに依存せず、あらゆる MCP サーバーや Next.js アプリで動作します。

クイックスタート

1. コアライブラリをインストールする

npm install @mcp-agentic-wallet/core viem

2. MCP サーバーで使用する

import { InMemoryStore, settleCall } from '@mcp-agentic-wallet/core';

const store = new InMemoryStore();

// In your MCP tool handler:
const token = req.headers.get('Session-Token');
const session = store.getSession(token);
if (!session) return new Response('Payment required', { status: 402 });

// Consume budget ($0.005 = 5000 atomic USDC units)
const result = store.consumeBudget(token, 5000n);
if (!result.ok) return new Response('Insufficient budget', { status: 402 });

// Settle on-chain
await settleCall(session.humanAddress, 5000n, {
  treasuryAddress: process.env.TREASURY_ADDRESS!,
  hotWalletKey: process.env.HOT_WALLET_PRIVATE_KEY,
});

return Response.json({ result: 'your data' });

3. リファレンスサーバーを実行する

git clone https://github.com/MCPVOT/mcp-agentic-wallet.git
cd mcp-agentic-wallet
npm install
cp .env.example .env.local  # Configure your treasury + hot wallet key
npm run dev

http://localhost:3000/wallet にアクセスしてウォレットを接続し、セッションを承認します。

仕組み

Human                          Server                        Agent
  │                              │                              │
  │── connect wallet ──────────►│                              │
  │── sign EIP-2612 Permit ───►│                              │
  │   (gasless, 1-time)           │── verify signature ──────►│ (on-chain)
  │                              │── submit permit() ────────►│ (on-chain, gas)
  │                              │── create session ──────────┐│
  │◄─ return session token ─────│◄───────────────────────────┘│
  │                              │                              │
  │                              │◄── Session-Token header ────│
  │                              │── consume budget ───────────┐│
  │                              │── transferFrom() ──────────►││ (on-chain, gas)
  │                              │── return tool data ─────────┘│
  │                              │◄──────────────────────────────│

コアライブラリ（@mcp-agentic-wallet/core）

クラス／関数	説明
InMemoryStore	セッションストア（インメモリ。KV／Redis に差し替え可能）
verifyPermit()	viem を介してオンチェーンで EIP-712 Permit 署名を検証します
settleCall()	Base 上で transferFrom(human, treasury, amount) を実行します
submitPermit()	USDC コントラクトに permit() トランザクションを送信します
checkAllowance()	所有者→使用者のペアについて、オンチェーンの USDC 使用許容量を読み取ります
checkRateLimit()	シンプルなレート制限機能（ウォレットごと）
toSessionInfo()	セッションをクライアント向けの安全な情報に変換します（Permit 署名は含みません）

セキュリティ

脅威モデルの詳細については、SECURITY.md を参照してください。

主な機能：

• EIP-712 署名の検証 — セッションを作成する前に、サーバーがすべての Permit 署名をオンチェーンで検証します
• 使用許容量の上限 — セッションあたり最大 100 USDC（設定可能）
• 有効期限の上限 — 最大 30 日
• レート制限 — ウォレットあたり 1 時間に 5 回まで承認可能
• セッションの取り消し — 人はいつでも取り消せます
• 決済債務の追跡 — 決済に 3 回失敗すると、セッションが停止されます
• 使用者の検証 — EIP-712 の検証により、spender === treasury が本質的に確認されます

ドキュメント

• アーキテクチャ — システム図、決済フロー、設計上の判断
• MCP 統合 — あらゆる MCP サーバーに追加するための手順ガイド
• セキュリティポリシー — 脅威モデル、攻撃ベクトル、本番環境向けチェックリスト
• コントリビューション — 開発環境のセットアップ、ガイドライン、PR の手順
• 寄付 — プロジェクトを支援する

技術スタック

• EIP-2612（Permit）— 型付きデータ署名によるガスレス承認
• EIP-712 — 型付きデータの署名と検証
• Base Mainnet 上の USDC（FiatTokenV2）（chainId 8453）
• viem — TypeScript の Ethereum ライブラリ
• Next.js — リファレンスサーバーの実装
• Model Context Protocol — MCP 2025-11-25 仕様

ユースケース：iRacing + ブロックチェーン

MCPVOT はこのウォレットを使用して、オンチェーンのシムレーシングイベントを実現します。

1. 主催者がイベントを作成 — Base 上に、参加費と賞金プールを設定したエスクロー用スマートコントラクトをデプロイします
2. ドライバーがウォレットを接続 — このライブラリを使って EIP-2612 Permit に署名し、セッショントークンを取得します
3. ドライバーが参加費を支払う — transferFrom により、参加費がエスクローコントラクトに送金されます
4. iRacing でレースを開催 — サーバーが iRacing Data API をポーリングして、フィニッシュ順位を取得します
5. スマートコントラクトが自動で賞金を分配 — 検証済みの勝者が賞金プールから USDC/SOL を受け取ります

iRacing MCP ツール（get_race_results、lookup_driver、search_hosted_races）は mcpvot.xyz で利用でき、支払いには同じセッショントークンフローを使用します。

設定

Env Var	必須	デフォルト	説明
TREASURY_ADDRESS	はい	—	USDC の受取先アドレス
HOT_WALLET_PRIVATE_KEY	はい	—	ガス代用の EOA 秘密鍵（git に絶対にコミットしないでください！）
BASE_RPC_URL	いいえ	https://mainnet.base.org	Base Mainnet RPC
NEXT_PUBLIC_TREASURY_ADDRESS	はい	—	ウォレット UI に表示するトレジャリーアドレス

ライセンス

MIT — LICENSE を参照