walletcap 0.2.2__tar.gz → 0.2.3__tar.gz

walletcap-0.2.3/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+# Publish walletcap to PyPI and npm when a GitHub Release is published, or by hand.
+# Both use trusted publishing, so no token is stored. PyPI matches this repository,
+# the workflow filename (publish.yml) and the "pypi" environment, and attaches PEP 740
+# attestations. npm matches this repository, publish.yml and the "npm" environment,
+# and attaches provenance.
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    name: PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.12"
+      - name: Check the release tag matches the package version
+        if: github.event_name == 'release'
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: test "$TAG" = "v$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")"
+      - name: Run the Python suite
+        run: |
+          python -m pip install --upgrade pytest
+          python -m pytest -q
+      - name: Build the distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  npm:
+    name: npm
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false
+      - name: Use an npm that supports trusted publishing (11.5.1 or later)
+        run: npm install --global npm@11.21.1
+      - name: Check the release tag matches the package version
+        if: github.event_name == 'release'
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: test "$TAG" = "v$(node -p "require('./js/package.json').version")"
+      - name: Run the JavaScript suite
+        working-directory: js
+        run: |
+          npm install --no-audit --no-fund --no-package-lock
+          node --test
+      - name: Publish to npm with provenance
+        working-directory: js
+        run: npm publish --provenance

walletcap-0.2.3/CHANGELOG.md

@@ -0,0 +1,58 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Changelog
+
+## 0.2.3 — 2026-11-06
+
+### Changed
+
+- Releases are published from GitHub Actions with trusted publishing: npm with provenance,
+  PyPI with PEP 740 attestations. No token is stored. A GitHub Release whose tag doesn't
+  match the package version is refused.
+
+### Fixed
+
+- `AccountCapSpender` no longer locks an account after a burst of payments. An unbounded log
+  made the first payment after 3,000 tiny ones cost about 17.7M gas, past the 2^24
+  per-transaction cap. The window is now counted in 24 buckets in a fixed ring of 25 slots, so
+  every `pay` costs the same gas. A payment counts for up to one bucket (window/24) past its
+  window, never less. The window must be a multiple of 24 seconds.
+- `walletcap awal-mcp` ran `npx -y @coinbase/payments-mcp`, which is Coinbase's installer, not
+  the MCP server. It now runs the installed server, `~/.payments-mcp/bundle.js`, and says how to
+  install it when it is missing.
+- `walletcap awal-mcp` forwarded every tool it didn't count. It now passes through only the
+  tools that move no money, and counts `send` and `make_http_request_with_x402`. It refuses
+  everything else, `trade` included, and leaves those tools out of `tools/list`, unless the
+  owner names one with `--allow-tool`. JSON-RPC batches and lines that aren't JSON are refused.
+
+### Added
+
+- `budget.guardAgentKit(provider)` puts the budget on every x402 client an AgentKit
+  `X402ActionProvider` builds. The README's subclass recipe didn't compile in TypeScript,
+  where `createX402Client` is private. `tsc` now checks the recipe against AgentKit's declared
+  types in the test suite.
+
+## 0.2.2 — 2026-11-05
+
+### Changed
+
+- A mixed-case EVM address is checked against EIP-55 before it is accepted. A bad
+  checksum is refused; all-lowercase and all-uppercase hex are still accepted.
+- A Solana CAIP-10 address is reduced to its address, so it and the bare address
+  share one budget.
+- Numeric `window` values are milliseconds in Python too, matching JavaScript.
+
+### Fixed
+
+- The rolling window cannot be shortened once the budget has spend. An edit can
+  change the cap and the per-payment limit, but it cannot reset the count by
+  shrinking the window.
+
+### Added
+
+- `SECURITY.md`, `docs/threat-model.md`, `docs/vendor-disclosure.md`, and the
+  Solidity audit status in `solidity/README.md`.
+- `examples/quickstart/` in JavaScript and Python, run in CI. No wallet, chain,
+  keys or network.
+- EIP-55, Solana CAIP-10, and window-freeze tests in both languages.
+
+## 0.2.1 — 2026-11-05

{walletcap-0.2.2 → walletcap-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: walletcap
-Version: 0.2.2
+Version: 0.2.3
 Summary: One spend budget per wallet for AI agents: counted across every process, replica, key, permission and payment rail.
 Project-URL: Homepage, https://github.com/coriolislabs/WalletCap
 Project-URL: Repository, https://github.com/coriolislabs/WalletCap
@@ -209,16 +209,23 @@ $ npx walletcap awal x402 pay https://api.example.com/data   # instead of: npx a
 $ npx walletcap awal send 0.05 0xRecipient --chain base       # instead of: npx awal send …
 ```
 
-For an MCP client such as Claude Desktop, start Coinbase's server behind walletcap. It runs
-`npx -y @coinbase/payments-mcp`; put another command after `--`.
+For an MCP client such as Claude Desktop, start Coinbase's server behind walletcap. Install the
+server once: `npx @coinbase/payments-mcp install --client other --no-auto-config` puts it in
+`~/.payments-mcp`, and walletcap runs `~/.payments-mcp/bundle.js` from there. (`npx
+@coinbase/payments-mcp` is the installer, not the server.) To run another server, put its
+command after `--`.
 
 ```json
 { "mcpServers": { "payments": { "command": "npx", "args": ["walletcap", "awal-mcp", "--wallet", "0xYourAgentWallet"] } } }
 ```
 
 - `send` and `x402 pay` (over MCP, `send` and `make_http_request_with_x402`) are checked against
-  the wallet's budget before the wallet signs anything, and counted. Every other command and tool
-  is the wallet's own.
+  the wallet's budget before the wallet signs anything, and counted. Every other CLI command is
+  the wallet's own.
+- Over MCP, 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: walletcap can't count it. `--allow-tool <name>` lets one through,
+  uncounted. JSON-RPC batches are refused.
 - 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
@@ -234,21 +241,20 @@ For an MCP client such as Claude Desktop, start Coinbase's server behind walletc
 
 ### Coinbase AgentKit
 
-AgentKit's x402 actions build their own x402 client on every call. Put the budget on that client
-with a three-line subclass, and every payment is checked against the wallet's budget before it
-is signed, whatever terms the merchant sends:
+AgentKit's x402 actions build their own x402 client on every call. `budget.guardAgentKit()` puts
+the budget on every client the provider builds, so each payment is checked against the wallet's
+budget before it is signed, whatever terms the merchant sends:
 
 ```js
 import { X402ActionProvider } from '@coinbase/agentkit';
 
-class BudgetedX402ActionProvider extends X402ActionProvider {
-  async createX402Client(walletProvider) {
-    return budget.guard(await super.createX402Client(walletProvider));
-  }
-}
-// AgentKit.from({ walletProvider, actionProviders: [new BudgetedX402ActionProvider()] })
+const x402 = budget.guardAgentKit(new X402ActionProvider());
+// AgentKit.from({ walletProvider, actionProviders: [x402] })
 ```
 
+It compiles in TypeScript, where a subclass can't override AgentKit's private
+`createX402Client`. Tested against the shape of AgentKit 0.10.4.
+
 ### Coinbase Spend Permissions, on chain
 
 For a limit the agent's own code can't go around, `solidity/src/AccountCapSpender.sol` is the
@@ -256,7 +262,9 @@ spender for Spend Permissions. Deploy it with the SpendPermissionManager, the ag
 address, the cap, the window, the per-payment max and the payees allowed. Grant Spend
 Permissions to the contract instead of the agent; the agent calls
 `pay(permission, amount, payee)`. Every permission the account grants it then shares one
-rolling cap.
+rolling cap. The window is counted in 24 buckets, so every payment costs the same gas however
+many came before it; a payment counts for up to one bucket (window/24) past its window, never
+less.
 
 ## The owner's controls
 
@@ -316,7 +324,7 @@ only for a demo or a first-run setup.
 | `tests/` | the Python suite, including the tests that drive both languages against one budget file |
 
 ```console
-$ cd js && npm install && node --test            # 61 tests
+$ cd js && npm install && node --test            # 65 tests
 $ uv run --with pytest pytest -q                 # 59 tests, from the repository root
 $ cd solidity/evm && npm install && node check.mjs ..   # the contract on an EVM, no Foundry needed
 $ cd solidity && forge test                      # the contract's canonical tests, if you have Foundry
@@ -324,7 +332,9 @@ $ cd solidity && forge test                      # the contract's canonical test
 
 The JavaScript suite runs the x402 guard against x402's own client and fetch wrapper, and runs
 restarts and racing replicas as separate processes, and drives the Agentic Wallet wrapper and
-MCP proxy against stand-ins for Coinbase's wallet and MCP server. The Python suite covers the ledger, the API,
+MCP proxy against stand-ins for Coinbase's wallet and MCP server. It builds AgentKit's x402
+client the way AgentKit 0.10.4 does, and type-checks the AgentKit recipe with `tsc` against
+AgentKit's declared types. The Python suite covers the ledger, the API,
 the CLI and one budget shared between both languages. `solidity/evm/check.mjs` compiles the
 contract with solc-js and drives it on an in-process EVM, covering what the Foundry tests cover.
 

{walletcap-0.2.2 → walletcap-0.2.3}/README.md

@@ -186,16 +186,23 @@ $ npx walletcap awal x402 pay https://api.example.com/data   # instead of: npx a
 $ npx walletcap awal send 0.05 0xRecipient --chain base       # instead of: npx awal send …
 ```
 
-For an MCP client such as Claude Desktop, start Coinbase's server behind walletcap. It runs
-`npx -y @coinbase/payments-mcp`; put another command after `--`.
+For an MCP client such as Claude Desktop, start Coinbase's server behind walletcap. Install the
+server once: `npx @coinbase/payments-mcp install --client other --no-auto-config` puts it in
+`~/.payments-mcp`, and walletcap runs `~/.payments-mcp/bundle.js` from there. (`npx
+@coinbase/payments-mcp` is the installer, not the server.) To run another server, put its
+command after `--`.
 
 ```json
 { "mcpServers": { "payments": { "command": "npx", "args": ["walletcap", "awal-mcp", "--wallet", "0xYourAgentWallet"] } } }
 ```
 
 - `send` and `x402 pay` (over MCP, `send` and `make_http_request_with_x402`) are checked against
-  the wallet's budget before the wallet signs anything, and counted. Every other command and tool
-  is the wallet's own.
+  the wallet's budget before the wallet signs anything, and counted. Every other CLI command is
+  the wallet's own.
+- Over MCP, 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: walletcap can't count it. `--allow-tool <name>` lets one through,
+  uncounted. JSON-RPC batches are refused.
 - 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
@@ -211,21 +218,20 @@ For an MCP client such as Claude Desktop, start Coinbase's server behind walletc
 
 ### Coinbase AgentKit
 
-AgentKit's x402 actions build their own x402 client on every call. Put the budget on that client
-with a three-line subclass, and every payment is checked against the wallet's budget before it
-is signed, whatever terms the merchant sends:
+AgentKit's x402 actions build their own x402 client on every call. `budget.guardAgentKit()` puts
+the budget on every client the provider builds, so each payment is checked against the wallet's
+budget before it is signed, whatever terms the merchant sends:
 
 ```js
 import { X402ActionProvider } from '@coinbase/agentkit';
 
-class BudgetedX402ActionProvider extends X402ActionProvider {
-  async createX402Client(walletProvider) {
-    return budget.guard(await super.createX402Client(walletProvider));
-  }
-}
-// AgentKit.from({ walletProvider, actionProviders: [new BudgetedX402ActionProvider()] })
+const x402 = budget.guardAgentKit(new X402ActionProvider());
+// AgentKit.from({ walletProvider, actionProviders: [x402] })
 ```
 
+It compiles in TypeScript, where a subclass can't override AgentKit's private
+`createX402Client`. Tested against the shape of AgentKit 0.10.4.
+
 ### Coinbase Spend Permissions, on chain
 
 For a limit the agent's own code can't go around, `solidity/src/AccountCapSpender.sol` is the
@@ -233,7 +239,9 @@ spender for Spend Permissions. Deploy it with the SpendPermissionManager, the ag
 address, the cap, the window, the per-payment max and the payees allowed. Grant Spend
 Permissions to the contract instead of the agent; the agent calls
 `pay(permission, amount, payee)`. Every permission the account grants it then shares one
-rolling cap.
+rolling cap. The window is counted in 24 buckets, so every payment costs the same gas however
+many came before it; a payment counts for up to one bucket (window/24) past its window, never
+less.
 
 ## The owner's controls
 
@@ -293,7 +301,7 @@ only for a demo or a first-run setup.
 | `tests/` | the Python suite, including the tests that drive both languages against one budget file |
 
 ```console
-$ cd js && npm install && node --test            # 61 tests
+$ cd js && npm install && node --test            # 65 tests
 $ uv run --with pytest pytest -q                 # 59 tests, from the repository root
 $ cd solidity/evm && npm install && node check.mjs ..   # the contract on an EVM, no Foundry needed
 $ cd solidity && forge test                      # the contract's canonical tests, if you have Foundry
@@ -301,7 +309,9 @@ $ cd solidity && forge test                      # the contract's canonical test
 
 The JavaScript suite runs the x402 guard against x402's own client and fetch wrapper, and runs
 restarts and racing replicas as separate processes, and drives the Agentic Wallet wrapper and
-MCP proxy against stand-ins for Coinbase's wallet and MCP server. The Python suite covers the ledger, the API,
+MCP proxy against stand-ins for Coinbase's wallet and MCP server. It builds AgentKit's x402
+client the way AgentKit 0.10.4 does, and type-checks the AgentKit recipe with `tsc` against
+AgentKit's declared types. The Python suite covers the ledger, the API,
 the CLI and one budget shared between both languages. `solidity/evm/check.mjs` compiles the
 contract with solc-js and drives it on an in-process EVM, covering what the Foundry tests cover.
 

{walletcap-0.2.2 → walletcap-0.2.3}/js/agentic.mjs

@@ -6,8 +6,10 @@
 // signs it, and the wallet is capped at that amount. A confirmed settlement counts for one
 // window; a payment the payee never confirms keeps counting until its owner releases it.
 import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 import { pathToFileURL } from 'node:url';
@@ -338,11 +340,28 @@ export async function awalMain(argv, { env = process.env, stdout = process.stdou
 }
 
 // ---------------------------------------------------------------------------------------------
-// npx walletcap awal-mcp [--wallet <address>] [--path <file>] [-- <server command>]: Coinbase's
-// payments-mcp server behind a proxy that counts its send and make_http_request_with_x402 calls.
+// npx walletcap awal-mcp [--wallet <address>] [--path <file>] [--allow-tool <name>]... [-- <server command>]:
+// Coinbase's Agentic Wallet MCP server behind a proxy that counts its send and
+// make_http_request_with_x402 calls, and refuses every tool it does not know.
 
 const MCP_PAYMENT_TOOLS = { make_http_request_with_x402: 'make-x402-request', send: 'send-transaction' };
-const DEFAULT_SERVER = ['npx', '-y', '@coinbase/payments-mcp'];
+
+/**
+ * The server's tools that move no money (payments-mcp 2.12.2), passed through as they are. Any
+ * other tool, `trade` included, is refused unless the wallet's owner names it with --allow-tool:
+ * a tool walletcap does not know may move money it cannot count.
+ */
+export const MCP_PASS_THROUGH_TOOLS = Object.freeze([
+  'bazaar_get_resource_details', 'bazaar_list', 'bazaar_search', 'check_session_status',
+  'get_wallet_address', 'get_wallet_balance', 'show_wallet_app', 'sign_in_with_email',
+  'verify_email_otp', 'x402_discover_payment_requirements',
+]);
+
+/**
+ * Where Coinbase's server runs from. `npx @coinbase/payments-mcp` is its installer, not the
+ * server: it downloads the server to ~/.payments-mcp, and MCP clients run bundle.js with node.
+ */
+export const paymentsMcpServer = (home = homedir()) => [process.execPath, join(home, '.payments-mcp', 'bundle.js')];
 
 const toolResult = raw => {
   const text = raw?.content?.find(item => item?.type === 'text')?.text;
@@ -356,18 +375,38 @@ const toolResult = raw => {
   }
 };
 
-/** Proxy an MCP client (stdin/stdout) to the payments-mcp server. Resolves with the server's exit code. */
-export async function awalMcpMain(argv, { env = process.env, input = process.stdin, output = process.stdout, stderr = process.stderr } = {}) {
+/**
+ * Proxy an MCP client (stdin/stdout) to Coinbase's Agentic Wallet MCP server. Payments are
+ * counted, the tools in MCP_PASS_THROUGH_TOOLS and --allow-tool pass through, and every other
+ * tool is refused and left out of tools/list. Resolves with the server's exit code.
+ */
+export async function awalMcpMain(argv, { env = process.env, input = process.stdin, output = process.stdout, stderr = process.stderr, home } = {}) {
   const split = argv.indexOf('--');
   const own = split < 0 ? argv : argv.slice(0, split);
-  const server = split < 0 ? DEFAULT_SERVER : argv.slice(split + 1);
-  const { values } = parseArgs({ args: own, options: { wallet: { type: 'string' }, path: { type: 'string' } }, strict: true });
+  const { values } = parseArgs({
+    args: own,
+    options: { wallet: { type: 'string' }, path: { type: 'string' }, 'allow-tool': { type: 'string', multiple: true } },
+    strict: true,
+  });
+  const server = split < 0 ? paymentsMcpServer(home) : argv.slice(split + 1);
+  if (server.length === 0) {
+    stderr.write('walletcap: give the MCP server command after --\n');
+    return 2;
+  }
+  if (split < 0 && !existsSync(server[1])) {
+    stderr.write(`walletcap: Coinbase's Agentic Wallet MCP server is not installed at ${server[1]}. `
+      + 'Install it once with: npx @coinbase/payments-mcp install --client other --no-auto-config '
+      + '(or give walletcap the server command after --)\n');
+    return 1;
+  }
+  const passed = new Set([...MCP_PASS_THROUGH_TOOLS, ...(values['allow-tool'] ?? [])]);
+  const offered = name => Object.hasOwn(MCP_PAYMENT_TOOLS, name) || passed.has(name);
   const child = spawn(server[0], server.slice(1), { stdio: ['pipe', 'pipe', 'inherit'], env });
   const write = (stream, message) => stream.write(`${JSON.stringify(message)}\n`);
   const pending = new Map();
-  let next = 0;
+  const listing = new Set(); // the client's tools/list requests, whose answers are filtered
   const callTool = (name, args) => new Promise((resolveCall, rejectCall) => {
-    const id = `walletcap-${next += 1}`;
+    const id = `walletcap-${randomUUID()}`;
     pending.set(id, { resolve: resolveCall, reject: rejectCall });
     write(child.stdin, { jsonrpc: '2.0', id, method: 'tools/call', params: { name, arguments: args } });
   });
@@ -376,10 +415,18 @@ export async function awalMcpMain(argv, { env = process.env, input = process.std
     let message;
     try { message = JSON.parse(line); } catch { output.write(`${line}\n`); return; }
     const waiting = pending.get(message?.id);
-    if (waiting === undefined) { output.write(`${line}\n`); return; }
-    pending.delete(message.id);
-    if (message.error) waiting.reject(new Error(message.error.message ?? JSON.stringify(message.error)));
-    else waiting.resolve(message.result);
+    if (waiting !== undefined) {
+      pending.delete(message.id);
+      if (message.error) waiting.reject(new Error(message.error.message ?? JSON.stringify(message.error)));
+      else waiting.resolve(message.result);
+      return;
+    }
+    const key = message?.id === undefined ? undefined : JSON.stringify(message.id);
+    if (key !== undefined && listing.delete(key) && Array.isArray(message.result?.tools)) {
+      write(output, { ...message, result: { ...message.result, tools: message.result.tools.filter(tool => offered(tool?.name)) } });
+      return;
+    }
+    output.write(`${line}\n`);
   });
 
   // The guard talks to the wallet through the server's own tools, one guard per call so concurrent
@@ -419,11 +466,37 @@ export async function awalMcpMain(argv, { env = process.env, input = process.std
 
   createInterface({ input }).on('line', line => {
     let message;
-    try { message = JSON.parse(line); } catch { child.stdin.write(`${line}\n`); return; }
-    if (message?.method === 'tools/call' && Object.hasOwn(MCP_PAYMENT_TOOLS, message.params?.name ?? '')) {
-      handle(message).catch(error => stderr.write(`walletcap: ${error.message}\n`));
+    try {
+      message = JSON.parse(line);
+    } catch {
+      stderr.write('walletcap: dropped a line from the MCP client that is not JSON\n');
       return;
     }
+    if (Array.isArray(message)) {
+      // A batch would carry calls past the checks below; MCP dropped batches in 2025-06-18.
+      write(output, { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'walletcap does not forward JSON-RPC batches' } });
+      return;
+    }
+    if (message?.method === 'tools/call') {
+      const name = String(message.params?.name);
+      if (Object.hasOwn(MCP_PAYMENT_TOOLS, name)) {
+        handle(message).catch(error => stderr.write(`walletcap: ${error.message}\n`));
+        return;
+      }
+      if (!passed.has(name)) {
+        write(output, {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: {
+            content: [{ type: 'text', text: `walletcap refused ${name}: it can't tell whether this tool moves money, so it can't count it. `
+              + `The wallet's owner can let it through, uncounted, with --allow-tool ${name}` }],
+            isError: true,
+          },
+        });
+        return;
+      }
+    }
+    if (message?.method === 'tools/list' && message.id !== undefined && message.id !== null) listing.add(JSON.stringify(message.id));
     child.stdin.write(`${line}\n`);
   }).on('close', () => child.stdin.end());
 

{walletcap-0.2.2 → walletcap-0.2.3}/js/cli.mjs

@@ -24,7 +24,8 @@ Commands
   history              The newest payments first
   release <id>         Give back an in-flight payment you know never left the wallet
   awal <command>       Coinbase's Agentic Wallet CLI, with send and x402 pay counted in the budget
-  awal-mcp [-- <cmd>]  Coinbase's payments-mcp server behind a proxy that counts its payments
+  awal-mcp [-- <cmd>]  Coinbase's Agentic Wallet MCP server (~/.payments-mcp) behind a proxy that
+                       counts its payments and refuses tools it can't count (--allow-tool <name>)
 
 Options
   --wallet <address>   The wallet the money leaves from (optional when the file holds one budget)

{walletcap-0.2.2 → walletcap-0.2.3}/js/index.d.ts

@@ -162,12 +162,17 @@ export declare class Budget {
   history(options?: { limit?: number }): Payment[];
   /** Count every payment an x402 client (@x402/core 2.x) makes in this budget. Returns the client. */
   guard<C extends X402HookedClient>(client: C, options?: { assets?: AssetEntry[] }): C;
+  /**
+   * Count every payment a Coinbase AgentKit X402ActionProvider makes in this budget: each x402
+   * client the provider builds is guarded before it can sign. Returns the provider.
+   */
+  guardAgentKit<P extends object>(provider: P, options?: { assets?: AssetEntry[] }): P;
   /** A SpendStore for Coinbase's CDP applySpendControls that counts in this budget. */
   cdpStore(options: { asset: string; scale?: bigint | number; clock?: () => number }): SharedBudgetStore;
   close(): void;
 }
 
-/** Open the wallet's budget, creating it on first use. */
+/** Open the wallet's budget. Its owner creates it with `walletcap set`; pass create: true only for a demo. */
 export declare function openBudget(options: BudgetOptions): Budget;
 
 /** Dollars as micro-dollars. */

{walletcap-0.2.2 → walletcap-0.2.3}/js/index.mjs

@@ -17,7 +17,7 @@ import {
   defaultBudgetPath, describeLimits, expandHome, formatUsd, formatWindow, limitFlags, MAX_AMOUNT,
   normalizeWallet, parseLimits, shortWallet, toMicros,
 } from './money.mjs';
-import { guardX402Client, USD_ASSETS } from './x402.mjs';
+import { guardX402ActionProvider, guardX402Client, USD_ASSETS } from './x402.mjs';
 
 export {
   BudgetError, BudgetRefused, defaultBudgetPath, formatUsd, MAX_AMOUNT, notSent, SCHEMA_VERSION,
@@ -304,6 +304,9 @@ export class Budget {
   /** Count every payment an x402 client (@x402/core 2.x) makes in this budget. Returns the client. */
   guard(client, options) { return guardX402Client(client, this, options); }
 
+  /** Count every payment a Coinbase AgentKit X402ActionProvider makes in this budget. Returns the provider. */
+  guardAgentKit(provider, options) { return guardX402ActionProvider(provider, this, options); }
+
   /** A SpendStore for Coinbase's CDP applySpendControls, counting in this budget. For a 6-decimal USD stablecoin. */
   cdpStore({ asset, scale = 1n, clock = Date.now } = {}) {
     return new SharedBudgetStore({ path: this.#path, instrument: this.#wallet, asset, scale, clock });

{walletcap-0.2.2 → walletcap-0.2.3}/js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "walletcap",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "One spend budget per wallet for AI agents: counted across every process, replica, key, permission and payment rail. Restarts don't reset it, limit changes don't zero it, and if it can't be read nothing is paid.",
   "license": "Apache-2.0",
   "author": "Coriolis Labs Inc.",
@@ -55,6 +55,7 @@
     "@x402/extensions": "2.28.0",
     "@x402/fetch": "2.28.0",
     "@x402/svm": "2.28.0",
+    "typescript": "5.6.3",
     "viem": "2.37.13"
   },
   "repository": {

{walletcap-0.2.2 → walletcap-0.2.3}/js/tests/agentic.test.mjs

@@ -3,12 +3,12 @@
 // server are stand-ins here; the payee is a local HTTP server that answers 402 like an x402 one.
 import assert from 'node:assert/strict';
 import { execFile, spawn, spawnSync } from 'node:child_process';
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { after, before, test } from 'node:test';
 import { BudgetRefused, openBudget } from '../index.mjs';
 import { guardAgenticWallet, usdcAtomic } from '../agentic.mjs';
@@ -202,7 +202,8 @@ test('npx walletcap awal-mcp: the MCP server answers, and payments past the cap
   };
   try {
     assert.equal((await ask(1, 'initialize', {})).serverInfo.name, 'payments-mcp');
-    assert.equal((await ask(2, 'tools/list', {})).tools.length, 3);
+    // The server also offers trade and a tool walletcap has never seen: neither is listed.
+    assert.deepEqual((await ask(2, 'tools/list', {})).tools.map(t => t.name), ['make_http_request_with_x402', 'send', 'get_wallet_balance']);
     const pay = { baseURL: base, path: '/pay?ttl=300', method: 'GET' };
     const results = [];
     for (let id = 3; id < 7; id += 1) results.push(await ask(id, 'tools/call', { name: 'make_http_request_with_x402', arguments: pay }));
@@ -211,6 +212,12 @@ test('npx walletcap awal-mcp: the MCP server answers, and payments past the cap
     const sent = await ask(7, 'tools/call', { name: 'send', arguments: { recipient: PAY_TO, amountAtomic: '50000', chain: 'base-sepolia' } });
     assert.equal(sent.isError, true);
     assert.equal((await ask(8, 'tools/call', { name: 'get_wallet_balance', arguments: {} })).content.length, 1);
+    // A tool walletcap can't count is refused before it reaches the wallet.
+    for (const [id, name] of [[9, 'trade'], [10, 'drain_wallet']]) {
+      const refused = await ask(id, 'tools/call', { name, arguments: { amount: '1000' } });
+      assert.equal(refused.isError, true);
+      assert.match(refused.content[0].text, new RegExp(`walletcap refused ${name}.*--allow-tool ${name}`));
+    }
   } finally {
     proxy.stdin.end();
     await new Promise(done => proxy.on('exit', done));
@@ -222,3 +229,60 @@ test('npx walletcap awal-mcp: the MCP server answers, and payments past the cap
   assert.equal(budget.status().spent, 150_000n);
   budget.close();
 });
+
+// Drive `npx walletcap awal-mcp` over stdio: send lines, collect answers by id.
+const mcpProxy = (args, env) => {
+  const proxy = spawn(process.execPath, [CLI, 'awal-mcp', ...args], { env: { ...process.env, ...env }, stdio: ['pipe', 'pipe', 'pipe'] });
+  const replies = new Map();
+  let stderr = '';
+  proxy.stderr.on('data', chunk => { stderr += chunk; });
+  createInterface({ input: proxy.stdout }).on('line', line => { const m = JSON.parse(line); replies.set(m.id, m); });
+  const send = line => proxy.stdin.write(`${line}\n`);
+  const reply = async id => {
+    for (let i = 0; i < 200 && !replies.has(id); i += 1) await new Promise(done => setTimeout(done, 25));
+    assert.ok(replies.has(id), `no reply to ${id}; stderr: ${stderr}`);
+    return replies.get(id);
+  };
+  const ask = async (id, method, params) => {
+    send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
+    return (await reply(id)).result;
+  };
+  const close = async () => {
+    proxy.stdin.end();
+    return new Promise(done => proxy.on('exit', code => done({ code, stderr })));
+  };
+  return { ask, send, reply, close };
+};
+
+test('npx walletcap awal-mcp runs the server Coinbase installed, not its installer', async () => {
+  const home = mkdtempSync(join(DIR, 'home-'));
+  const path = join(DIR, 'mcp-default.sqlite');
+  const log = join(DIR, 'mcp-default.log');
+  writeFileSync(log, '');
+  openBudget({ wallet: WALLET, path, perPayment: '$0.05', perDay: '$0.15', create: true }).close();
+  const env = { HOME: home, USERPROFILE: home, FAKE_MCP_LOG: log };
+
+  // Before Coinbase's installer has run, there is no server to start: say so, start nothing.
+  const missing = await mcpProxy(['--wallet', WALLET, '--path', path], env).close();
+  assert.equal(missing.code, 1);
+  assert.match(missing.stderr, /npx @coinbase\/payments-mcp install/);
+
+  // The installer leaves ~/.payments-mcp/bundle.js, an ES module MCP clients run with node.
+  mkdirSync(join(home, '.payments-mcp'));
+  writeFileSync(join(home, '.payments-mcp', 'package.json'), '{"type":"module"}');
+  writeFileSync(join(home, '.payments-mcp', 'bundle.js'), `import ${JSON.stringify(pathToFileURL(FAKE_MCP).href)};\n`);
+  const mcp = mcpProxy(['--wallet', WALLET, '--path', path, '--allow-tool', 'trade'], env);
+  try {
+    assert.equal((await mcp.ask(1, 'initialize', {})).serverInfo.name, 'payments-mcp');
+    // --allow-tool lets trade through, uncounted; a tool nobody named stays out.
+    assert.deepEqual((await mcp.ask(2, 'tools/list', {})).tools.map(t => t.name), ['make_http_request_with_x402', 'send', 'get_wallet_balance', 'trade']);
+    assert.notEqual((await mcp.ask(3, 'tools/call', { name: 'trade', arguments: {} })).isError, true);
+    assert.equal((await mcp.ask(4, 'tools/call', { name: 'drain_wallet', arguments: {} })).isError, true);
+    // A JSON-RPC batch could carry a call past those checks, so it is refused whole.
+    mcp.send(JSON.stringify([{ jsonrpc: '2.0', id: 5, method: 'tools/call', params: { name: 'drain_wallet', arguments: {} } }]));
+    assert.equal((await mcp.reply(null)).error.code, -32600);
+  } finally {
+    await mcp.close();
+  }
+  assert.deepEqual(readFileSync(log, 'utf8').trim().split('\n').map(line => JSON.parse(line).name), ['trade']);
+});