x402-guard 0.1.0__tar.gz

x402_guard-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+node_modules/
+dist/
+*.egg-info/
+# guard runtime state (buyer-local data, never commit)
+*.db
+*-audit.jsonl

x402_guard-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: x402-guard
+Version: 0.1.0
+Summary: Payment-path seatbelt for x402 buyer agents: Settled pre-flight, endpoint drift checks (StallRow Recheck), RouteVerdict trust gates, and spend caps enforced before any payment is signed.
+Project-URL: Homepage, https://github.com/QuincyGB/x402-guard
+Project-URL: Repository, https://github.com/QuincyGB/x402-guard
+Project-URL: Issues, https://github.com/QuincyGB/x402-guard/issues
+Author: Quincy Goertz-Brown
+License: MIT
+Keywords: agents,base,guard,middleware,payments,usdc,verdict-row,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.13
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# x402-guard (Python)
+
+The payment-path seatbelt for x402 buyer agents. Install
+`GuardedClient` once inside your paying code; from then on, every
+x402 payment you make is pre-flighted through Verdict Row **before
+anything is signed**:
+
+1. **Settled pre-flight (free)** — settled.tools' scout has actually
+   bought from most endpoints worth paying. The guard asks what its
+   test purchases found. Hard veto *only* on a failed delivery or a
+   not-payable verdict; a verified delivery corroborates;
+   `nothing_to_compare` is noted, never a veto; Settled being down or
+   silent is a pass-through, never a block.
+2. **Drift check (StallRow Recheck, $0.005, cached)** — if the
+   endpoint is new to you, or your last look is older than the TTL
+   (default 24h), the guard pays Recheck to fingerprint the
+   endpoint's live payment terms and diffs them against its local
+   store. `payTo` or asset changed → **hard block**. Price moved
+   more than the configured % (default 20%) → block. Schema /
+   description / other changes → warn. Inside the TTL the cached
+   result is used and this stage costs **zero**.
+3. **RouteVerdict gate (optional, $0.05, cached)** — a first-ever
+   payment at or above a threshold (default $0.10) requires a
+   TRUSTED verdict ≥ your trust floor (default 80).
+4. **Your spend caps** — per-payment, per-endpoint-daily, and
+   global-daily caps from your own config, checked against the
+   guard's local ledger *before* signing. The guard refuses first;
+   it never signs and discovers later.
+
+Every decision — allow, warn, block, with the reason chain and what
+the checks cost — is appended to a local audit log (JSONL) you can
+read. Blocks raise `GuardBlocked` carrying the full decision.
+
+```python
+from eth_account import Account
+from x402_guard import GuardConfig, GuardedClient
+
+account = Account.from_key("0x...")  # your key, your env — never logged
+guard = GuardedClient(account=account, config=GuardConfig(
+    global_daily_cap_units=1_000_000,  # $1.00/day across everything
+))
+
+result = guard.pay("https://some-service.example/v1/thing", {"input": 1})
+print(result.outcome.response)          # the service's real answer
+print(result.decision.summary())        # what was consulted, what it cost
+```
+
+No signer (`account=None`) = dry-run: the pipeline runs what it can
+for free, paid stages are noted as skipped, would-be blocks land on
+`result.decision.blocked`, and nothing is ever paid.
+
+## What it costs you
+
+| Stage | Cost | When |
+|---|---|---|
+| Settled pre-flight | free | every payment |
+| Recheck drift check | $0.005 | first look per endpoint per TTL (24h default) |
+| RouteVerdict gate | $0.05 | first big payment (≥ $0.10 default) per TTL |
+| The guard itself | $0 | it's a library |
+
+## What it cannot do
+
+It judges **pre-payment signals only**: the inspector's delivery
+record, the endpoint's current terms vs. its own history, a trust
+verdict, and your caps. It cannot judge the paid payload — whether
+the answer you bought was *good* is your application's problem. It
+also cannot help if an endpoint's terms change between the drift
+check and your payment inside the same TTL window; shorten the TTL
+if that window matters to you.
+
+## Configuration
+
+`GuardConfig` in code, or environment variables via
+`GuardConfig.from_env()` (`X402_GUARD_*`: stage toggles, URLs, TTL,
+price-change %, failure policies — `"warn"` or `"block"` when a check
+service itself errors — USD caps, store/audit paths). Local state
+lives in `~/.x402-guard/` (sqlite cache + spend ledger, JSONL audit
+log) — your machine, your data, never transmitted.
+
+An external budget object (anything with `authorize(units)` /
+`record(units, label=)` — e.g. verdict-loop's `DailySpendCap`) can be
+passed as `budget=`; every settled payment the guard makes, checks
+included, is authorized and recorded against it, so an embedding app
+keeps exactly one cap.
+
+Part of Verdict Row: [Token Verdict](https://github.com/QuincyGB/token-verdict) ·
+[RouteVerdict](https://github.com/QuincyGB/route-verdict) ·
+[ListSmith](https://github.com/QuincyGB/list-smith) ·
+[StallRow](https://github.com/QuincyGB/stall-row) ·
+[listsmith-ci](https://github.com/QuincyGB/listsmith-ci) (the seller-side shovel)

x402_guard-0.1.0/README.md

@@ -0,0 +1,90 @@
+# x402-guard (Python)
+
+The payment-path seatbelt for x402 buyer agents. Install
+`GuardedClient` once inside your paying code; from then on, every
+x402 payment you make is pre-flighted through Verdict Row **before
+anything is signed**:
+
+1. **Settled pre-flight (free)** — settled.tools' scout has actually
+   bought from most endpoints worth paying. The guard asks what its
+   test purchases found. Hard veto *only* on a failed delivery or a
+   not-payable verdict; a verified delivery corroborates;
+   `nothing_to_compare` is noted, never a veto; Settled being down or
+   silent is a pass-through, never a block.
+2. **Drift check (StallRow Recheck, $0.005, cached)** — if the
+   endpoint is new to you, or your last look is older than the TTL
+   (default 24h), the guard pays Recheck to fingerprint the
+   endpoint's live payment terms and diffs them against its local
+   store. `payTo` or asset changed → **hard block**. Price moved
+   more than the configured % (default 20%) → block. Schema /
+   description / other changes → warn. Inside the TTL the cached
+   result is used and this stage costs **zero**.
+3. **RouteVerdict gate (optional, $0.05, cached)** — a first-ever
+   payment at or above a threshold (default $0.10) requires a
+   TRUSTED verdict ≥ your trust floor (default 80).
+4. **Your spend caps** — per-payment, per-endpoint-daily, and
+   global-daily caps from your own config, checked against the
+   guard's local ledger *before* signing. The guard refuses first;
+   it never signs and discovers later.
+
+Every decision — allow, warn, block, with the reason chain and what
+the checks cost — is appended to a local audit log (JSONL) you can
+read. Blocks raise `GuardBlocked` carrying the full decision.
+
+```python
+from eth_account import Account
+from x402_guard import GuardConfig, GuardedClient
+
+account = Account.from_key("0x...")  # your key, your env — never logged
+guard = GuardedClient(account=account, config=GuardConfig(
+    global_daily_cap_units=1_000_000,  # $1.00/day across everything
+))
+
+result = guard.pay("https://some-service.example/v1/thing", {"input": 1})
+print(result.outcome.response)          # the service's real answer
+print(result.decision.summary())        # what was consulted, what it cost
+```
+
+No signer (`account=None`) = dry-run: the pipeline runs what it can
+for free, paid stages are noted as skipped, would-be blocks land on
+`result.decision.blocked`, and nothing is ever paid.
+
+## What it costs you
+
+| Stage | Cost | When |
+|---|---|---|
+| Settled pre-flight | free | every payment |
+| Recheck drift check | $0.005 | first look per endpoint per TTL (24h default) |
+| RouteVerdict gate | $0.05 | first big payment (≥ $0.10 default) per TTL |
+| The guard itself | $0 | it's a library |
+
+## What it cannot do
+
+It judges **pre-payment signals only**: the inspector's delivery
+record, the endpoint's current terms vs. its own history, a trust
+verdict, and your caps. It cannot judge the paid payload — whether
+the answer you bought was *good* is your application's problem. It
+also cannot help if an endpoint's terms change between the drift
+check and your payment inside the same TTL window; shorten the TTL
+if that window matters to you.
+
+## Configuration
+
+`GuardConfig` in code, or environment variables via
+`GuardConfig.from_env()` (`X402_GUARD_*`: stage toggles, URLs, TTL,
+price-change %, failure policies — `"warn"` or `"block"` when a check
+service itself errors — USD caps, store/audit paths). Local state
+lives in `~/.x402-guard/` (sqlite cache + spend ledger, JSONL audit
+log) — your machine, your data, never transmitted.
+
+An external budget object (anything with `authorize(units)` /
+`record(units, label=)` — e.g. verdict-loop's `DailySpendCap`) can be
+passed as `budget=`; every settled payment the guard makes, checks
+included, is authorized and recorded against it, so an embedding app
+keeps exactly one cap.
+
+Part of Verdict Row: [Token Verdict](https://github.com/QuincyGB/token-verdict) ·
+[RouteVerdict](https://github.com/QuincyGB/route-verdict) ·
+[ListSmith](https://github.com/QuincyGB/list-smith) ·
+[StallRow](https://github.com/QuincyGB/stall-row) ·
+[listsmith-ci](https://github.com/QuincyGB/listsmith-ci) (the seller-side shovel)

x402_guard-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "x402-guard"
+version = "0.1.0"
+description = "Payment-path seatbelt for x402 buyer agents: Settled pre-flight, endpoint drift checks (StallRow Recheck), RouteVerdict trust gates, and spend caps enforced before any payment is signed."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Quincy Goertz-Brown" },
+]
+keywords = ["x402", "agents", "payments", "usdc", "base", "guard", "middleware", "verdict-row"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27",
+    "eth-account>=0.13",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/QuincyGB/x402-guard"
+Repository = "https://github.com/QuincyGB/x402-guard"
+Issues = "https://github.com/QuincyGB/x402-guard/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/x402_guard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

x402_guard-0.1.0/src/x402_guard/__init__.py

@@ -0,0 +1,49 @@
+"""x402-guard — the payment-path seatbelt for x402 buyer agents.
+
+Install GuardedClient once inside your paying code; from then on
+every x402 payment is pre-flighted before anything is signed:
+
+  1. Settled pre-flight (free)   — the inspector's delivery record
+  2. Drift check (Recheck $0.005, cached daily)
+                                 — the endpoint's terms haven't moved
+  3. RouteVerdict gate ($0.05)   — big first payments need TRUSTED
+  4. Your own spend caps         — enforced before signing, never after
+
+Blocks raise GuardBlocked with the full reason chain; every decision
+lands in a local audit log you can read.
+"""
+
+from .client import GuardDecision, GuardResult, GuardedClient, StageResult
+from .config import GuardConfig
+from .errors import GuardBlocked
+from .settled import SettledReport, fetch_settled_report
+from .store import GuardStore
+from .x402client import (
+    CallOutcome,
+    ServiceError,
+    SpendCapExceeded,
+    call_paid_endpoint,
+    format_usd,
+    load_account_from_env,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GuardedClient",
+    "GuardConfig",
+    "GuardDecision",
+    "GuardResult",
+    "StageResult",
+    "GuardBlocked",
+    "GuardStore",
+    "SettledReport",
+    "fetch_settled_report",
+    "CallOutcome",
+    "ServiceError",
+    "SpendCapExceeded",
+    "call_paid_endpoint",
+    "format_usd",
+    "load_account_from_env",
+    "__version__",
+]

x402_guard-0.1.0/src/x402_guard/audit.py

@@ -0,0 +1,27 @@
+"""The audit log: one JSON object per guard decision, append-only.
+
+Every payment the guard allows, warns on, or blocks leaves a record
+the buyer can read: what was about to be paid, which stages ran, what
+each one found, what the checks themselves cost, and the final
+decision with its reasons. If the guard ever stops a payment you
+needed, this file is where it explains itself.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+
+class AuditLog:
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def write(self, entry: dict) -> None:
+        line = json.dumps(entry, sort_keys=True)
+        with self._lock:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(line + "\n")