MCP Agentic Wallet — open-source session management for x402

MCP Agentic Wallet

Open-source EIP-2612 Permit-based wallet sessions for AI agents. The reference implementation for paid MCP servers — verify signatures, manage sessions, settle on-chain. No API keys. No recurring charges.

What This Is

A human connects their crypto wallet, signs a one-time EIP-2612 Permit (gasless — no transaction fee), and receives a session token. AI agents use this token in MCP requests to pay for tool calls with USDC on Base. The server settles each call on-chain via transferFrom.

No API keys. No recurring charges. No per-call wallet signatures. The permit is the policy.

This is the reference implementation used by mcpvot.xyz — an x402 payment facilitator for MCP servers. The open-source core (@mcp-agentic-wallet/core) is framework-agnostic and works with any MCP server or Next.js app.

Quick Start

1. Install the core library

npm install @mcp-agentic-wallet/core viem

2. Use in your MCP server

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. Run the reference server

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

Visit http://localhost:3000/wallet to connect a wallet and authorize a session.

How It Works

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 ─────────┘│
  │                              │◄──────────────────────────────│

Core Library (@mcp-agentic-wallet/core)

Class/Function	Description
InMemoryStore	Session store (in-memory, pluggable for KV/Redis)
verifyPermit()	Verifies EIP-712 Permit signature on-chain via viem
settleCall()	Executes transferFrom(human, treasury, amount) on Base
submitPermit()	Submits the permit() transaction to USDC contract
checkAllowance()	Reads on-chain USDC allowance for an owner→spender pair
checkRateLimit()	Simple rate limiter (per-wallet)
toSessionInfo()	Converts session to safe client-facing info (no permit signature)

Security

See SECURITY.md for the full threat model.

Key features:

• EIP-712 signature verification — server verifies every permit signature on-chain before creating a session
• Allowance cap — max $100 USDC per session (configurable)
• Deadline cap — max 30 days
• Rate limiting — 5 authorizations per wallet per hour
• Session revocation — humans can revoke anytime
• Settlement debt tracking — sessions suspended after 3 failed settlements
• Spender verification — EIP-712 verification inherently checks spender === treasury

Documentation

• ARCHITECTURE — system diagram, payment flow, design decisions
• MCP Integration — step-by-step guide for adding to any MCP server
• Security Policy — threat model, attack vectors, production checklist
• Contributing — dev setup, guidelines, PR process
• Donations — support the project

Tech Stack

• EIP-2612 (Permit) — gasless approval via typed data signature
• EIP-712 — typed data signing and verification
• USDC (FiatTokenV2) on Base Mainnet (chainId 8453)
• viem — TypeScript Ethereum library
• Next.js — reference server implementation
• Model Context Protocol — MCP 2025-11-25 spec

Use Case: iRacing + Blockchain

MCPVOT uses this wallet to power on-chain sim-racing events:

1. Host creates event — deploys an escrow smart contract on Base with entry fee + prize pool
2. Drivers connect wallet — sign EIP-2612 Permit via this library, get a session token
3. Drivers pay entry fee — transferFrom settles the entry to the escrow contract
4. Race happens in iRacing — server polls iRacing Data API for finish order
5. Smart contract auto-disburses — verified winners receive USDC/SOL from the prize pool

The iRacing MCP tools (get_race_results, lookup_driver, search_hosted_races) are available at mcpvot.xyz and use the same session-token flow for payment.

Configuration

Env Var	Required	Default	Description
TREASURY_ADDRESS	Yes	—	Address that receives USDC payments
HOT_WALLET_PRIVATE_KEY	Yes	—	EOA private key for gas (never commit to git!)
BASE_RPC_URL	No	https://mainnet.base.org	Base Mainnet RPC
NEXT_PUBLIC_TREASURY_ADDRESS	Yes	—	Treasury shown in wallet UI

License

MIT — see LICENSE