# 🔐 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.

```bash
# 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

```bash
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):

```json
{
  "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/