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:

Tool	What it does
create_wallet	Create a new USDC wallet on Base
list_wallets	List all wallets, show which is active
switch_wallet	Switch the active wallet
get_wallet	Get active wallet address and status
get_balance	Check USDC balance
set_spending_rules	Set per-tx limit, daily cap, service allow/blocklists
get_spending_rules	View current rules
set_network	Switch between Base mainnet and Base Sepolia testnet
pay	Make an x402 payment to any URL
get_transactions	View transaction history
freeze_wallet	Emergency kill switch — blocks all payments instantly
unfreeze_wallet	Re-enable payments
set_agent_identity	Bind an ERC-8004 on-chain identity to the wallet
get_agent_identity	Retrieve agent identity
configure_adapter	Configure Coinbase CDP wallet provider

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 ------------->|
  |                          |<-- 402 Payment Required -|
  |                          |                          |
  |                    Check spending rules             |
  |                    Sign ERC-3009 payment            |
  |                          |                          |
  |                          |--- GET url + signature ->|
  |                          |<-- 200 OK + response ----|
  |                          |                          |
  |                    Log transaction                  |
  |<-- response + receipt ---|                          |

1. Agent calls pay with a URL
2. Clawlet sends the request, gets 402 Payment Required with payment details
3. Spending rules are checked (per-tx limit, daily cap, allowlist/blocklist, frozen status)
4. Clawlet signs an EIP-712 TransferWithAuthorization (ERC-3009) for the exact USDC amount
5. Retries the request with the payment signature
6. Server verifies, settles on-chain, returns the response
7. Transaction is logged with hash, amount, service, and reason

The agent never touches private keys. Clawlet handles all cryptographic operations.

Wallet adapters

Clawlet supports multiple wallet providers through a common adapter interface:

Adapter	Type	Custody	Use case
local-key	Self-custodial	You	Development, testing, full control
coinbase-cdp	Managed	Coinbase (TEE)	Production server-side agents
browser-wallet	Browser	MetaMask, etc.	Dashboard payments via browser extension

The default adapter (local-key) generates a private key locally — no third-party dependency. For production deployments, configure the Coinbase CDP adapter:

You:   Configure Coinbase CDP as the wallet provider
Agent: [calls configure_adapter] → Coinbase CDP configured.

You:   Create a new wallet
Agent: [calls create_wallet with adapter="coinbase-cdp"] → Wallet provisioned via CDP.

CLI

clawlet                Start the dashboard and API server
clawlet start          Same as above
clawlet mcp            Start the MCP server (stdio transport)

Options:
  --port <number>      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:

Endpoint	Price
/api/joke	0.01 USDC
/api/weather	0.05 USDC
/api/market-data	0.10 USDC
/api/sentiment	0.02 USDC
/api/code-review	0.25 USDC

Networks

Network	Chain ID	USDC Address
Base Mainnet	eip155:8453	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Base Sepolia	eip155:84532	0x036CbD53842c5426634e7929541eC2318f3dCF7e

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