walletbrake 0.1.0__tar.gz

walletbrake-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+*.zip
+.DS_Store
+.env
+.env.alerts
+.env.sepolia
+/bin/
+audit.jsonl
+contracts/broadcast/
+contracts/cache/
+contracts/lib/
+contracts/out/
+data/
+web/walletconnect/node_modules/
+sdk-ts/node_modules/
+sdk-ts/dist/
+agentkit/node_modules/
+agentkit/dist/
+mcp/node_modules/
+mcp/dist/
+sdk-py/.venv/
+sdk-py/dist/
+__pycache__/
+.pytest_cache/

walletbrake-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hd5-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

walletbrake-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: walletbrake
+Version: 0.1.0
+Summary: Pay from a WalletBrake vault from a bot or AI agent: spending limits, a trusted-address list and owner approval on Telegram, enforced on chain.
+Project-URL: Homepage, https://walletbrake.com
+Project-URL: Documentation, https://walletbrake.com/docs#python
+Author-email: WalletBrake <support@walletbrake.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-payments,ai-agent,base,ethereum,prompt-injection,spending-limits,usdc,wallet,walletbrake,web3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Requires-Dist: web3<9,>=7
+Description-Content-Type: text/markdown
+
+# walletbrake (Python)
+
+Pay from a [WalletBrake](https://walletbrake.com) vault from a bot or AI agent, in Python. It works with LangChain, CrewAI, or plain scripts.
+
+WalletBrake checks every payment against the vault's rules: limits, a trusted-address list, and asking the owner on Telegram. The vault contract enforces the result on chain. A payment needs WalletBrake's signature and the spending wallet's transaction, so neither one can move money alone. There's no API key: each request is signed with the spending wallet's key.
+
+> Test networks only for now (Base Sepolia, BNB testnet, Ethereum Sepolia). Mainnet comes after the security audit.
+
+## Install
+
+```sh
+pip install walletbrake
+```
+
+Python 3.10 or newer; web3 7 or 8.
+
+## Pay
+
+```python
+import os
+from walletbrake import WalletBrake
+
+wb = WalletBrake(
+    url="https://app.walletbrake.com/c/84532/v/0xYourVault",  # the vault's WalletBrake address
+    private_key=os.environ["AGENT_KEY"],                      # the vault's spending wallet
+    rpc_url="https://sepolia.base.org",
+)
+paid = wb.pay("0x…", "10")  # 10 USDC
+print(paid.tx_hash)
+```
+
+- `amount` is in coin units, as a string or `Decimal` (`"10.5"`). Ints and floats are refused, because `10` could mean 10 USDC or 10 base units, and floats lose cents. For base units, use `amount_base_units=10_500_000`.
+- `token` is a symbol (`"USDC"`, `"ETH"`) or a token address. The default is `"USDC"`.
+
+## When the owner has to approve
+
+On the **AI agent** plan, the vault pays only trusted addresses: the ones listed when the vault was created, or added later from the Safety tab. A payment to any other address goes to the owner on Telegram, with Approve and Reject buttons. Until they answer, `pay` raises `DeniedError` and `is_awaiting_approval(err)` returns true. Asking again with the same coin, address and amount goes through once they tap Approve. `pay_and_wait` does the asking again for you:
+
+```python
+paid = wb.pay_and_wait("0x…", "10", on_waiting=lambda _: print("Asked the owner on Telegram…"))
+```
+
+Each approval covers one payment, for 15 minutes. It doesn't make the address trusted.
+
+## Tasks
+
+Before an agent starts a job, before it reads any web page, email or file,
+tell WalletBrake what the job is. Payments in that task can't go past it,
+even to addresses you trust:
+
+```python
+task = wb.open_task(
+    "Pay the March hosting invoice",
+    "100",                            # USDC, for the whole task
+    pay_only=["0xHostingCompany…"],   # optional
+    minutes=60,                       # optional, up to 1440
+)
+wb.pay_and_wait("0xHostingCompany…", "60", task=task, note="invoice 1042")
+```
+
+A payment over what's left of the budget, to an address the task didn't
+list, or after the task ends, is refused with rule `"task"`. When the
+server's intent check is on, a payment that doesn't clearly fit the task's
+description goes to the owner on Telegram first, with the reason.
+
+## Refusals
+
+```python
+from walletbrake import DeniedError, WalletBrakeError
+
+try:
+    wb.pay(to, "5000")
+except DeniedError as err:
+    print(err.rule, err.reason)  # e.g. "per-tx-cap", why
+```
+
+`err.verdict == "freeze"` means the request looked like an attack and WalletBrake froze the vault. Only the owner can unfreeze it. Other problems raise:
+- `WalletBrakeError`: unreachable, wrong key (`status` 401)
+- `VaultError`: the vault contract refused, e.g. `NotReady`
+
+## Held payments
+
+The vault holds a large payment to an address it doesn't trust for an hour, so the owner can cancel it. In that case `pay` returns `queued=True` and a `queue_id`. Run it once the hour has passed:
+
+```python
+if paid.queued:
+    wb.execute_queued(paid.queue_id)
+```
+
+## Also
+
+- `wb.info()`: the vault's coins, balances, limits, and whether it's frozen.
+- `wb.request_approval(...)` then `wb.send(approval)`: the two halves of `pay`. Before sending, the SDK checks that WalletBrake's approval matches the payment you asked for.
+
+## Docs
+
+Quickstart, every refusal reason, the networks and addresses, and the HTTP API for other languages: **https://walletbrake.com/docs**
+
+Questions: support@walletbrake.com. Security issues: security@walletbrake.com.
+
+## License
+
+MIT

walletbrake-0.1.0/README.md

@@ -0,0 +1,103 @@
+# walletbrake (Python)
+
+Pay from a [WalletBrake](https://walletbrake.com) vault from a bot or AI agent, in Python. It works with LangChain, CrewAI, or plain scripts.
+
+WalletBrake checks every payment against the vault's rules: limits, a trusted-address list, and asking the owner on Telegram. The vault contract enforces the result on chain. A payment needs WalletBrake's signature and the spending wallet's transaction, so neither one can move money alone. There's no API key: each request is signed with the spending wallet's key.
+
+> Test networks only for now (Base Sepolia, BNB testnet, Ethereum Sepolia). Mainnet comes after the security audit.
+
+## Install
+
+```sh
+pip install walletbrake
+```
+
+Python 3.10 or newer; web3 7 or 8.
+
+## Pay
+
+```python
+import os
+from walletbrake import WalletBrake
+
+wb = WalletBrake(
+    url="https://app.walletbrake.com/c/84532/v/0xYourVault",  # the vault's WalletBrake address
+    private_key=os.environ["AGENT_KEY"],                      # the vault's spending wallet
+    rpc_url="https://sepolia.base.org",
+)
+paid = wb.pay("0x…", "10")  # 10 USDC
+print(paid.tx_hash)
+```
+
+- `amount` is in coin units, as a string or `Decimal` (`"10.5"`). Ints and floats are refused, because `10` could mean 10 USDC or 10 base units, and floats lose cents. For base units, use `amount_base_units=10_500_000`.
+- `token` is a symbol (`"USDC"`, `"ETH"`) or a token address. The default is `"USDC"`.
+
+## When the owner has to approve
+
+On the **AI agent** plan, the vault pays only trusted addresses: the ones listed when the vault was created, or added later from the Safety tab. A payment to any other address goes to the owner on Telegram, with Approve and Reject buttons. Until they answer, `pay` raises `DeniedError` and `is_awaiting_approval(err)` returns true. Asking again with the same coin, address and amount goes through once they tap Approve. `pay_and_wait` does the asking again for you:
+
+```python
+paid = wb.pay_and_wait("0x…", "10", on_waiting=lambda _: print("Asked the owner on Telegram…"))
+```
+
+Each approval covers one payment, for 15 minutes. It doesn't make the address trusted.
+
+## Tasks
+
+Before an agent starts a job, before it reads any web page, email or file,
+tell WalletBrake what the job is. Payments in that task can't go past it,
+even to addresses you trust:
+
+```python
+task = wb.open_task(
+    "Pay the March hosting invoice",
+    "100",                            # USDC, for the whole task
+    pay_only=["0xHostingCompany…"],   # optional
+    minutes=60,                       # optional, up to 1440
+)
+wb.pay_and_wait("0xHostingCompany…", "60", task=task, note="invoice 1042")
+```
+
+A payment over what's left of the budget, to an address the task didn't
+list, or after the task ends, is refused with rule `"task"`. When the
+server's intent check is on, a payment that doesn't clearly fit the task's
+description goes to the owner on Telegram first, with the reason.
+
+## Refusals
+
+```python
+from walletbrake import DeniedError, WalletBrakeError
+
+try:
+    wb.pay(to, "5000")
+except DeniedError as err:
+    print(err.rule, err.reason)  # e.g. "per-tx-cap", why
+```
+
+`err.verdict == "freeze"` means the request looked like an attack and WalletBrake froze the vault. Only the owner can unfreeze it. Other problems raise:
+- `WalletBrakeError`: unreachable, wrong key (`status` 401)
+- `VaultError`: the vault contract refused, e.g. `NotReady`
+
+## Held payments
+
+The vault holds a large payment to an address it doesn't trust for an hour, so the owner can cancel it. In that case `pay` returns `queued=True` and a `queue_id`. Run it once the hour has passed:
+
+```python
+if paid.queued:
+    wb.execute_queued(paid.queue_id)
+```
+
+## Also
+
+- `wb.info()`: the vault's coins, balances, limits, and whether it's frozen.
+- `wb.request_approval(...)` then `wb.send(approval)`: the two halves of `pay`. Before sending, the SDK checks that WalletBrake's approval matches the payment you asked for.
+
+## Docs
+
+Quickstart, every refusal reason, the networks and addresses, and the HTTP API for other languages: **https://walletbrake.com/docs**
+
+Questions: support@walletbrake.com. Security issues: security@walletbrake.com.
+
+## License
+
+MIT

walletbrake-0.1.0/examples/pay.py

@@ -0,0 +1,33 @@
+"""An AI agent's payment, with the Python SDK. Test networks only.
+
+    uv run examples/pay.py <vault> <to> <amount>
+
+Uses the spending key from `go run ./examples/agentpay keygen`
+(~/.config/walletbrake/agent.key), or AGENT_KEY. Base Sepolia by default;
+set WALLETBRAKE_URL and RPC_URL for another network.
+"""
+import os
+import pathlib
+import sys
+
+from walletbrake import DeniedError, WalletBrake
+
+if len(sys.argv) != 4:
+    sys.exit("usage: uv run examples/pay.py <vault> <to> <amount>")
+vault, to, amount = sys.argv[1:]
+key = os.environ.get("AGENT_KEY") or (pathlib.Path.home() / ".config/walletbrake/agent.key").read_text().strip()
+
+wb = WalletBrake(
+    url=os.environ.get("WALLETBRAKE_URL", f"https://app.walletbrake.com/c/84532/v/{vault}"),
+    private_key=key,
+    rpc_url=os.environ.get("RPC_URL", "https://sepolia.base.org"),
+)
+print(f"Paying {amount} USDC to {to}…", flush=True)
+try:
+    res = wb.pay_and_wait(
+        to, amount,
+        on_waiting=lambda _: print("This address isn't trusted: WalletBrake asked the owner on Telegram. Waiting for Approve…", flush=True),
+    )
+except DeniedError as err:
+    sys.exit(f"WalletBrake refused: {err.reason} ({err.rule})")
+print(f"Approved; the vault holds it (payment #{res.queue_id}). Tx {res.tx_hash}" if res.queued else f"Paid. Tx {res.tx_hash}")

walletbrake-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "walletbrake"
+version = "0.1.0"
+description = "Pay from a WalletBrake vault from a bot or AI agent: spending limits, a trusted-address list and owner approval on Telegram, enforced on chain."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "WalletBrake", email = "support@walletbrake.com" }]
+keywords = ["walletbrake", "ai-agent", "agent-payments", "wallet", "spending-limits", "prompt-injection", "web3", "ethereum", "base", "usdc"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "web3>=7,<9",
+  "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://walletbrake.com"
+Documentation = "https://walletbrake.com/docs#python"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["walletbrake"]
+
+[tool.hatch.build.targets.sdist]
+include = ["walletbrake", "tests", "examples", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

walletbrake-0.1.0/tests/conftest.py

@@ -0,0 +1,63 @@
+"""Starts cmd/testenv (anvil + a vault + the real guardian) for the tests."""
+import json
+import os
+import pathlib
+import secrets
+import subprocess
+import tempfile
+
+import pytest
+import requests
+from web3 import Web3
+
+REPO = pathlib.Path(__file__).resolve().parents[2]
+
+
+@pytest.fixture(scope="session")
+def env():
+    bin_path = pathlib.Path(tempfile.mkdtemp(prefix="wb-testenv-")) / "testenv"
+    subprocess.run(["go", "build", "-o", str(bin_path), "./cmd/testenv"], cwd=REPO, check=True, env={**os.environ, "CGO_ENABLED": "0"})
+    p = subprocess.Popen([str(bin_path)], stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True)
+    line = p.stdout.readline()
+    if not line:
+        raise RuntimeError(f"testenv exited ({p.wait()})")
+    yield json.loads(line)
+    p.stdin.close()
+    p.wait(timeout=10)
+
+
+class Tools:
+    def __init__(self, env):
+        self.env = env
+        self.w3 = Web3(Web3.HTTPProvider(env["rpc"]))
+        self.usdc = self.w3.eth.contract(
+            address=env["usdc"],
+            abi=[{"type": "function", "name": "balanceOf", "stateMutability": "view",
+                  "inputs": [{"name": "", "type": "address"}], "outputs": [{"name": "", "type": "uint256"}]}],
+        )
+
+    def balance(self, who):
+        return self.usdc.functions.balanceOf(Web3.to_checksum_address(who)).call()
+
+    def warp(self, seconds):
+        self.w3.provider.make_request("evm_increaseTime", [seconds])
+        self.w3.provider.make_request("evm_mine", [])
+
+    def tap(self, approve):
+        """Answers the oldest open Telegram question, like the owner tapping a button."""
+        r = requests.post(self.env["guardianUrl"] + "/test/answer", json={"approve": approve}, timeout=10)
+        r.raise_for_status()
+        return r.json()["reply"]
+
+    def questions(self):
+        return requests.get(self.env["guardianUrl"] + "/test/questions", timeout=10).json()
+
+
+@pytest.fixture(scope="session")
+def tools(env):
+    return Tools(env)
+
+
+@pytest.fixture
+def new_address():
+    return lambda: Web3.to_checksum_address("0x" + secrets.token_hex(20))

walletbrake-0.1.0/tests/test_sdk.py

@@ -0,0 +1,251 @@
+"""End to end against the real guardian (cmd/testenv: anvil, a vault that
+pays only trusted addresses, and a stand-in for Telegram)."""
+import threading
+
+import pytest
+from web3 import Web3
+
+from walletbrake import (
+    RULE_OWNER_REJECTED,
+    DeniedError,
+    VaultError,
+    WalletBrake,
+    WalletBrakeError,
+    Task,
+    is_awaiting_approval,
+    payment_message,
+    task_message,
+)
+
+
+def usdc(n):
+    return int(n * 1_000_000)
+
+
+@pytest.fixture(scope="session")
+def wb(env):
+    return WalletBrake(env["guardianUrl"], env["operatorKey"], env["rpc"])
+
+
+def awaiting(wb, *args, **kw):
+    with pytest.raises(DeniedError) as e:
+        wb.pay(*args, **kw)
+    assert is_awaiting_approval(e.value), e.value
+
+
+def test_reads_the_vault(wb, env):
+    info = wb.info()
+    assert info["vault"] == Web3.to_checksum_address(env["vault"])
+    assert info["chainId"] == env["chainId"]
+    assert info["trustedOnly"] is True
+    coin = next(t for t in info["tokens"] if t["symbol"] == "USDC")
+    assert coin["decimals"] == 6 and coin["address"] == Web3.to_checksum_address(env["usdc"])
+
+
+def test_pays_a_trusted_address(wb, env, tools):
+    before = tools.balance(env["trusted"])
+    res = wb.pay(env["trusted"], "100.5")
+    assert res.queued is False and res.tx_hash.startswith("0x") and len(res.tx_hash) == 66
+    assert tools.balance(env["trusted"]) - before == 100_500_000
+
+
+def test_base_units_and_token_by_address(wb, env, tools):
+    before = tools.balance(env["trusted"])
+    wb.pay(env["trusted"], token=env["usdc"], amount_base_units=7)
+    assert tools.balance(env["trusted"]) - before == 7
+
+
+def test_untrusted_waits_for_owner_then_pays(wb, tools, new_address):
+    to = new_address()
+    asked = tools.questions()["asked"]
+    awaiting(wb, to, "25")
+    assert tools.questions()["asked"] == asked + 1
+    awaiting(wb, to, "25")  # asking again while waiting doesn't ask twice
+    assert tools.questions()["asked"] == asked + 1
+
+    assert "Approved" in tools.tap(True)
+    assert wb.pay(to, "25").queued is False
+    assert tools.balance(to) == usdc(25)
+
+    awaiting(wb, to, "25")  # one payment per approval
+    tools.tap(False)
+
+
+def test_pay_and_wait_waits_for_the_tap(wb, tools, new_address):
+    to = new_address()
+    waited = []
+
+    def on_waiting(_err):
+        waited.append(1)
+        threading.Timer(0.3, tools.tap, args=(True,)).start()
+
+    res = wb.pay_and_wait(to, "30", poll=0.1, timeout=20, on_waiting=on_waiting)
+    assert waited == [1] and res.queued is False
+    assert tools.balance(to) == usdc(30)
+
+
+def test_pay_and_wait_gives_up(wb, tools, new_address):
+    with pytest.raises(WalletBrakeError, match="didn't answer"):
+        wb.pay_and_wait(new_address(), "31", poll=0.05, timeout=0.3)
+    tools.tap(False)
+
+
+def test_rejected_payment_is_refused(wb, tools, new_address):
+    to = new_address()
+    awaiting(wb, to, "40")
+    assert "Rejected" in tools.tap(False)
+    with pytest.raises(DeniedError) as e:
+        wb.pay(to, "40")
+    assert e.value.rule == RULE_OWNER_REJECTED
+    assert tools.balance(to) == 0
+
+
+def test_over_the_per_payment_limit(wb, env):
+    with pytest.raises(DeniedError) as e:
+        wb.pay(env["trusted"], "6000")
+    assert e.value.rule == "per-tx-cap" and e.value.verdict == "deny"
+
+
+def test_wrong_key_is_turned_away(env):
+    other = WalletBrake(env["guardianUrl"], env["otherKey"], env["rpc"])
+    with pytest.raises(WalletBrakeError) as e:
+        other.pay(env["trusted"], "1")
+    assert e.value.status == 401 and not isinstance(e.value, DeniedError)
+
+
+def test_never_sends_a_different_payment(env, tools, new_address):
+    import requests
+
+    thief = new_address()
+
+    class Lying(requests.Session):
+        def request(self, method, url, **kw):
+            r = super().request(method, url, **kw)
+            if url.endswith("/v1/approve") and r.ok:
+                body = r.json()
+                body["to"] = thief
+                r._content = __import__("json").dumps(body).encode()
+            return r
+
+    tricked = WalletBrake(env["guardianUrl"], env["operatorKey"], env["rpc"], session=Lying())
+    before = tools.balance(env["trusted"])
+    with pytest.raises(WalletBrakeError, match="doesn't match"):
+        tricked.pay(env["trusted"], "5")
+    assert tools.balance(thief) == 0 and tools.balance(env["trusted"]) == before
+
+
+@pytest.mark.parametrize(
+    "kw, err, match",
+    [
+        ({"amount": "abc"}, ValueError, "not a number"),
+        ({"amount": "0"}, ValueError, "more than 0"),
+        ({"amount": "1.0000001"}, ValueError, "only 6 decimals"),
+        ({"amount": 10}, TypeError, "string or Decimal"),
+        ({"amount": 1.5}, TypeError, "string or Decimal"),
+        ({"amount": "1", "token": "DOGE"}, ValueError, "isn't a coin this vault pays"),
+        ({}, ValueError, "give amount"),
+        ({"amount": "1", "amount_base_units": 1}, ValueError, "not both"),
+    ],
+)
+def test_bad_input(wb, env, kw, err, match):
+    with pytest.raises(err, match=match):
+        wb.pay(env["trusted"], **kw)
+
+
+def test_bad_address(wb):
+    with pytest.raises(ValueError, match="not an address"):
+        wb.pay("0x1234", "1")
+
+
+def test_unreachable(env):
+    down = WalletBrake("http://127.0.0.1:1", env["operatorKey"], env["rpc"])
+    with pytest.raises(WalletBrakeError, match="unreachable"):
+        down.pay(env["trusted"], "1")
+
+
+def test_payment_message_format():
+    assert payment_message(
+        vault="0xcf7ed3acca5a467e9e704c703e8d87f634fb0fc9",
+        chain_id=84532,
+        token="0x5fbdb2315678afecb367f032d93f642f64180aa3",
+        to="0x000000000000000000000000000000000000beef",
+        amount=10_000_000,
+        time=1700000000,
+        id="00112233445566778899aabbccddeeff",
+    ) == (
+        "WalletBrake payment request\n\nVault: 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9\nChain ID: 84532\n"
+        "Token: 0x5FbDB2315678afecb367f032d93F642f64180aa3\nTo: 0x000000000000000000000000000000000000bEEF\n"
+        "Amount: 10000000\nTime: 1700000000\nRequest ID: 00112233445566778899aabbccddeeff"
+    )
+
+
+def test_task_caps_payments_even_to_trusted(wb, env, tools):
+    task = wb.open_task("Pay the March hosting invoice", "100", pay_only=[env["trusted"].lower()])
+    assert isinstance(task, Task) and task.id.startswith("t_") and task.budget == usdc(100)
+    before = tools.balance(env["trusted"])
+    wb.pay(env["trusted"], "60", task=task, note="hosting invoice 1042")
+    with pytest.raises(DeniedError) as e:
+        wb.pay(env["trusted"], "50", task=task.id)
+    assert e.value.rule == "task" and "budget" in e.value.reason
+    assert tools.balance(env["trusted"]) - before == usdc(60)
+
+
+def test_payment_that_does_not_fit_its_task_asks_the_owner(wb, env, tools):
+    task = wb.open_task("Pay the March hosting invoice", "100")
+    asked = tools.questions()["asked"]
+    awaiting(wb, env["trusted"], "20", task=task, note="refund to customer")
+    q = tools.questions()
+    assert q["asked"] == asked + 1
+    assert q["last"] == {"task": "Pay the March hosting invoice", "note": "refund to customer", "concern": "a refund isn't part of this task", "trusted": True}
+    tools.tap(True)
+    before = tools.balance(env["trusted"])
+    wb.pay(env["trusted"], "20", task=task, note="refund to customer")
+    assert tools.balance(env["trusted"]) - before == usdc(20)
+
+
+def test_bad_task_input(wb):
+    with pytest.raises(ValueError, match="more than 0"):
+        wb.open_task("x", "0")
+    with pytest.raises(ValueError, match="not an address"):
+        wb.open_task("x", "5", pay_only=["0x12"])
+    with pytest.raises(WalletBrakeError) as e:
+        wb.open_task("two\nlines", "5")
+    assert e.value.status == 400
+
+
+def test_task_message_format():
+    vault, token = "0xcf7ed3acca5a467e9e704c703e8d87f634fb0fc9", "0x5fbdb2315678afecb367f032d93f642f64180aa3"
+    assert task_message(
+        vault=vault, chain_id=84532, description="Buy API credits", token=token, budget=50_000_000,
+        pay_only=["0x000000000000000000000000000000000000beef"], minutes=60, time=1700000000, id="ab" * 16,
+    ) == (
+        "WalletBrake task\n\nVault: 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9\nChain ID: 84532\nTask: Buy API credits\n"
+        "Token: 0x5FbDB2315678afecb367f032d93F642f64180aa3\nBudget: 50000000\nPay only: 0x000000000000000000000000000000000000bEEF\n"
+        "Open for: 60 minutes\nTime: 1700000000\nRequest ID: " + "ab" * 16
+    )
+    pay = payment_message(vault=vault, chain_id=84532, token=token, to=token, amount=1, time=1, id="x", task="t_1", note="credits")
+    assert pay.endswith("\nRequest ID: x\nTask: t_1\nNote: credits")
+
+
+def test_zz_held_payment_runs_after_the_delay(wb, env, tools, new_address):
+    """Last (zz): it moves the chain clock forward."""
+    to = new_address()
+    awaiting(wb, to, "2000")
+    tools.tap(True)
+    res = wb.pay(to, "2000")
+    assert res.queued is True and isinstance(res.queue_id, int)
+    assert tools.balance(to) == 0
+
+    with pytest.raises(VaultError) as e:
+        wb.execute_queued(res.queue_id)
+    assert e.value.name == "NotReady"
+    tools.warp(env["recipientDelay"] + 1)
+    wb.execute_queued(res.queue_id)
+    assert tools.balance(to) == usdc(2000)
+
+
+def test_lowercase_vault_url_is_checksummed():
+    key = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d"
+    wb = WalletBrake("https://app.walletbrake.com/c/84532/v/0x976f718682c69bd2eb54f11370bc1d32df18318a/", key, "http://127.0.0.1:1")
+    assert wb.url == "https://app.walletbrake.com/c/84532/v/0x976F718682c69bD2eb54F11370BC1d32df18318a"
+    assert WalletBrake("http://127.0.0.1:8080", key, "http://127.0.0.1:1").url == "http://127.0.0.1:8080"