walletcap 0.2.3__tar.gz → 0.2.4__tar.gz

{walletcap-0.2.3 → walletcap-0.2.4}/.circleci/config.yml

@@ -33,6 +33,14 @@ jobs:
             cd solidity/evm
             npm install --no-audit --no-fund --no-package-lock
             node check.mjs ..
+      - run:
+          name: Crash test
+          command: |
+            cd crash-test
+            npm install --no-audit --no-fund --no-package-lock
+            npm install --no-save --no-audit --no-fund --no-package-lock ../js
+            node contracts/build.mjs --check
+            node --test
 
 workflows:
   ci:

walletcap-0.2.4/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  javascript:
+    name: JavaScript
+    runs-on: ubuntu-latest
+    container: node:22-bookworm
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Install the test dependencies
+        run: npm install --no-audit --no-fund
+        working-directory: js
+      - name: Run the suite
+        run: node --test
+        working-directory: js
+
+  python:
+    name: Python
+    runs-on: ubuntu-latest
+    container: node:22-bookworm
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+      - name: Run the suite
+        # Node is on PATH here, so the cross-language tests run rather than skip.
+        run: uv run --with pytest --python 3.12 pytest -q
+
+  solidity:
+    name: Solidity
+    runs-on: ubuntu-latest
+    container: node:22-bookworm
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Install the check's dependencies
+        run: npm install --no-audit --no-fund
+        working-directory: solidity/evm
+      - name: Drive the contract on an EVM
+        run: node check.mjs ..
+        working-directory: solidity/evm
+
+  crash-test:
+    name: Crash test
+    runs-on: ubuntu-latest
+    container: node:22-bookworm
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Install the crash test, on this checkout's walletcap
+        run: |
+          npm install --no-audit --no-fund --no-package-lock
+          npm install --no-save --no-audit --no-fund --no-package-lock ../js
+        working-directory: crash-test
+      - name: Check the shipped contracts match their sources
+        run: node contracts/build.mjs --check
+        working-directory: crash-test
+      - name: Run it
+        run: node --test
+        working-directory: crash-test
+
+  crash-test-agentkit:
+    name: Crash test (AgentKit)
+    runs-on: ubuntu-latest
+    container: node:22-bookworm
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Pack the crash test
+        run: npm pack --pack-destination "$RUNNER_TEMP"
+        working-directory: crash-test
+      # As users run it: AgentKit installed alongside, walletcap from npm.
+      - name: Run it with Coinbase AgentKit alongside
+        run: npx -y -p "$RUNNER_TEMP"/walletcap-crash-test-*.tgz -p @coinbase/agentkit@0.10.4 walletcap-crash-test --agentkit --json > "$RUNNER_TEMP/agentkit.json"
+      - name: Check the AgentKit row
+        run: node crash-test/ci/check-agentkit.mjs "$RUNNER_TEMP/agentkit.json"

walletcap-0.2.4/.github/workflows/mcp-registry.yml

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: Apache-2.0
+# Publish server.json to the official MCP Registry (registry.modelcontextprotocol.io), by hand.
+# Run it once the npm release that server.json names is out: the registry checks that
+# walletcap@<version> on npm carries "mcpName": "io.github.coriolislabs/walletcap".
+# GitHub OIDC proves the io.github.coriolislabs namespace, so no token is stored.
+# (mcp-publisher's interactive GitHub login can't publish to an organization namespace.)
+name: MCP Registry
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Publish server.json
+    runs-on: ubuntu-latest
+    env:
+      MCP_PUBLISHER_VERSION: v1.8.7
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Check server.json names the npm package's version and mcpName
+        run: |
+          test "$(jq -r .version server.json)" = "$(jq -r .version js/package.json)"
+          test "$(jq -r '.packages[0].version' server.json)" = "$(jq -r .version js/package.json)"
+          test "$(jq -r .name server.json)" = "$(jq -r .mcpName js/package.json)"
+      - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+      - name: Download mcp-publisher and verify its Sigstore bundle
+        run: |
+          set -euo pipefail
+          archive=mcp-publisher_linux_amd64.tar.gz
+          base_url="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
+          curl --fail --location --silent --show-error --output "$archive" "$base_url/$archive"
+          curl --fail --location --silent --show-error --output "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
+          cosign verify-blob \
+            --bundle "$archive.sigstore.json" \
+            --certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${MCP_PUBLISHER_VERSION}" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+            "$archive"
+          tar xzf "$archive" mcp-publisher
+          rm -f "$archive" "$archive.sigstore.json"
+      - name: Log in to the registry with GitHub OIDC
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

{walletcap-0.2.3 → walletcap-0.2.4}/.github/workflows/publish.yml

@@ -1,9 +1,11 @@
 # 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,
+# Publish when a GitHub Release is published, or by hand.
+# - A release tagged v<version> publishes walletcap to PyPI and npm.
+# - A release tagged crash-test-v<version> publishes walletcap-crash-test to npm, and nothing else.
+# Everything uses 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.
+# attestations. npm matches this repository, publish.yml and the "npm" environment, for
+# each of the two packages, and attaches provenance.
 name: Publish
 
 on:
@@ -18,6 +20,7 @@ permissions:
 jobs:
   pypi:
     name: PyPI
+    if: github.event_name != 'release' || !startsWith(github.event.release.tag_name, 'crash-test-v')
     runs-on: ubuntu-latest
     environment: pypi
     steps:
@@ -43,6 +46,7 @@ jobs:
 
   npm:
     name: npm
+    if: github.event_name != 'release' || !startsWith(github.event.release.tag_name, 'crash-test-v')
     runs-on: ubuntu-latest
     environment: npm
     steps:
@@ -67,3 +71,30 @@ jobs:
       - name: Publish to npm with provenance
         working-directory: js
         run: npm publish --provenance
+
+  crash-test:
+    name: npm (crash test)
+    if: github.event_name == 'release' && startsWith(github.event.release.tag_name, 'crash-test-v')
+    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
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: test "$TAG" = "crash-test-v$(node -p "require('./crash-test/package.json').version")"
+      - name: Run the crash test on the walletcap users get from npm
+        working-directory: crash-test
+        run: |
+          npm install --no-audit --no-fund --no-package-lock
+          node --test
+      - name: Publish to npm with provenance
+        working-directory: crash-test
+        run: npm publish --provenance

{walletcap-0.2.3 → walletcap-0.2.4}/CHANGELOG.md

@@ -1,6 +1,25 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 # Changelog
 
+## 0.2.4 — 2026-11-06
+
+### Added
+
+- `mcpName` in the npm package and a `server.json`, so `walletcap awal-mcp` can be listed in the
+  official MCP Registry as `io.github.coriolislabs/walletcap`. `glama.json` names the maintainer
+  for Glama.
+- A docs site, https://coriolislabs.github.io/WalletCap/, with one page per integration, and
+  `llms.txt`.
+
+### Fixed
+
+- The `create` doc comment in `index.d.ts` said it defaulted to true. It defaults to false.
+
+### Changed
+
+- Package descriptions and search keywords on npm and PyPI, and a README that leads with the
+  crash test.
+
 ## 0.2.3 — 2026-11-06
 
 ### Changed

walletcap-0.2.3/README.md → walletcap-0.2.4/PKG-INFO

@@ -1,17 +1,84 @@
+Metadata-Version: 2.5
+Name: walletcap
+Version: 0.2.4
+Summary: Spend limits for AI agent wallets: a per-payment cap and rolling 24-hour budget that holds across restarts, kept in a SQLite file every process and the npm package share.
+Project-URL: Homepage, https://github.com/coriolislabs/WalletCap
+Project-URL: Repository, https://github.com/coriolislabs/WalletCap
+Project-URL: Issues, https://github.com/coriolislabs/WalletCap/issues
+Author: Coriolis Labs Inc.
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agent-payments,agent-wallet,ai-agent,ai-agents,budget,guardrails,spend-limit,spending-limit,stablecoin,usdc,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
 <!-- SPDX-License-Identifier: Apache-2.0 -->
-# walletcap
+# walletcap: spend limits for AI agent wallets
+
+[![npm](https://img.shields.io/npm/v/walletcap?label=npm)](https://www.npmjs.com/package/walletcap)
+[![PyPI](https://img.shields.io/pypi/v/walletcap?label=PyPI)](https://pypi.org/project/walletcap/)
+[![CI](https://github.com/coriolislabs/WalletCap/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/coriolislabs/WalletCap/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/coriolislabs/WalletCap/blob/main/LICENSE)
+
+**Spend limits for AI agent wallets that pay in USDC: a per-payment cap and a rolling 24-hour
+budget that holds across restarts, replicas and payment rails.** walletcap plugs into x402
+clients, Coinbase CDP's x402 spend controls, Coinbase AgentKit, the Coinbase Agentic Wallet CLI
+and payments MCP server, and Coinbase Spend Permissions. By ShadowPath.
+
+## Crash test: CDP's controls let $1,600–$1,700 past a $150 cap, walletcap lets $0
+
+`npx walletcap-crash-test` puts Coinbase's agent spend controls through four ordinary events (a
+restart, 10 replicas, 10 replicas on a shared store, and a payee who asks for EURC), then puts
+walletcap through the same events. CDP's x402 controls are set as Coinbase's README shows, then
+run again on walletcap's `cdpStore` as this README shows. Spend Permissions run Coinbase's
+deployed contract code on a local EVM. Every agent is held to $50 a payment and $150 in any 24
+hours, in USDC on Base. It runs offline in about 15 seconds and sends nothing.
+
+```console
+$ npx walletcap-crash-test
+```
+
+| CDP x402 spend controls | CDP's controls | walletcap guard | walletcap cdpStore |
+|---|---|---|---|
+| restart, then pay again | $300 signed · $150 over | $150 signed · $0 over | $150 signed · $0 over |
+| 10 replicas | $1,500 signed · $1,350 over | $150 signed · $0 over | $150 signed · $0 over |
+| 10 replicas, shared store 1 ms away | $350 signed · $200 over | $150 signed · $0 over | $150 signed · $0 over |
+| payee asks for EURC, not USDC | 1,000 EURC signed, counted as $0 | refused before signing | refused before signing |
 
-[![CircleCI](https://dl.circleci.com/status-badge/img/circleci/9kf5Wo9wYAuLZHsV9nFTQC/Pcdc3JTt5shsZfYpip6SBB/tree/main.svg?style=svg)](https://app.circleci.com/pipelines/circleci/9kf5Wo9wYAuLZHsV9nFTQC/Pcdc3JTt5shsZfYpip6SBB)
+| Spend Permissions | SpendPermissionManager | AccountCapSpender |
+|---|---|---|
+| a second permission | $300 pulled · $150 over | $150 pulled · $0 over |
+| across a period boundary, 1 second apart | $300 pulled · $150 over | $150 pulled · $0 over |
 
-**Your agent's spending limit forgets. This one doesn't.** By ShadowPath.
+Past the $150 cap: $1,700 and 1,000 EURC with CDP's controls, $300 with Spend Permissions; $0
+with walletcap's guard, its cdpStore and AccountCapSpender. The shared-store row varies from
+run to run: in eight runs on 6 November 2026 it was $100 over five times and $200 over three
+times. Those runs used `@coinbase/cdp-sdk` 1.61.0, `@x402/core` 2.30.0, SpendPermissionManager
+1.0.0 and walletcap 0.2.3.
 
-Agent payment kits count "spent so far" per process, per key, per permission or per
-period. So a restart, a second replica, one more key, or the next period hands the agent a
-fresh budget. walletcap counts **per wallet**: one budget that every process,
-replica, key, permission and payment rail spends from.
+Add `--agentkit` for Coinbase AgentKit's row: the agent approves a 1¢ offer, and AgentKit signs
+the merchant's first-listed $1.00 on Base mainnet. walletcap, at 2¢ a payment, refuses it before
+signing. [The crash test's README](https://github.com/coriolislabs/WalletCap/tree/main/crash-test)
+says exactly what runs.
 
-The owner creates the budget once. Opening it never creates one; pass `create: true` only
-for a demo or first-run setup:
+## Install and use
+
+```console
+$ npm install walletcap     # Node 22.13+, no dependencies
+$ pip install walletcap     # Python 3.11+, no dependencies
+```
+
+The owner creates the budget once. Opening it never creates one; pass `create: true` only for a
+demo or first-run setup:
 
 ```console
 $ npx walletcap set --wallet 0xYourAgentWallet --per-payment 50 --per-day 150
@@ -34,8 +101,18 @@ with budget.pay("$12.50"):
     send_usdc(payee, "12.50")
 ```
 
-`npm install walletcap` (Node 22.13+) · `pip install walletcap` (Python 3.11+) ·
-no dependencies · Apache-2.0
+| Integration | Install | Use |
+|---|---|---|
+| [Any x402 client](https://github.com/coriolislabs/WalletCap/blob/main/docs/x402-spending-limit.md) (`@x402/core`, `@x402/fetch`) | `npm install walletcap` | `budget.guard(client)` |
+| [Coinbase CDP x402 spend controls](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-cdp-spend-controls.md) | `npm install walletcap @coinbase/cdp-sdk` | `store: budget.cdpStore({ asset: USDC })` in `applySpendControls` |
+| [Coinbase AgentKit](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-agentkit-spending-limit.md) | `npm install walletcap @coinbase/agentkit` | `budget.guardAgentKit(new X402ActionProvider())` |
+| [Coinbase Agentic Wallet CLI](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-agentic-wallet-budget.md) | `npm install walletcap awal` | `npx walletcap awal x402 pay <url>` |
+| [Coinbase payments MCP server](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-agentic-wallet-budget.md#the-mcp-server-one-entry-in-the-clients-config) | `npx @coinbase/payments-mcp install --client other --no-auto-config` | MCP server command: `npx walletcap awal-mcp --wallet 0x…` |
+| [Coinbase Spend Permissions](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-spend-permissions-cap.md) | deploy `solidity/src/AccountCapSpender.sol` (testnet only, unaudited) | the agent calls `pay(permission, amount, payee)` |
+| [Python](https://github.com/coriolislabs/WalletCap/blob/main/docs/python-agent-spending-limit.md) | `pip install walletcap` | `with budget.pay("$12.50"):` |
+
+Each link opens a page with a full snippet. The [Use it](#use-it) section below covers every
+integration too.
 
 ## Try it without a wallet
 
@@ -298,7 +375,10 @@ only for a demo or a first-run setup.
 | `js/` | the npm package `walletcap`: the budget, the x402 guard, the CDP store, the CLI, and the Agentic Wallet CLI wrapper and MCP proxy |
 | `src/walletcap/` | the PyPI package `walletcap`, on the same file format |
 | `solidity/` | `AccountCapSpender`, the on-chain cap for Coinbase Spend Permissions |
+| `crash-test/` | the crash test: CDP's spend controls and walletcap through the same events, in dollars |
 | `tests/` | the Python suite, including the tests that drive both languages against one budget file |
+| `docs/` | the docs site for GitHub Pages: one page per integration, each with a full snippet, plus the threat model |
+| `llms.txt` | a summary of the package and links to the docs, for language models |
 
 ```console
 $ cd js && npm install && node --test            # 65 tests

walletcap-0.2.3/PKG-INFO → walletcap-0.2.4/README.md

@@ -1,40 +1,61 @@
-Metadata-Version: 2.5
-Name: walletcap
-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
-Project-URL: Issues, https://github.com/coriolislabs/WalletCap/issues
-Author: Coriolis Labs Inc.
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: agent-payments,ai-agents,budget,guardrails,spend-limit,stablecoin,usdc,x402
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
 <!-- SPDX-License-Identifier: Apache-2.0 -->
-# walletcap
+# walletcap: spend limits for AI agent wallets
+
+[![npm](https://img.shields.io/npm/v/walletcap?label=npm)](https://www.npmjs.com/package/walletcap)
+[![PyPI](https://img.shields.io/pypi/v/walletcap?label=PyPI)](https://pypi.org/project/walletcap/)
+[![CI](https://github.com/coriolislabs/WalletCap/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/coriolislabs/WalletCap/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/coriolislabs/WalletCap/blob/main/LICENSE)
+
+**Spend limits for AI agent wallets that pay in USDC: a per-payment cap and a rolling 24-hour
+budget that holds across restarts, replicas and payment rails.** walletcap plugs into x402
+clients, Coinbase CDP's x402 spend controls, Coinbase AgentKit, the Coinbase Agentic Wallet CLI
+and payments MCP server, and Coinbase Spend Permissions. By ShadowPath.
+
+## Crash test: CDP's controls let $1,600–$1,700 past a $150 cap, walletcap lets $0
+
+`npx walletcap-crash-test` puts Coinbase's agent spend controls through four ordinary events (a
+restart, 10 replicas, 10 replicas on a shared store, and a payee who asks for EURC), then puts
+walletcap through the same events. CDP's x402 controls are set as Coinbase's README shows, then
+run again on walletcap's `cdpStore` as this README shows. Spend Permissions run Coinbase's
+deployed contract code on a local EVM. Every agent is held to $50 a payment and $150 in any 24
+hours, in USDC on Base. It runs offline in about 15 seconds and sends nothing.
+
+```console
+$ npx walletcap-crash-test
+```
+
+| CDP x402 spend controls | CDP's controls | walletcap guard | walletcap cdpStore |
+|---|---|---|---|
+| restart, then pay again | $300 signed · $150 over | $150 signed · $0 over | $150 signed · $0 over |
+| 10 replicas | $1,500 signed · $1,350 over | $150 signed · $0 over | $150 signed · $0 over |
+| 10 replicas, shared store 1 ms away | $350 signed · $200 over | $150 signed · $0 over | $150 signed · $0 over |
+| payee asks for EURC, not USDC | 1,000 EURC signed, counted as $0 | refused before signing | refused before signing |
 
-[![CircleCI](https://dl.circleci.com/status-badge/img/circleci/9kf5Wo9wYAuLZHsV9nFTQC/Pcdc3JTt5shsZfYpip6SBB/tree/main.svg?style=svg)](https://app.circleci.com/pipelines/circleci/9kf5Wo9wYAuLZHsV9nFTQC/Pcdc3JTt5shsZfYpip6SBB)
+| Spend Permissions | SpendPermissionManager | AccountCapSpender |
+|---|---|---|
+| a second permission | $300 pulled · $150 over | $150 pulled · $0 over |
+| across a period boundary, 1 second apart | $300 pulled · $150 over | $150 pulled · $0 over |
 
-**Your agent's spending limit forgets. This one doesn't.** By ShadowPath.
+Past the $150 cap: $1,700 and 1,000 EURC with CDP's controls, $300 with Spend Permissions; $0
+with walletcap's guard, its cdpStore and AccountCapSpender. The shared-store row varies from
+run to run: in eight runs on 6 November 2026 it was $100 over five times and $200 over three
+times. Those runs used `@coinbase/cdp-sdk` 1.61.0, `@x402/core` 2.30.0, SpendPermissionManager
+1.0.0 and walletcap 0.2.3.
 
-Agent payment kits count "spent so far" per process, per key, per permission or per
-period. So a restart, a second replica, one more key, or the next period hands the agent a
-fresh budget. walletcap counts **per wallet**: one budget that every process,
-replica, key, permission and payment rail spends from.
+Add `--agentkit` for Coinbase AgentKit's row: the agent approves a 1¢ offer, and AgentKit signs
+the merchant's first-listed $1.00 on Base mainnet. walletcap, at 2¢ a payment, refuses it before
+signing. [The crash test's README](https://github.com/coriolislabs/WalletCap/tree/main/crash-test)
+says exactly what runs.
 
-The owner creates the budget once. Opening it never creates one; pass `create: true` only
-for a demo or first-run setup:
+## Install and use
+
+```console
+$ npm install walletcap     # Node 22.13+, no dependencies
+$ pip install walletcap     # Python 3.11+, no dependencies
+```
+
+The owner creates the budget once. Opening it never creates one; pass `create: true` only for a
+demo or first-run setup:
 
 ```console
 $ npx walletcap set --wallet 0xYourAgentWallet --per-payment 50 --per-day 150
@@ -57,8 +78,18 @@ with budget.pay("$12.50"):
     send_usdc(payee, "12.50")
 ```
 
-`npm install walletcap` (Node 22.13+) · `pip install walletcap` (Python 3.11+) ·
-no dependencies · Apache-2.0
+| Integration | Install | Use |
+|---|---|---|
+| [Any x402 client](https://github.com/coriolislabs/WalletCap/blob/main/docs/x402-spending-limit.md) (`@x402/core`, `@x402/fetch`) | `npm install walletcap` | `budget.guard(client)` |
+| [Coinbase CDP x402 spend controls](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-cdp-spend-controls.md) | `npm install walletcap @coinbase/cdp-sdk` | `store: budget.cdpStore({ asset: USDC })` in `applySpendControls` |
+| [Coinbase AgentKit](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-agentkit-spending-limit.md) | `npm install walletcap @coinbase/agentkit` | `budget.guardAgentKit(new X402ActionProvider())` |
+| [Coinbase Agentic Wallet CLI](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-agentic-wallet-budget.md) | `npm install walletcap awal` | `npx walletcap awal x402 pay <url>` |
+| [Coinbase payments MCP server](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-agentic-wallet-budget.md#the-mcp-server-one-entry-in-the-clients-config) | `npx @coinbase/payments-mcp install --client other --no-auto-config` | MCP server command: `npx walletcap awal-mcp --wallet 0x…` |
+| [Coinbase Spend Permissions](https://github.com/coriolislabs/WalletCap/blob/main/docs/coinbase-spend-permissions-cap.md) | deploy `solidity/src/AccountCapSpender.sol` (testnet only, unaudited) | the agent calls `pay(permission, amount, payee)` |
+| [Python](https://github.com/coriolislabs/WalletCap/blob/main/docs/python-agent-spending-limit.md) | `pip install walletcap` | `with budget.pay("$12.50"):` |
+
+Each link opens a page with a full snippet. The [Use it](#use-it) section below covers every
+integration too.
 
 ## Try it without a wallet
 
@@ -321,7 +352,10 @@ only for a demo or a first-run setup.
 | `js/` | the npm package `walletcap`: the budget, the x402 guard, the CDP store, the CLI, and the Agentic Wallet CLI wrapper and MCP proxy |
 | `src/walletcap/` | the PyPI package `walletcap`, on the same file format |
 | `solidity/` | `AccountCapSpender`, the on-chain cap for Coinbase Spend Permissions |
+| `crash-test/` | the crash test: CDP's spend controls and walletcap through the same events, in dollars |
 | `tests/` | the Python suite, including the tests that drive both languages against one budget file |
+| `docs/` | the docs site for GitHub Pages: one page per integration, each with a full snippet, plus the threat model |
+| `llms.txt` | a summary of the package and links to the docs, for language models |
 
 ```console
 $ cd js && npm install && node --test            # 65 tests

walletcap-0.2.4/crash-test/README.md

@@ -0,0 +1,124 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# walletcap crash test
+
+This puts Coinbase's agent spend controls through the events that hand an AI agent a fresh budget, runs walletcap through the same events, and counts what gets past the cap.
+
+| Control | Events |
+|---|---|
+| CDP's x402 controls, on their own store and on walletcap's | a restart, replicas, a shared store, a payee who switches assets |
+| Spend Permissions | a second permission, a period boundary |
+| AgentKit (`--agentkit`) | a merchant who lists a bigger offer first |
+
+It runs offline in under fifteen seconds and sends nothing.
+
+```console
+$ npx walletcap-crash-test
+
+walletcap crash test: Coinbase's agent spend controls
+@coinbase/cdp-sdk 1.61.0 · @x402/core 2.30.0 · SpendPermissionManager 1.0.0 · walletcap 0.2.3
+Every agent is held to $50 a payment and $150 in any 24 hours, in USDC on Base.
+
+CDP x402 spend controls                      CDP's controls                     walletcap guard          walletcap cdpStore
+  restart, then pay again                    $300 signed · $150 over            $150 signed · $0 over    $150 signed · $0 over
+  10 replicas                                $1,500 signed · $1,350 over        $150 signed · $0 over    $150 signed · $0 over
+  10 replicas, shared store 1 ms away        $350 signed · $200 over            $150 signed · $0 over    $150 signed · $0 over
+  payee asks for EURC, not USDC              1,000 EURC signed, counted as $0   refused before signing   refused before signing
+
+Spend Permissions                            SpendPermissionManager             AccountCapSpender
+  a second permission                        $300 pulled · $150 over            $150 pulled · $0 over
+  across a period boundary, 1 second apart   $300 pulled · $150 over            $150 pulled · $0 over
+
+Past the $150 cap: $1,700 and 1,000 EURC with CDP's controls, $300 with Spend Permissions;
+$0 with walletcap's guard and AccountCapSpender; $0 with CDP's controls on walletcap's cdpStore.
+```
+
+It needs Node 22.13 or later. Add `--json` for machine-readable results; each event's `cdp`, `walletcap` and `cdpStore` hold the three columns. The process exits 1 if walletcap's guard, CDP's controls on walletcap's cdpStore, or any other walletcap control lets anything past the cap.
+
+To run it from this repository instead: `cd crash-test && npm install && npm start`.
+
+## What runs
+
+Every agent is a separate Node process with its own throwaway key. It builds an `@x402/core` client with the exact EVM scheme and tries its payments.
+
+The three controls:
+- **CDP's controls:** `applySpendControls` from `@coinbase/cdp-sdk/x402`, the same guardrails `CdpX402Client` uses. The settings follow Coinbase's README example: per-payment and cumulative caps in USDC, Base only, and no asset allowlist. Like `CdpX402Client`, the agent turns off x402's own default cap.
+- **walletcap guard:** `budget.guard()` on the same client. The owner sets the budget once, and every agent opens the same file.
+- **walletcap cdpStore:** CDP's own `applySpendControls` again, set exactly as [walletcap's README](https://github.com/coriolislabs/WalletCap#coinbase-cdp-spend-controls) shows: the same caps, `allowedAssets: [USDC]`, and `store: budget.cdpStore({ asset: USDC })`. The owner sets the budget once, and every agent, replica or restart opens the same file, so CDP's ledger is that file.
+
+The events, each from a fresh start, once per control:
+
+| Event | What happens |
+|---|---|
+| Restart | One process pays until it is refused. A second process, the restart, pays again. |
+| 10 replicas | Ten processes start together and pay. |
+| 10 replicas, shared store | The same, with CDP's ledger in one shared store built to its `SpendStore` interface. In the cdpStore column, walletcap's store answers each call after the same 1 ms. |
+| EURC instead of USDC | The payee asks for 1,000 EURC. |
+
+The shared store is what Coinbase's docs advise for replicas: "implement this interface against a shared durable backend (Redis, Postgres, DynamoDB, etc.)". The store in `spend-store.mjs` does exactly what the interface says, and answers each call after 1 ms, as a network database does.
+
+The interface has no single step that both checks the cap and records the payment. CDP reads the total, decides, then appends, and its lock covers one process. Replicas can read the same total before any of them appends. How many overlap varies from run to run.
+
+walletcap's cdpStore sits behind the same interface, so CDP still reads, decides, then appends. Its `append` re-checks the cap inside one SQLite write transaction and throws if the payment would go past it. CDP appends before it signs, so a payment the store refuses is never signed. In the replica rows, the re-check usually refuses a few payments that CDP's own check had passed (`budget_budget` in `--json`); how many varies from run to run. In the EURC row, CDP's `allowedAssets`, which walletcap's README sets, refuses before the store is asked.
+
+## Coinbase Spend Permissions
+
+Coinbase's `SpendPermissionManager` v1.0.0 and Smart Wallet run on an in-process EVM. Their code is the exact runtime code deployed on Base mainnet, read once with `eth_getCode` and shipped in `contracts/coinbase-base-mainnet.json` with each code hash, so the crash test needs no network.
+
+A Smart Wallet holds $1,000 of a test token that stands in for USDC, and grants the agent permissions of $150 a day.
+
+| Event | What happens |
+|---|---|
+| A second permission | The wallet grants two permissions with different salts, and the agent pulls $150 from each. |
+| A period boundary | The agent pulls $150 in the last second of one day and $150 in the first second of the next. |
+
+The manager counts each permission, and each period, on its own, so both events pull $300. Within one permission and one period it holds: the test suite checks that a fourth $50 is refused with `ExceededSpendPermission`.
+
+walletcap's side: the wallet grants the same permissions to `AccountCapSpender`, walletcap's on-chain spender. It counts every permission against one rolling $150 cap and refuses the second $150 with `OverBudget`. `AccountCapSpender` is unaudited.
+
+`node contracts/build.mjs --check` checks two things: that each piece of Coinbase code still matches its recorded hash, and that the shipped `AccountCapSpender` still compiles from `solidity/`. `--fetch` re-reads Coinbase's code from Base mainnet.
+
+## Coinbase AgentKit (`--agentkit`)
+
+```console
+$ npx -p walletcap-crash-test -p @coinbase/agentkit@0.10.4 walletcap-crash-test --agentkit
+
+Coinbase AgentKit 0.10.4: the agent approves the merchant's 1¢ offer on Base Sepolia; the merchant
+lists $1.00 on Base mainnet, to another address, first.
+
+AgentKit                         signed $1.00 on Base mainnet to the first-listed address, valid 4 days; reported $0.01 on Base Sepolia
+walletcap, 2¢ a payment          refused before signing
+```
+
+The AgentKit row runs AgentKit's own `retry_http_request_with_x402` action against a merchant on `127.0.0.1`. The agent hands it the 1¢ offer it approved, which is how AgentKit's flow works.
+
+What AgentKit does with it:
+- It checks only that the approved offer's network is one the wallet supports.
+- It then builds a fresh x402 client, which pays whatever the merchant listed first.
+- Its answer reports the approved offer, not the one it signed.
+
+walletcap's `budget.guardAgentKit()`, at 2¢ a payment, refuses the $1.00 before anything is signed.
+
+AgentKit is opt-in because it installs about 1.3 GB. Its wallet providers also send an analytics event with the wallet's address when they start. The crash test turns that off and blocks every request except the one to the local merchant.
+
+## What "signed" means
+
+Nothing is sent. Each payment is an x402 authorization (EIP-3009) signed with a key that holds nothing. A payee holding one could settle it on Base until it expires, so signing is the moment the money is committed. The crash test counts what each control lets the agent sign.
+
+## What it doesn't cover
+
+- **Settlement of x402 payments.** For x402 it measures what the client-side control lets the agent sign, not what lands on chain. The Spend Permissions rows do move tokens on the local EVM.
+- **More than one machine.** The replicas share one machine, and walletcap's budget file, behind both its guard and its cdpStore, is single-host.
+- **A revoke in the same block.** A revoke that lands after the agent's payment in the same block doesn't stop that payment, with either control. Neither control can make a revoke retroactive.
+- **Other vendors' controls.** Coinbase's CDP x402 controls, Spend Permissions and AgentKit are covered so far. The Agentic Wallet, Safe, MetaMask, Tempo and AP2 come next.
+
+Coinbase's contract code in `contracts/coinbase-base-mainnet.json` comes from [coinbase/spend-permissions](https://github.com/coinbase/spend-permissions) and [coinbase/smart-wallet](https://github.com/coinbase/smart-wallet), both under the MIT license.
+
+## Releasing
+
+To release a new version:
+1. Bump `version` in `crash-test/package.json` and merge the change.
+2. Publish a GitHub Release tagged `crash-test-v<version>`. Untick "Set as the latest release", so walletcap's own release stays the latest.
+
+The Publish workflow then runs the crash test against the walletcap on npm and publishes with provenance. Releases tagged `v<version>` publish walletcap only.
+
+To have the same measurement run against your own agent, inside your walls, with every control on and a signed result, [ask for a ShadowPath report](mailto:paul@coriolislabs.ca).