🐾 ClawSafe

The safest way to let AI agents spend on Solana

Solana · MCP · AI agents · x402 · Token-2022 · micropayments

⭐ Star this repo if it's useful — it helps other builders discover ClawSafe.

ClawSafe is an open-source Model Context Protocol (MCP) server that gives autonomous AI agents — Cline, Cursor, Claude Code, Roo Code — their own policy-gated Solana wallet, so they can pay for APIs and move micro-funds autonomously without ever touching your main wallet.

Give agents spending power, not your seed phrase.

🎯 TL;DR

npx -y clawsafe-mcp init     # create the local allowance wallet (~/.clawsafe)
npx -y clawsafe-mcp serve    # start the MCP server (stdio) for any MCP client

• ✅ Local burner wallet — your main Solana wallet is never imported, configured, or read.

• ✅ Hard policy engine — per-transaction and rolling-hour spend limits, enforced before anything is signed.

• ✅ Token-2022 CPI Guard — protects the agent's token accounts from hidden cross-program transfers.

• ✅ x402 paid APIs — agents self-serve HTTP 402 Payment Required resources inside their allowance.

• ✅ SOL / USDC payments and Jupiter swaps — every operation is one atomic, fully signed transaction.

• ✅ Works everywhere MCP works — Claude Desktop, Cline, Cursor, Roo Code, any stdio client.

Related MCP server: PipRail

🤖 What an agent session looks like

You:     "Fetch the paid weather report and send 0.01 SOL to Alice."

Agent:   get_allowance_status()
           → solBalance: 0.5 SOL · remaining this hour: 0.2 SOL · limits OK

Agent:   x402_paid_fetch("https://api.weatherx.io/report")
           ← 402 Payment Required (invoice: 0.001 SOL)
           → ClawSafe pays from the burner wallet (inside the limits)
           → retries with the payment proof attached
           → returns the JSON report + the payment receipt

Agent:   pay_sol(alice, 0.01)
           → atomic transfer, signature returned, spent logged against the hour

Agent:   "Done. Report attached. 0.19 SOL remaining this hour."

No copy-pasting signatures, no wallet approvals, no human in the loop — and no way for the agent to overshoot the policy you set.

✨ Features

🚀 Quick start

Requires Node.js ≥ 20.

# 1) Create the allowance wallet, policy and spend log (~/.clawsafe)
npx -y clawsafe-mcp init

  ✔ Burner wallet generated: ~/.clawsafe/keypair.json
     Sub-wallet address:  Ad8zCHiwBXVwVKioC3GGR2CU6fkTJbCzsokjG21s5PdK

  ✔ Policy file: ~/.clawsafe/policy.json
     Limits: 0.05 SOL/tx · 0.2 SOL/hour · 5 USDC/tx · 20 USDC/hour
  🔒 Token-2022 CPI Guard enforced on this wallet's accounts

# 2) Fund the burner wallet with a small amount of SOL / USDC (only what you can lose)

# 3) Point your MCP client at it — the server name is "clawsafe"

Claude Desktop — claude_desktop_config.json:

// macOS / Linux
{
  "mcpServers": {
    "clawsafe": {
      "command": "npx",
      "args": ["-y", "clawsafe-mcp", "serve"]
    }
  }
}

// Windows
{
  "mcpServers": {
    "clawsafe": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "clawsafe-mcp", "serve"]
    }
  }
}

Cline / Cursor / Roo Code / Zed / OpenAI Agents SDK — add a stdio MCP server: command npx, args -y clawsafe-mcp serve.

🧰 The 6 MCP tools

All inputs are zod-validated; violations return an isError result that names the violated limit and the exact remaining allowance, so agents can retry within budget instead of looping.

🛡️ Security model

• Local enforcement. Limits are checked in-process before any transaction is built or signed. There is no remote API to bypass, nothing to phish.

• Safe defaults. A fresh install allows 0.05 SOL/tx, 0.2 SOL/hour, 5 USDC/tx, 20 USDC/hour. Unknown or malformed policy fields always fall back to the defaults — a half-edited policy.json can never silently disable a limit.

• Auditable accounting. Every executed spend is appended to ~/.clawsafe/history.json; a corrupt history is a hard failure instead of silently forgotten limits.

• One-way flows. A scam instruction from an agent can only spend within the allowance — it can never reach your main accounts or drain savings.

🔒 Token-2022 CPI Guard, explained

A normal Token-2022 account can be spent not only by you, but also by any program you interact with — a malicious dApp can trigger a hidden CPI (cross-program invocation) that transfers your tokens out while you're signing something unrelated. ClawSafe enables the CPI Guard extension on the wallet's Token-2022 accounts:

• With the guard on, transfers from that account only succeed when the instruction is signed directly by you (the owner), not pushed through another contract.

• It activates automatically — swap_tokens enables it on the received Token-2022 account right after the swap lands, and get_allowance_status reports the protection state of every account.

🧱 Policy engine

~/.clawsafe/policy.json is the hard firewall the agent cannot talk its way out of:

{
  "maxPerTxSol": 0.05,
  "maxPerHourSol": 0.2,
  "maxPerTxUsdc": 5.0,
  "maxPerHourUsdc": 20.0,
  "whitelistedAddresses": [],
  "allowedX402Domains": []
}

• maxPerTx* / maxPerHour* — hard caps per transaction and per rolling 60 minutes (from history.json). SOL and USDC are tracked separately.

• whitelistedAddresses — when non-empty, transfers may only go to these base58 addresses.

• allowedX402Domains — when non-empty, paid-fetch auto-payment is restricted to these domains (exact match or *.domain.com).

• Limits always apply to the total amount debited from the wallet in a single atomic operation.

• Rejections are written for the agent: "the total cost of X exceeds the per-transaction limit of Y… remaining right now: Z" — so it can retry with a smaller amount instead of guessing.

🌐 x402: paid APIs for autonomous agents

x402 is the open standard that turns HTTP 402 Payment Required into machine-payable invoices. With the x402_paid_fetch tool, your agent can consume paid APIs end-to-end:

1. ClawSafe fetches the URL; the API answers 402 with payment requirements (x402 v2 JSON body or a URL-encoded PAYMENT-REQUIRED header).

2. The domain is checked against allowedX402Domains, and the invoice amount against the same policy limits used for every other payment.

3. ClawSafe pays from the burner wallet and replays the request with the Solana transaction signature in the PAYMENT-SIGNATURE / X-PAYMENT header.

4. The agent receives the API's payload plus a payment receipt (amount, signature, explorer link).

Guardrails: the payment is attempted exactly once (a repeat 402 is an error, never a loop), an invoice for a different resource is refused, and only SOL / USDC invoices are supported.

♻️ Trapped rent — audited, never auto-reclaimed

Empty SPL Token / Token-2022 accounts still hold a SOL rent deposit (~0.002 SOL each). ClawSafe deliberately never closes accounts from agent flows — mixing rent reclaims with AI-driven transfers is how funds get moved by mistake. Instead, check_trapped_rent scans both token programs and reports:

Found 12 empty token accounts locking 0.0244 SOL in rent. Reclaim your SOL safely in 1 click at https://excesssol.xyz

Reclaiming stays a human action at https://excesssol.xyz (independent third party — review it before use).

🏗️ How it works

┌──────────────┐      MCP (stdio)       ┌──────────────────────────────────┐
│  AI agent    │ ◄──────────────────►   │        clawsafe-mcp              │
│ (Cline /     │     6 tools only       │      (this server, Node)         │
│  Cursor /    │                        │                                  │
│  Claude)     │                        │  ┌──────────────────────────┐    │
└──────────────┘                        │  │ Burner wallet keypair     │    │ ← fund this, never your main wallet
                                        │  │  ~/.clawsafe/keypair.json │    │
                                        │  └─────────────┬────────────┘    │
                                        │  Policy engine  (hard limits)   │ ← checked BEFORE anything is signed
                                        │  Solana layer   (payments/swaps)│
                                        │  x402 client    (auto-pay 402)   │
                                        └────────────────┬─────────────────┘
                                                         ▼
                                        ┌──────────────────────────────────┐
                                        │         Solana mainnet           │
                                        │   recipient ← full amount        │
                                        └──────────────────────────────────┘

💡 Use cases

• Pay-per-request AI APIs — give agents a budget for x402 endpoints (weather, data, inference) without manual invoicing.

• Agentic commerce prototypes — capped budgets for agents that buy digital goods or trigger payouts.

• Sandboxed agent research — study autonomous spending behavior with real transactions and hard ceilings.

• Team tooling budgets — each coding agent gets its own allowance for SaaS / infra APIs.

⚙️ Configuration

Set them in .env (see .env.example), in the env block of your MCP client config, or in your shell.

👨‍💻 Development

npm install          # install dependencies
npm run build        # tsc → dist/
npm run typecheck    # strict type-check of src + tests (no emit)
npm test             # node:test + tsx: spend limits, cost math, x402 parsing
npm run dev -- init  # run the CLI from source (tsx)
node dist/index.js init   # or run the built CLI directly

Tests use node --import tsx, which needs Node ≥ 20.6.

🔎 Known transitive advisory (bigint-buffer)

npm audit reports one remaining high advisory: bigint-buffer (GHSA-3gc7-fjrx-p6mg), a deep transitive dependency of @solana/spl-token (via @solana/buffer-layout-utils). It has no fixed release — 1.1.5 is the last version ever published, and npm's only suggested "fix" is downgrading @solana/spl-token to 0.1.8, which predates Token-2022 and would break CPI Guard. Assessment:

• The vulnerable function is only reached when decoding on-chain data returned by the RPC endpoint you configure (SOLANA_RPC_URL).

• The impact is availability only (a potential uncaught RangeError on a crafted payload), not memory corruption — Node's Buffers are bounds-checked.

• Every other advisory the audit reported (zod, stream-json, uuid) is resolved at the root of the tree via direct version upgrades and the overrides block in package.json.

We track upstream and will drop this dependency as soon as @solana/spl-token removes it.

📦 Project structure

src/
├── index.ts     # CLI: `init` (wallet + config bootstrap) and `serve` (default, stdio MCP server)
├── config.ts    # Routing parameters, paths under ~/.clawsafe, RPC/protocol constants
├── wallet.ts    # Burner wallet generation/storage + Token-2022 CPI Guard helpers
├── policy.ts    # Policy engine: limits, rolling-hour history, whitelist, x402 domain gate
├── solana.ts    # Payments, Jupiter swaps, rent scan, wallet status
├── x402.ts      # HTTP 402 parsing and the paidFetch flow
└── tools.ts     # The 6 MCP tools with zod schemas
tests/           # node:test unit tests: cost math, policy limits, x402 parsing

State on disk (~/.clawsafe/, all mode 0600): keypair.json (burner secret key — never share, never exposed to tools), policy.json (limits, whitelist, allowed x402 domains), history.json (rolling-hour spend log).

❓ FAQ

What is a burner wallet? A throwaway hot wallet that holds only the funds you put into it. In ClawSafe it lives at ~/.clawsafe/keypair.json — the agent's only money pipe, bounded by the policy engine.

Does the agent see my private keys? No. The keypair is only used inside the server process to sign transactions the policy engine approved. It never appears in a tool response, a prompt, or a log.

How is this different from pasting my wallet into an agent? Scope and blast radius: a main wallet gives the agent everything, a ClawSafe burner gives it a capped allowance with per-tx + rolling-hour limits, a recipient whitelist, and CPI-guarded token accounts.

Which MCP clients work? Any client that speaks stdio MCP: Claude Desktop, Cline, Cursor, Roo Code, Zed, the OpenAI Agents SDK, mcp-inspector, and more.

Which chains / tokens? Solana (mainnet; point SOLANA_RPC_URL at devnet to test), native SOL, USDC, and any SPL / Token-2022 token via Jupiter swaps.

What is x402? An open protocol that makes HTTP 402 Payment Required machine-readable (amount, asset, pay-to address), so clients can pay per API request. ClawSafe implements the Solana side: parse → approve → pay → retry with proof.

What happens when the agent hits a limit? It gets a plain-English MCP error naming the violated limit and the exact remaining allowance, so it can retry smaller or wait — never bypass.

Is it safe? It's self-custodial and open-source: your keys, your machine, your policy. Still — this moves real money on mainnet. Fund only what you can lose, test on devnet, and review the code (start with src/policy.ts and src/wallet.ts).

🗺️ Roadmap

• Repository, CLI (init / serve) and the ~/.clawsafe layout

• Burner wallet + Token-2022 CPI Guard

• Policy engine (per-tx + rolling-hour limits, whitelist, x402 domain gate)

• pay_sol, pay_usdc, swap_tokens (Jupiter) and check_trapped_rent

• x402 paid-fetch (JSON v2 + header invoices, one-shot payment)

• The 6 MCP tools with zod validation, unit tests, docs (that's this README!)

Ideas: devnet mode flag, multi-wallet profiles, notifications when limits reset, more input assets for swap accounting, payment-channel top-ups, a desktop widget.

🤝 Contributing

PRs are welcome — see the roadmap above for direction. Good first issues: new x402 parsers, more tools (NFT transfers, compressed tokens), docs translations, and more MCP client recipes.

1. Fork it, npm install, npm test must stay green.

2. Keep the strict TS settings and add tests for new policy/math behavior.

3. Open a PR describing the use case (agents-enabled examples win bonus points).

If ClawSafe helps you ship an agent, tell the world — and leave a ⭐ so others find it.

📄 License

Apache-2.0 — see LICENSE. Use it, fork it, self-host it, build a product on it.

⚠️ Disclaimer

This software is provided as is, without warranty of any kind. Transactions on Solana are irreversible. Nothing in this repository is financial advice. Always test on devnet, never fund the burner wallet beyond what you can afford to lose, and review the code you are trusting. ClawSafe is not affiliated with Solana Labs, Jupiter, the x402 working group, or https://excesssol.xyz.

⭐ Star the repo · 📦 npm package · Issues

Made for autonomous agents that deserve an allowance, not a blank check.