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)

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](./docs/ARCHITECTURE.md) — system diagram, payment flow, design decisions
• [MCP Integration](./docs/MCP-INTEGRATION.md) — step-by-step guide for adding to any MCP server
• [Security Policy](./SECURITY.md) — threat model, attack vectors, production checklist
• [Contributing](./CONTRIBUTING.md) — dev setup, guidelines, PR process
• [Donations](./docs/DONATIONS.md) — 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

License

MIT — see LICENSE