🔐 OWS MCP Wallet - Agent Treasury with Spending Limits

MCP server that exposes OpenWallet Standard to Claude with built-in policy engine and spending limits.

Hackathon Tracks: #05 (Agent Treasury) + #06 (MCP Wallet Server)

---

🎯 What It Does

Allows AI agents (like Claude) to:

• ✅ Check wallet balances across multiple chains
• ✅ Send transactions with policy enforcement
• ✅ Automatic spending limit protection
• ✅ Multi-chain support (Ethereum, Solana, Base)
• ✅ Session-scoped security

Demo: Agent can't overspend even if instructed to!

---

🚀 Quick Start (15 Minutes!)

New: Auto-generate test wallets! No need for MetaMask/Phantom.

# 1. Install dependencies
cd ~/ows-mcp-wallet
npm install

# 2. Generate test wallet (creates addresses + private keys)
npm run generate

# 3. Copy output to .env file
# (Script tells you exactly what to copy)

# 4. Get testnet tokens
# Visit faucets (links in output)

# 5. Test it works
npm test
npm run cli balance

# 6. Send real testnet transaction!
npm run cli send ethereum-sepolia 0x000... 0.01

📖 Full walkthrough: See QUICKSTART.md for detailed 15-min guide

---

📚 Documentation

• QUICKSTART.md ⭐ - 15-minute setup guide (start here!)
• SETUP-GUIDE.md - Detailed step-by-step setup
• ENV-VARIABLES.md - Complete environment variable reference
• MOBILE-PLAN.md - Mobile-friendly hackathon guide
• GETTING-STARTED.md - Friday build schedule

---

🔧 New Commands

npm run generate    # Generate test wallet
npm run test        # Verify configuration
npm run cli balance # Check balances
npm run cli policy  # View spending limits
npm run cli send    # Send test transaction
npm run build       # Build for production
npm run dev         # Run in watch mode

---

🔧 Configure Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "ows-wallet": {
      "command": "node",
      "args": ["/path/to/ows-mcp-wallet/dist/mcp-server.js"],
      "env": {
        "ETH_ADDRESS": "0xYourAddress",
        "SOL_ADDRESS": "YourSolanaAddress"
      }
    }
  }
}

Restart Claude Desktop.

---

🎬 Demo Script

Test 1: Check Balance

You: "What's my wallet balance?"
Claude: *calls get_balance tool*
Response: Shows balances across all chains

Test 2: Send Transaction (Allowed)

You: "Send 0.01 ETH to 0x123... on Sepolia"
Claude: *calls send_transaction*
Response: ✅ Transaction approved and prepared

Test 3: Overspending (Blocked)

You: "Send 100 ETH to 0x456..."
Claude: *calls send_transaction*
Response: ❌ DENIED - Exceeds $50 per-transaction limit

Test 4: Check Policy

You: "What are my spending limits?"
Claude: *calls check_policy*
Response: Shows daily limit, spent amount, remaining allowance

---

📊 Policy Engine

Default limits (configurable):

• Daily limit: $100 USD
• Per-transaction limit: $50 USD
• Allowed chains: Sepolia, Devnet, Base Sepolia
• Optional: Address whitelist

---

🏗️ Architecture

Claude (AI Agent)
    ↓
MCP Protocol
    ↓
OWS MCP Server
    ↓
Policy Engine (checks limits)
    ↓
Wallet Manager (prepares transaction)
    ↓
OWS (signs & broadcasts)
    ↓
Blockchain

---

📁 Project Structure

ows-mcp-wallet/
├── mcp-server.ts          # MCP server implementation
├── wallet-manager.ts      # Multi-chain wallet interface
├── policy-engine.ts       # Spending limits & policy
├── package.json
├── tsconfig.json
├── .env.example
├── testnet-setup.md       # Testnet token guide
└── README.md

---

🔨 Development Checklist

Morning (Setup - 1-2 hours)

• [x] Project structure created
• [x] Dependencies installed
• [ ] Get testnet tokens (ETH, SOL, Base)
• [ ] Create OWS wallet
• [ ] Update .env with addresses
• [ ] Build project

Afternoon (Core Features - 3-4 hours)

• [x] Wallet Manager implemented
• [x] Policy Engine implemented
• [x] MCP Server implemented
• [ ] Test with real testnet addresses
• [ ] Verify policy enforcement works
• [ ] Test all 3 tools with Claude

Evening (Demo & Polish - 2-3 hours)

• [ ] Record 2-min demo video
• [ ] Create submission materials
• [ ] Deploy to GitHub
• [ ] Write clear documentation
• [ ] Submit to hackathon

---

🎥 Demo Video Outline

2-Minute Demo:

0:00 - Introduction

• "AI agents need wallets. But they also need guardrails."

0:20 - Show the problem

• "Without limits, an agent could drain your wallet"

0:40 - Show the solution

• Live demo of Claude checking balance
• Claude sending small transaction (approved)
• Claude trying to overspend (blocked)

1:30 - Show the tech

• Quick code walkthrough
• Policy engine enforcement
• Multi-chain support

1:50 - Call to action

• "Built on OWS. Local-first. Self-custody."
• GitHub link

---

🚀 Production Roadmap

If this wins/scales:

Phase 1: Polish MVP

• Add actual OWS integration
• Broadcast to real testnets
• Transaction history tracking

Phase 2: Enhanced Features

• Custom policy templates
• Multi-user support
• Audit logging dashboard

Phase 3: Monetization

• Free tier: Personal use
• Pro ($49/mo): Team policies
• Enterprise: White-label solution

---

🤝 Contributing

Built for the OpenWallet Standard Hackathon - April 3, 2026

---

📄 License

MIT

---

🔗 Links

• OpenWallet Standard: https://openwallet.sh/
• Hackathon: https://hackathon.openwallet.sh/
• MCP Docs: https://modelcontextprotocol.io/