MCP Agentic Wallet — open-source session management for x402

MCP Agentic Wallet

面向 AI Agent 的开源 EIP-2612 Permit 会话钱包。 付费 MCP 服务的参考实现——验证签名、管理会话、在链上结算。无需 API 密钥。无定期扣费。

这是什么

用户连接自己的加密钱包，签署一次性 EIP-2612 Permit（免 Gas——无需支付交易费），并获得一个会话令牌。AI Agent 在 MCP 请求中使用此令牌，通过 Base 上的 USDC 为工具调用付费。服务端通过 transferFrom 在链上结算每次调用。

无需 API 密钥。无定期扣费。无需为每次调用签署钱包。 Permit 就是规则。

这是 mcpvot.xyz 使用的参考实现——一个面向 MCP 服务的 x402 支付促成服务。开源核心库（@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 天
• 速率限制 — 每个钱包每小时最多授权 5 次
• 会话撤销 — 用户可随时撤销
• 结算欠款跟踪 — 结算失败 3 次后暂停会话
• 支出方验证 — EIP-712 验证会自动检查 spender === treasury

文档

• 架构 — 系统图、支付流程、设计决策
• MCP 集成 — 将其接入任意 MCP 服务的分步指南
• 安全策略 — 威胁模型、攻击途径、生产环境检查清单
• 贡献指南 — 开发环境设置、指南、PR 流程
• 捐赠 — 支持此项目

技术栈

• EIP-2612（Permit）— 通过类型化数据签名免 Gas 授权
• EIP-712 — 类型化数据签名与验证
• Base 主网（chainId 8453）上的 USDC（FiatTokenV2）
• viem — TypeScript 以太坊库
• 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 使用，并采用相同的会话令牌支付流程。

配置

环境变量	必需	默认值	说明
TREASURY_ADDRESS	是	—	接收 USDC 付款的地址
HOT_WALLET_PRIVATE_KEY	是	—	用于支付 Gas 的 EOA 私钥（切勿提交到 git！）
BASE_RPC_URL	否	https://mainnet.base.org	Base 主网 RPC
NEXT_PUBLIC_TREASURY_ADDRESS	是	—	钱包界面中显示的金库地址

许可证

MIT — 请参阅 LICENSE