clawlet (Clawletxyz)

Clawlet

Spend controls for AI agents + x402 payments over HTTP.

One package. One command. Your AI agent gets a USDC wallet on Base with spending rules, x402 payment support, and a full audit trail — all running on your machine.

Quickstart

npx clawlet

That's it. Opens a dashboard at http://localhost:3000 where you create a wallet, set spending rules, and view transactions. The CLI also prints the MCP config snippet to connect Claude Desktop.

Install globally (optional)

npm install -g clawlet
clawlet start

Connect your AI agent

Clawlet runs an MCP server that gives any compatible AI agent financial tools. Add this to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "clawlet": {
      "command": "npx",
      "args": ["-y", "clawlet", "mcp"]
    }
  }
}

Once connected, your agent has these tools:

Example conversation

You:   Create a wallet for this agent
Agent: [calls create_wallet] → Created wallet 0xABC...123 on Base.

You:   Set a $5 per transaction limit and $20 daily cap
Agent: [calls set_spending_rules] → Rules updated.

You:   Access the premium data at https://api.example.com/data
Agent: [calls pay] → Paid 0.10 USDC to api.example.com. Here's the data: {...}

You:   Something's wrong — freeze the wallet
Agent: [calls freeze_wallet] → Wallet frozen. All payments blocked.

How x402 payments work

Agent                     Clawlet                   Paid API
  |                          |                          |
  |--- pay(url) ----------->|                          |
  |                          |--- GET url ------------->|
  |                          ||
  |                          |      Port for the dashboard (default: 3000)
  --help, -h           Show help
  --version, -v        Show version

Architecture

src/
├── cli.ts         # CLI entry point (npx clawlet)
├── index.ts       # MCP server — tool definitions, stdio transport
├── api.ts         # REST API + dashboard server (Hono)
├── wallet.ts      # Multi-wallet management, freeze/unfreeze
├── rules.ts       # Spending rules engine
├── ledger.ts      # Transaction recording
├── x402.ts        # x402 protocol handler (EIP-712 signing, two-phase for browser wallets)
├── store.ts       # SQLite persistence, wallet resolution (.clawlet/clawlet.db)
├── types.ts       # TypeScript type definitions
├── constants.ts   # Network addresses, ABIs, RPC URLs
└── adapters/
    ├── local-key.ts      # Raw private key (dev/testing)
    ├── coinbase-cdp.ts   # Coinbase CDP v2 (TEE-based)
    ├── browser-wallet.ts # MetaMask / browser extension
    └── evm-balance.ts    # Shared ERC-20 balance lookup

dashboard/             # React + Vite monitoring UI
demo/                  # Mock x402 server + seed data

Development

git clone https://github.com/clawletxyz/clawlet.git
cd clawlet
npm install

# Seed sample data and run with hot reload
npm run demo:seed
npm run dev

# Run with mock x402 server (API + dashboard + mock paid endpoints)
npm run demo

# Build everything
npm run build

The mock x402 server runs on localhost:4020 with test endpoints:

Networks

Switch networks via the dashboard or MCP:

Agent: [calls set_network with network="base-sepolia"] → Switched to testnet.

Security

• Private keys are stored locally in .clawlet/clawlet.db (gitignored)
• The wallet only signs ERC-3009 TransferWithAuthorization — the facilitator can only execute the exact transfer described
• Spending rules are enforced before any signature is created
• Freeze blocks all payments instantly, no confirmation needed
• The Coinbase CDP adapter uses TEE-based key management — keys never leave the secure enclave

REST API

The dashboard server exposes a full REST API at the same port.

Authentication

Set CLAWLET_API_KEY env var to require a bearer token on all API routes (except /api/config):

CLAWLET_API_KEY=my-secret-key clawlet start

Then include Authorization: Bearer my-secret-key in requests. If the env var is not set, auth is disabled.

Legacy routes (active wallet)

GET    /api/config             Config flags (demoMode, authRequired)
GET    /api/wallets            List all wallets
POST   /api/wallets            Create a new wallet
POST   /api/wallets/switch     Switch active wallet
DELETE /api/wallets/:id        Delete a wallet
GET    /api/balance            Get USDC balance
GET    /api/rules              Get spending rules
PUT    /api/rules              Update spending rules
GET    /api/transactions       Get transaction history
GET    /api/today-spent        Today's spending total
POST   /api/pay                Make an x402 payment
POST   /api/freeze             Freeze active wallet
POST   /api/unfreeze           Unfreeze active wallet
GET    /api/agent-identity     Get agent identity
POST   /api/agent-identity     Set agent identity

Wallet-scoped routes

Target a specific wallet by ID — no need to switch the active wallet:

GET    /api/wallets/:walletId/transactions     Transactions for wallet
GET    /api/wallets/:walletId/rules            Get spending rules
PUT    /api/wallets/:walletId/rules            Update spending rules
GET    /api/wallets/:walletId/balance          Get USDC balance
POST   /api/wallets/:walletId/freeze           Freeze wallet
POST   /api/wallets/:walletId/unfreeze         Unfreeze wallet
POST   /api/wallets/:walletId/rename           Rename wallet
GET    /api/wallets/:walletId/agent-identity   Get agent identity
POST   /api/wallets/:walletId/agent-identity   Set agent identity
GET    /api/wallets/:walletId/today-spent      Today's spending total
GET    /api/wallets/:walletId/tags             Get wallet tags
PUT    /api/wallets/:walletId/tags             Set/merge wallet tags
POST   /api/wallets/:walletId/pay              Make an x402 payment

Aggregate endpoints

GET    /api/overview           All wallets with rules, tags, and today's spend
GET    /api/transactions/all   Cross-wallet transaction ledger (?limit=N)

Contributing

See CONTRIBUTING.md.

Stack

• MCP — Model Context Protocol for agent tool communication
• Hono — lightweight web framework for the REST API
• viem — EVM interactions and EIP-712 signing
• x402 — HTTP-native payment protocol
• USDC on Base — settlement layer

License

MIT