walletcap 0.2.0__tar.gz

walletcap-0.2.0/.circleci/config.yml

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+# CircleCI runs the same gate as scripts/ci.sh, directly from the GitHub repo.
+version: 2.1
+
+jobs:
+  test:
+    docker:
+      - image: cimg/node:22.18
+    steps:
+      - checkout
+      - run:
+          name: JavaScript
+          command: |
+            cd js
+            npm install --no-audit --no-fund --no-package-lock
+            node --test
+      - run:
+          name: Python
+          command: |
+            sudo apt-get update -qq
+            sudo apt-get install -y -qq python3 python3-venv
+            python3 -m venv /tmp/venv
+            /tmp/venv/bin/pip install --quiet pytest
+            /tmp/venv/bin/python -m pytest -q
+      - run:
+          name: Solidity
+          command: |
+            cd solidity/evm
+            npm install --no-audit --no-fund --no-package-lock
+            node check.mjs ..
+
+workflows:
+  ci:
+    jobs:
+      - test

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

@@ -0,0 +1,47 @@
+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

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

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+# Publish walletcap to PyPI when a GitHub Release is published, or by hand.
+# PyPI trusted publishing matches this repository, the workflow filename
+# (publish.yml) and the "pypi" environment; no API token is stored.
+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: 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

walletcap-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+out/
+cache/
+work/
+
+# The fake awal stand-in in the tests is committed on purpose: the CLI test
+# needs its dist/ layout, and the dist/ rule above would hide it.
+!js/tests/support/fake-awal/dist/
+!js/tests/support/fake-awal/dist/**

walletcap-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

walletcap-0.2.0/NOTICE

@@ -0,0 +1,11 @@
+SPDX-License-Identifier: Apache-2.0
+
+walletcap, by ShadowPath
+Copyright 2026 Coriolis Labs Inc.
+
+This distribution is licensed under the Apache License 2.0. It is separate from
+the ShadowPath product, which is proprietary and is not included here.
+
+AccountCapSpender's ISpendPermissionManager interface restates the struct layout
+of Coinbase's SpendPermissionManager so the contract can call it; it contains no
+Coinbase code.

walletcap-0.2.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.5
+Name: walletcap
+Version: 0.2.0
+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
+
+[![CircleCI](https://dl.circleci.com/status-badge/img/circleci/9kf5Wo9wYAuLZHsV9nFTQC/Pcdc3JTt5shsZfYpip6SBB/tree/main.svg?style=svg)](https://app.circleci.com/pipelines/circleci/9kf5Wo9wYAuLZHsV9nFTQC/Pcdc3JTt5shsZfYpip6SBB)
+
+**Your agent's spending limit forgets. This one doesn't.** By ShadowPath.
+
+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.
+
+```js
+import { openBudget } from 'walletcap';
+
+const budget = openBudget({ wallet: account.address, perPayment: '$50', perDay: '$150' });
+
+await budget.pay('$12.50', () => sendUsdc(payee, '12.50')); // refused past $150 in any 24h, restarts included
+```
+
+```python
+from walletcap import open_budget
+
+budget = open_budget(agent_address, per_payment="$50", per_day="$150")
+
+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
+
+## Why a per-wallet count
+
+Most agent spend controls keep "spent so far" next to something temporary or repeatable: a
+process, a browser window, an API key, a delegate, one permission, or a fixed calendar period.
+The money, though, sits in one wallet. When the count and the wallet don't match, ordinary
+events (a restart, a second replica, another key or permission, the next period) can hand the
+agent a fresh budget against the same money.
+
+ShadowPath measures spend controls against that pattern, on owned test chains with the vendors'
+own code. Findings go to the vendors first; this package is the fix, not the findings.
+
+## The fix: four rules
+
+1. **Count per wallet.** The budget belongs to the account the money leaves from, not to a
+   process, key, permission or delegate. Every payment from that wallet reserves against one
+   number. Checksummed, lowercase and CAIP-10 forms of an address are one wallet, so they
+   can't split it.
+2. **Count over a rolling window.** "$150 a day" means any 24 hours: there is no period
+   boundary to straddle.
+3. **Changing a limit never resets the count.** Raising $150 to $200 after spending $150
+   leaves $50, not $200. A restart can lower a limit but never raise one: if the code comes
+   back asking for looser limits (a kit's defaults, say), the stored limits stay and you get a
+   warning with the command that raises them on purpose.
+4. **Fail closed.** If the count can't be read, nothing pays. A payment whose outcome is
+   unknown keeps counting, because a payment that failed halfway may still have moved money.
+
+The count lives in a SQLite file that every process on the machine shares, and each payment is
+reserved inside one write transaction, so replicas racing for the last dollar can't both win.
+JavaScript and Python read and write the same file.
+
+## Use it
+
+### Any payment, any rail
+
+`pay()` reserves the amount, runs your payment, and records it as settled.
+
+```js
+const tx = await budget.pay('$5', async reservation => {
+  return wallet.sendTransaction(request); // reservation.id makes a good idempotency key
+}, { to: payee, note: 'weather API' });
+```
+
+If the payment throws, it still counts, because it may have left the wallet. If you know it
+didn't, say so and the amount comes back:
+
+```js
+import { notSent } from 'walletcap';
+
+throw notSent(error); // inside the payment function
+```
+
+In Python, `raise NotSent("card declined")` inside the `with` block. Set `payment.tx` in the
+block to keep the transaction hash in the history, and use `async with` in async code.
+
+`budget.check('$5')` answers `{ ok, reason, remaining }` without spending. `budget.reserve()`
+gives you a reservation to `commit()` or `release()` yourself.
+
+### x402
+
+`guard()` puts the budget in front of any x402 v2 client from `@x402/core`, so it works under
+`@x402/fetch` and alongside Coinbase's CDP spend controls.
+
+```js
+import { x402Client } from '@x402/core/client';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { wrapFetchWithPayment } from '@x402/fetch';
+
+const client = budget.guard(new x402Client().register('eip155:8453', new ExactEvmScheme(account)));
+const fetchPaid = wrapFetchWithPayment(fetch, client);
+```
+
+- Each payment is checked before it is signed, and reserved once its payload exists and every
+  other control has passed.
+- It counts as spent when the server confirms settlement. A payee that answers "payment
+  failed" still holds your signed authorization and could settle it until it expires, so the
+  payment keeps counting until then.
+- USDC on Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche and Solana is priced out of
+  the box, plus Base Sepolia, Arbitrum Sepolia and Solana devnet. Add another USD stablecoin with
+  `budget.guard(client, { assets: [{ network, asset, decimals }] })`. Anything else is refused,
+  not guessed.
+- `@x402/fetch` rewraps errors from payment creation, so a refusal reaches you as an `Error`
+  whose message starts `Failed to create payment payload:` and carries the budget's reason.
+
+### Coinbase CDP spend controls
+
+`applySpendControls` builds on an x402 client, so `budget.guard(client)` works alongside it, and
+it's the one to use:
+
+- **It counts every token.** `guard()` prices the USD stablecoins it knows and refuses
+  anything else, whatever assets the client would otherwise accept.
+- **It reserves in one transaction.** Each payment is checked and reserved inside one write
+  transaction on the budget file, so processes and replicas sharing the file can't both take
+  the last dollar.
+- **It keeps counting what the payee calls failed** until the authorization expires, then frees
+  it on its own.
+
+To keep CDP's own count durable and shared as well, swap its in-memory store for walletcap's,
+set `maxCumulativeSpend` (CDP only records through its store when a cumulative cap is set), and
+set `allowedAssets`: CDP never consults its store for a token outside the cap.
+
+```js
+applySpendControls(client, {
+  maxAmountPerPayment: { atomic: 50_000_000n, asset: USDC },
+  maxCumulativeSpend: { atomic: 150_000_000n, asset: USDC },
+  maxCumulativeSpendWindow: '24h',
+  allowedAssets: [USDC],
+  store: budget.cdpStore({ asset: USDC }),
+});
+budget.guard(client);
+```
+
+walletcap's store re-checks the budget when CDP records a payment, so it holds across replicas
+on its own. When CDP removes a payment from its store, the store can't tell why, so the payment
+stays counted as in-flight until you check the chain and run `npx walletcap release <id>`. Use
+CDP 1.56.0 or later.
+
+### Coinbase Agentic Wallet (awal CLI and MCP server)
+
+Run the Agentic Wallet's CLI and MCP server through walletcap, and every payment counts in the
+wallet's budget, whichever process, session or machine makes it:
+
+```console
+$ 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 …
+```
+
+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 `--`.
+
+```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.
+- 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 release it: the wallet signs whatever validity the payee asks for, and
+  walletcap can't see it. Check the chain, then `npx walletcap release <id>`.
+- The wallet's own refusal, 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). Separate hosts without one
+  wait for the Postgres backend.
+- It binds the payments that go through it. The wallet app takes requests from any process of
+  the same user, so keep the real `awal` out of an agent's reach.
+
+### 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:
+
+```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()] })
+```
+
+### Coinbase Spend Permissions, on chain
+
+For a limit the agent's own code can't go around, `solidity/src/AccountCapSpender.sol` is the
+spender for Spend Permissions. Deploy it with the SpendPermissionManager, the agent's
+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.
+
+## The owner's controls
+
+```console
+$ npx walletcap status
+Budget file /home/you/.local/state/walletcap/budget.sqlite
+
+0xd797…ca02: $0.15 spent of $0.15 per 24h, $0.00 left · at most $0.05 a payment
+
+$ npx walletcap set --per-day 0.20     # what was spent still counts
+$ npx walletcap freeze                 # every process, every rail, now
+$ npx walletcap unfreeze
+$ npx walletcap history
+$ npx walletcap release <id>           # an in-flight payment you know never left
+```
+
+Python ships the same commands as `walletcap`. Amounts are dollars; leave out the `$`
+sign, which your shell would expand. Add `--wallet` when the file holds more than one budget,
+and `--json` for scripts.
+
+## Where the budget lives
+
+The default file is per user: `~/.local/state/walletcap/budget.sqlite` on Linux,
+`~/Library/Application Support/walletcap/budget.sqlite` on macOS, and
+`%LOCALAPPDATA%\walletcap\budget.sqlite` on Windows. Set `WALLETCAP_PATH`, or pass `path`, to put it elsewhere. Both languages
+compute the same default.
+
+The budget is as durable as that file. In a container, put it on a volume that outlives the
+container, or a redeploy starts a new file. For agents that can touch the filesystem, open the
+budget with `create: false` and create it once, as the owner, with `npx walletcap set`:
+then a missing file refuses every payment instead of starting a new budget.
+
+## What it doesn't do
+
+- **It binds the payments that go through it.** An agent with a shell on the same machine can
+  go around it: call the wallet directly, or delete the file. To bound an agent like that, keep
+  the budget out of its reach (another OS user, another service) or enforce on chain, as
+  `AccountCapSpender` does for Spend Permissions.
+- **One file is one host, or a shared volume.** A Postgres backend for replicas on separate
+  hosts is next.
+- **It can't see a revoke that lands later in the same block,** and for x402 schemes that settle
+  later (batch vouchers), a payment counts from when the server confirms it.
+- **Some x402 payments can't be confirmed.** `@x402/fetch` doesn't report v1 settlements
+  back, and only the exact EVM scheme carries an expiry the guard can read. An unconfirmed
+  payment keeps counting until its authorization expires plus one window, or, with no expiry,
+  until you `release` it.
+- Amounts are micro-dollars and must fit in 64 bits.
+
+## This repository
+
+| Path | What it is |
+|---|---|
+| `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 |
+| `tests/` | the Python suite, including the tests that drive both languages against one budget file |
+
+```console
+$ cd js && npm install && node --test            # 50 tests
+$ uv run --with pytest pytest -q                 # 53 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
+```
+
+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,
+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.
+
+One test is **not** here: the integration test that drives Coinbase's CDP spend controls through
+the shared store. It runs against a vendored build of Coinbase's SDK and lives in ShadowPath's
+own repository. Porting it to the published `@coinbase/cdp-sdk` is open work.
+
+## Prove it holds in your deployment
+
+This package closes the gaps ShadowPath measured. Whether your configuration is closed is a
+measurement: ShadowPath runs your agent with every control switched on and certifies, in
+dollars, what can still get past your budget, signed and re-checkable offline.
+[Get a certificate for your deployment](mailto:paul@coriolislabs.ca).
+
+Apache-2.0. Copyright 2026 Coriolis Labs Inc.