walletcap

Coinbase Agentic Wallet and payments MCP budget

You give an agent Coinbase’s Agentic Wallet, through the awal CLI or through the payments MCP server in Claude Desktop or another MCP client, and you want a dollar limit per payment and per day on what it sends and pays. npx walletcap awal and npx walletcap awal-mcp run the wallet’s CLI and MCP server through walletcap. Every send and x402 payment is checked against the wallet’s budget before the wallet signs anything, and counted, whichever process, session or machine makes it.

The CLI: one word in front of awal

$ npm install walletcap awal
$ npx walletcap set --wallet 0xYourAgentWallet --per-payment 0.05 --per-day 0.15
$ npx walletcap awal x402 pay https://api.example.com/data   # instead of: npx awal x402 pay …
$ npx walletcap awal send 0.05 0xRecipient --chain base       # instead of: npx awal send …

send and x402 pay are checked and counted by walletcap. Every other command is the wallet’s own.

The MCP server: one entry in the client’s config

Install Coinbase’s server once. It goes to ~/.payments-mcp, and walletcap runs ~/.payments-mcp/bundle.js from there. Run on its own, npx @coinbase/payments-mcp is the installer:

$ npx @coinbase/payments-mcp install --client other --no-auto-config

Then start the server behind walletcap from the MCP client, Claude Desktop for example:

{ "mcpServers": { "payments": { "command": "npx", "args": ["walletcap", "awal-mcp", "--wallet", "0xYourAgentWallet"] } } }

• send and make_http_request_with_x402 are checked against the wallet’s budget before the wallet signs anything, and counted.
• The tools that move no money (balance, address, sign-in, bazaar search, payment discovery) pass through. Any other tool, trade or one the server adds later, is refused and left out of the tool list, because walletcap can’t count it. --allow-tool <name> lets one through, uncounted.
• JSON-RPC batches are refused.
• To run another server, put its command after --.

What gets counted

• An x402 payment is priced from the endpoint’s own 402 answer, and the wallet is capped at exactly that amount, so it refuses to sign for more.
• A payment the payee confirms as settled counts for one window. One it doesn’t confirm keeps counting until you check the chain and run npx walletcap release <id>.
• A refusal from the wallet before it signs gives the amount back. Any other failure keeps counting.
• Only USDC is counted; a send in any other asset is refused.
• Machines share a budget when they share its file (a shared volume).
• It binds the payments that go through it, so keep the real awal out of the agent’s reach.

What the tests check: 11 tests of walletcap awal and walletcap awal-mcp

The test suite drives both commands against stand-ins for Coinbase’s wallet and MCP server. Among them:

• sends count in the wallet’s budget, and the one past the cap never reaches the wallet;
• the wallet is capped at exactly the price walletcap checked;
• assets walletcap cannot price are refused before the wallet is asked;
• two machines on one budget share one cap;
• npx walletcap awal: payments are counted, everything else is awal;
• npx walletcap awal-mcp: the MCP server answers, and payments past the cap never reach it.

Links

• README: Coinbase Agentic Wallet and the wrapper’s source
• Tests: agentic.test.mjs
• The owner’s controls: walletcap status, set, freeze, history and release
• All pages. Other stacks: any x402 client, Coinbase AgentKit, Python

This site is open source. Improve this page.