MCP Agentic Wallet — open-source session management for x402
Open-source EIP-2612 Permit-based wallet sessions for AI agents using MCP.
Open source Open in the app JSON README (API)
About
Open-source EIP-2612 Permit-based wallet sessions for AI agents using MCP.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- mcpvot
- Origin
- official
- Category
- ferramentas
- Transport
- desconhecido
- Version
- 1.0.1
- Last push
- 2026-07-28T05:04:11Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:01
- Updated
- 2026-08-29 03:02:01
- Origin id
io.github.MCPVOT/mcp-agentic-wallet
README
# 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.
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://viem.sh/)
[](https://base.org/)
[](https://modelcontextprotocol.io/)
## 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](https://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
```bash
npm install @mcp-agentic-wallet/core viem
```
### 2. Use in your MCP server
```typescript
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
```bash
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](./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](https://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](./LICENSE)