keptvow 0.1.0__tar.gz

keptvow-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: keptvow
+Version: 0.1.0
+Summary: Check who your AI agent is about to pay before an x402 payment goes out: ok, careful or stop.
+Author-email: Keptvow <support@keptvow.com>
+License-Expression: MIT
+Project-URL: Homepage, https://keptvow.com
+Project-URL: Documentation, https://keptvow.com/docs
+Keywords: x402,ai-agents,payments,trust,erc-8004,base,usdc
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# keptvow
+
+Check who your AI agent is about to pay **before** an x402 payment goes out.
+
+Every answer is one word — **ok**, **careful** or **stop** — with the reason, built from real
+USDC payments on Base (how many different buyers paid the seller, how many came back), reports
+from buyers who did or didn't get what they paid for, and daily checks that the seller's
+services answer. Free, no sign-up, no key, no dependencies.
+
+```sh
+pip install keptvow
+```
+
+## Ask about one wallet
+
+```python
+import keptvow
+
+result = keptvow.check("0xSELLER", amount_usd=5)
+result["verdict"]   # "ok", "careful" or "stop"
+result["advice"]    # one plain sentence saying why
+```
+
+## Check a seller's 402 answer before paying
+
+Works with `requests` and `httpx` responses:
+
+```python
+r = session.get(url)
+if r.status_code == 402:
+    keptvow.guard(r)   # raises keptvow.KeptvowStop for a wallet with a bad record
+    # ...go on and pay with your x402 client
+```
+
+`guard(r, allow_careful=False)` also blocks wallets with no track record;
+`fail_open=False` blocks payment when Keptvow can't be reached.
+
+## Report whether you got what you paid for
+
+```python
+keptvow.report_outcome(paid_response)          # reads the PAYMENT-RESPONSE receipt
+keptvow.report_outcome("0xTX", delivered=False) # or name the payment yourself
+```
+
+Sent in the background and never raises. Keptvow checks the payment on-chain, so only real
+buyers count — this is what lets honest sellers earn **ok** and flags the ones that take the
+money and deliver nothing.
+
+Set `KEPTVOW_URL` to use another Keptvow address.
+
+## Other ways in
+
+No package needed: `GET https://keptvow.com/v1/check?pay_to=0x…&amount_usd=5`, an MCP server at
+`https://keptvow.com/mcp`, and a guide for AI agents at <https://keptvow.com/llms.txt>. Everything
+else: <https://keptvow.com/docs>.

keptvow-0.1.0/README.md

@@ -0,0 +1,55 @@
+# keptvow
+
+Check who your AI agent is about to pay **before** an x402 payment goes out.
+
+Every answer is one word — **ok**, **careful** or **stop** — with the reason, built from real
+USDC payments on Base (how many different buyers paid the seller, how many came back), reports
+from buyers who did or didn't get what they paid for, and daily checks that the seller's
+services answer. Free, no sign-up, no key, no dependencies.
+
+```sh
+pip install keptvow
+```
+
+## Ask about one wallet
+
+```python
+import keptvow
+
+result = keptvow.check("0xSELLER", amount_usd=5)
+result["verdict"]   # "ok", "careful" or "stop"
+result["advice"]    # one plain sentence saying why
+```
+
+## Check a seller's 402 answer before paying
+
+Works with `requests` and `httpx` responses:
+
+```python
+r = session.get(url)
+if r.status_code == 402:
+    keptvow.guard(r)   # raises keptvow.KeptvowStop for a wallet with a bad record
+    # ...go on and pay with your x402 client
+```
+
+`guard(r, allow_careful=False)` also blocks wallets with no track record;
+`fail_open=False` blocks payment when Keptvow can't be reached.
+
+## Report whether you got what you paid for
+
+```python
+keptvow.report_outcome(paid_response)          # reads the PAYMENT-RESPONSE receipt
+keptvow.report_outcome("0xTX", delivered=False) # or name the payment yourself
+```
+
+Sent in the background and never raises. Keptvow checks the payment on-chain, so only real
+buyers count — this is what lets honest sellers earn **ok** and flags the ones that take the
+money and deliver nothing.
+
+Set `KEPTVOW_URL` to use another Keptvow address.
+
+## Other ways in
+
+No package needed: `GET https://keptvow.com/v1/check?pay_to=0x…&amount_usd=5`, an MCP server at
+`https://keptvow.com/mcp`, and a guide for AI agents at <https://keptvow.com/llms.txt>. Everything
+else: <https://keptvow.com/docs>.

keptvow-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keptvow"
+version = "0.1.0"
+description = "Check who your AI agent is about to pay before an x402 payment goes out: ok, careful or stop."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Keptvow", email = "support@keptvow.com" }]
+dependencies = []
+keywords = ["x402", "ai-agents", "payments", "trust", "erc-8004", "base", "usdc"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://keptvow.com"
+Documentation = "https://keptvow.com/docs"

keptvow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

keptvow-0.1.0/src/keptvow/__init__.py

@@ -0,0 +1,248 @@
+"""Check who your AI agent is about to pay before an x402 payment goes out.
+
+    import keptvow
+
+    result = keptvow.check("0xSELLER", amount_usd=5)
+    result["verdict"]   # "ok", "careful" or "stop"
+    result["advice"]    # one plain sentence saying why
+
+With requests or httpx, check a seller's 402 answer before paying it, and report afterwards
+whether the result arrived:
+
+    r = session.get(url)
+    if r.status_code == 402:
+        keptvow.guard(r)          # raises keptvow.KeptvowStop for a wallet with a bad record
+    ...
+    keptvow.report_outcome(paid_response)   # in the background; never raises
+
+Every answer is signed by Keptvow (result["signed"], checkable at
+https://keptvow.com/.well-known/keptvow-signer.json) and says how long it stays fresh, so checking
+the same seller again within five minutes reuses the answer. With a key, the same seller is billed
+at most once a day, and delivery reports sent with that key make its checks free.
+
+Free, no sign-up, no key. No dependencies. Set KEPTVOW_URL to use another Keptvow address.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Iterable, Optional
+
+__all__ = ["check", "guard", "report_outcome", "payment_options", "KeptvowStop", "DEFAULT_URL"]
+__version__ = "0.1.0"
+
+DEFAULT_URL = "https://keptvow.com"
+
+# USDC (6 decimals) on Base, Base Sepolia and Ethereum, so prices can be judged in dollars.
+_USDC = {
+    "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+    "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
+}
+
+
+class KeptvowStop(Exception):
+    """Raised instead of paying a wallet Keptvow says to stop at. `.check` holds the full answer."""
+
+    def __init__(self, check: dict):
+        super().__init__(f"Keptvow: not paying {check.get('pay_to')}: {check.get('advice')}")
+        self.check = check
+
+
+def _base(base_url: Optional[str]) -> str:
+    return (base_url or os.environ.get("KEPTVOW_URL") or DEFAULT_URL).rstrip("/")
+
+
+def _request(method: str, url: str, body: Optional[dict], headers: dict, timeout: float) -> tuple[int, dict]:
+    data = json.dumps(body).encode() if body is not None else None
+    if data is not None:
+        headers = {**headers, "Content-Type": "application/json"}
+    req = urllib.request.Request(url, data=data, method=method, headers={"Accept": "application/json", **headers})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return r.status, json.loads(r.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read() or b"{}")
+        except ValueError:
+            return e.code, {}
+
+
+# Answers still fresh, by base, wallet and amount: reused until their signed "Valid until".
+_fresh: dict = {}
+_fresh_lock = threading.Lock()
+_CACHE_MAX = 1000
+
+
+def check(
+    pay_to: str,
+    amount_usd: Optional[float] = None,
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    cache: bool = True,
+    timeout: float = 5.0,
+) -> dict:
+    """Asks Keptvow about one wallet before paying it.
+
+    Returns {"verdict": "ok" | "careful" | "stop", "advice": ..., "evidence": ..., "signed": ...}.
+    A fresh answer for the same wallet and amount is reused unless cache=False.
+    Raises RuntimeError when Keptvow refuses the question (e.g. not a wallet address).
+    """
+    base = _base(base_url)
+    key = (base, pay_to.strip().lower(), amount_usd)
+    if cache:
+        with _fresh_lock:
+            hit = _fresh.get(key)
+        if hit and hit[0] > time.time() * 1000:
+            return hit[1]
+    q = {"pay_to": pay_to}
+    if amount_usd is not None:
+        q["amount_usd"] = str(amount_usd)
+    headers = {"X-Api-Key": api_key} if api_key else {}
+    status, j = _request("GET", f"{base}/v1/check?{urllib.parse.urlencode(q)}", None, headers, timeout)
+    if status >= 400:
+        raise RuntimeError(j.get("error") or f"Keptvow answered {status}")
+    until = (j.get("signed") or {}).get("valid_until_ms") if isinstance(j, dict) else None
+    if cache and isinstance(until, (int, float)) and until > time.time() * 1000:
+        with _fresh_lock:
+            if len(_fresh) >= _CACHE_MAX:
+                _fresh.pop(next(iter(_fresh)))
+            _fresh[key] = (until, j)
+    return j
+
+
+def _header(response: Any, name: str) -> Optional[str]:
+    headers = getattr(response, "headers", None) or {}
+    try:
+        return headers.get(name) or headers.get(name.lower()) or headers.get(name.upper())
+    except AttributeError:
+        return None
+
+
+def payment_options(response: Any) -> list[dict]:
+    """The payment options a 402 answer offers, from its JSON body or PAYMENT-REQUIRED header."""
+    try:
+        body = response.json()
+        if isinstance(body, dict) and isinstance(body.get("accepts"), list):
+            return [a for a in body["accepts"] if isinstance(a, dict)]
+    except Exception:
+        pass
+    header = _header(response, "payment-required")
+    if header:
+        try:
+            j = json.loads(base64.b64decode(header))
+            if isinstance(j.get("accepts"), list):
+                return [a for a in j["accepts"] if isinstance(a, dict)]
+        except Exception:
+            pass
+    return []
+
+
+def guard(
+    response: Any,
+    *,
+    allow_careful: bool = True,
+    fail_open: bool = True,
+    on_check: Optional[Callable[[dict], None]] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    cache: bool = True,
+    timeout: float = 5.0,
+) -> list[dict]:
+    """Checks every wallet a 402 Payment Required answer asks to be paid at.
+
+    Works with requests and httpx responses (anything with .json() and .headers). Raises
+    KeptvowStop for a wallet with a bad record — or, with allow_careful=False, one with no track
+    record. If Keptvow can't be reached, payment goes ahead unless fail_open=False.
+    Returns the check results.
+    """
+    results = []
+    for option in payment_options(response):
+        pay_to = option.get("payTo")
+        if not isinstance(pay_to, str):
+            continue
+        units = option.get("maxAmountRequired", option.get("amount"))
+        amount = None
+        if units is not None and str(option.get("asset", "")).lower() in _USDC:
+            try:
+                amount = float(units) / 1e6
+            except (TypeError, ValueError):
+                amount = None
+        try:
+            result = check(pay_to, amount, api_key=api_key, base_url=base_url, cache=cache, timeout=timeout)
+        except Exception:
+            if fail_open:
+                continue
+            raise
+        if on_check:
+            on_check(result)
+        results.append(result)
+        if result.get("verdict") == "stop" or (not allow_careful and result.get("verdict") == "careful"):
+            raise KeptvowStop(result)
+    return results
+
+
+def report_outcome(
+    response_or_tx: Any,
+    *,
+    delivered: Optional[bool] = None,
+    pay_to: Optional[str] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    background: bool = True,
+    timeout: float = 5.0,
+) -> bool:
+    """Tells Keptvow whether a paid request delivered.
+
+    Pass the paid response (its PAYMENT-RESPONSE receipt names the transaction, and its status
+    says whether it delivered), or a transaction hash with delivered=True/False. Keptvow checks
+    the payment on-chain, so only real buyers count. With api_key, that seller's checks on the
+    key come back free. Never raises; returns False when there was nothing to report.
+    """
+    body: dict = {}
+    if isinstance(response_or_tx, str):
+        body["tx"] = response_or_tx
+    else:
+        header = _header(response_or_tx, "payment-response") or _header(response_or_tx, "x-payment-response")
+        if not header:
+            return False
+        try:
+            receipt = json.loads(base64.b64decode(header))
+        except Exception:
+            return False
+        if receipt.get("success") is False:
+            return False
+        tx = receipt.get("transaction") or receipt.get("txHash")
+        if not tx:
+            return False
+        body["tx"] = tx
+        status = getattr(response_or_tx, "status_code", None) or getattr(response_or_tx, "status", None)
+        if isinstance(status, int):
+            body["status"] = status
+    if delivered is not None:
+        body["delivered"] = delivered
+    elif "status" not in body:
+        return False
+    if pay_to:
+        body["pay_to"] = pay_to
+    url = f"{_base(base_url)}/v1/outcomes"
+
+    def send() -> None:
+        try:
+            _request("POST", url, body, {"X-Api-Key": api_key} if api_key else {}, timeout)
+        except Exception:
+            pass
+
+    if background:
+        threading.Thread(target=send, daemon=True).start()
+    else:
+        send()
+    return True

keptvow-0.1.0/src/keptvow.egg-info/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: keptvow
+Version: 0.1.0
+Summary: Check who your AI agent is about to pay before an x402 payment goes out: ok, careful or stop.
+Author-email: Keptvow <support@keptvow.com>
+License-Expression: MIT
+Project-URL: Homepage, https://keptvow.com
+Project-URL: Documentation, https://keptvow.com/docs
+Keywords: x402,ai-agents,payments,trust,erc-8004,base,usdc
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# keptvow
+
+Check who your AI agent is about to pay **before** an x402 payment goes out.
+
+Every answer is one word — **ok**, **careful** or **stop** — with the reason, built from real
+USDC payments on Base (how many different buyers paid the seller, how many came back), reports
+from buyers who did or didn't get what they paid for, and daily checks that the seller's
+services answer. Free, no sign-up, no key, no dependencies.
+
+```sh
+pip install keptvow
+```
+
+## Ask about one wallet
+
+```python
+import keptvow
+
+result = keptvow.check("0xSELLER", amount_usd=5)
+result["verdict"]   # "ok", "careful" or "stop"
+result["advice"]    # one plain sentence saying why
+```
+
+## Check a seller's 402 answer before paying
+
+Works with `requests` and `httpx` responses:
+
+```python
+r = session.get(url)
+if r.status_code == 402:
+    keptvow.guard(r)   # raises keptvow.KeptvowStop for a wallet with a bad record
+    # ...go on and pay with your x402 client
+```
+
+`guard(r, allow_careful=False)` also blocks wallets with no track record;
+`fail_open=False` blocks payment when Keptvow can't be reached.
+
+## Report whether you got what you paid for
+
+```python
+keptvow.report_outcome(paid_response)          # reads the PAYMENT-RESPONSE receipt
+keptvow.report_outcome("0xTX", delivered=False) # or name the payment yourself
+```
+
+Sent in the background and never raises. Keptvow checks the payment on-chain, so only real
+buyers count — this is what lets honest sellers earn **ok** and flags the ones that take the
+money and deliver nothing.
+
+Set `KEPTVOW_URL` to use another Keptvow address.
+
+## Other ways in
+
+No package needed: `GET https://keptvow.com/v1/check?pay_to=0x…&amount_usd=5`, an MCP server at
+`https://keptvow.com/mcp`, and a guide for AI agents at <https://keptvow.com/llms.txt>. Everything
+else: <https://keptvow.com/docs>.

keptvow-0.1.0/src/keptvow.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+src/keptvow/__init__.py
+src/keptvow.egg-info/PKG-INFO
+src/keptvow.egg-info/SOURCES.txt
+src/keptvow.egg-info/dependency_links.txt
+src/keptvow.egg-info/top_level.txt
+tests/test_keptvow.py

keptvow-0.1.0/src/keptvow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

keptvow-0.1.0/src/keptvow.egg-info/top_level.txt

@@ -0,0 +1 @@
+keptvow

keptvow-0.1.0/tests/test_keptvow.py

@@ -0,0 +1,107 @@
+"""Runs without a network: Keptvow's answers are faked. Set KEPTVOW_TEST_URL to also ask a
+running Keptvow server for real."""
+
+import base64
+import json
+import os
+import time
+import unittest
+
+import keptvow
+
+SCAM = "0x" + "c3" * 20
+GOOD = "0x" + "a1" * 20
+SIGNED = "0x" + "5e" * 20
+USDC = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
+
+
+class FakeResponse:
+    def __init__(self, status, body=None, headers=None):
+        self.status_code = status
+        self._body = body
+        self.headers = headers or {}
+
+    def json(self):
+        if self._body is None:
+            raise ValueError("no body")
+        return self._body
+
+
+class Test(unittest.TestCase):
+    def setUp(self):
+        self.calls = []
+        self.report_headers = []
+        keptvow._fresh.clear()
+        self.real = keptvow._request
+
+        def fake(method, url, body, headers, timeout):
+            self.calls.append((method, url, body))
+            if "/v1/check" in url:
+                q = dict(p.split("=", 1) for p in url.split("?", 1)[1].split("&"))
+                if q["pay_to"] == "down":
+                    raise OSError("offline")
+                signed = {"valid_until_ms": (time.time() + 60) * 1000} if q["pay_to"] == SIGNED else None
+                return 200, {"pay_to": q["pay_to"], "verdict": "stop" if q["pay_to"] == SCAM else "ok", "advice": "test", "signed": signed}
+            self.report_headers.append(headers)
+            return 202, {"status": "queued"}
+
+        keptvow._request = fake
+
+    def tearDown(self):
+        keptvow._request = self.real
+
+    def test_check_asks_about_one_wallet(self):
+        r = keptvow.check(GOOD, 5, base_url="https://k.test")
+        self.assertEqual(r["verdict"], "ok")
+        self.assertIn("amount_usd=5", self.calls[-1][1])
+
+    def test_guard_stops_a_bad_seller_and_passes_a_good_one(self):
+        bad = FakeResponse(402, {"accepts": [{"payTo": SCAM, "maxAmountRequired": "2000000", "asset": USDC}]})
+        with self.assertRaises(keptvow.KeptvowStop) as e:
+            keptvow.guard(bad)
+        self.assertEqual(e.exception.check["pay_to"], SCAM)
+        self.assertIn("amount_usd=2.0", self.calls[-1][1])
+        # The payment request can also come in the PAYMENT-REQUIRED header.
+        header = base64.b64encode(json.dumps({"accepts": [{"payTo": GOOD}]}).encode()).decode()
+        self.assertEqual(keptvow.guard(FakeResponse(402, headers={"PAYMENT-REQUIRED": header}))[0]["verdict"], "ok")
+
+    def test_unreachable_keptvow_pays_on_unless_told_not_to(self):
+        r = FakeResponse(402, {"accepts": [{"payTo": "down"}]})
+        self.assertEqual(keptvow.guard(r), [])
+        with self.assertRaises(OSError):
+            keptvow.guard(r, fail_open=False)
+
+    def test_outcomes_come_from_the_payment_receipt(self):
+        receipt = base64.b64encode(json.dumps({"success": True, "transaction": "0x" + "ab" * 32}).encode()).decode()
+        self.assertTrue(keptvow.report_outcome(FakeResponse(200, {}, {"PAYMENT-RESPONSE": receipt}), background=False))
+        self.assertEqual(self.calls[-1][2], {"tx": "0x" + "ab" * 32, "status": 200})
+        self.assertFalse(keptvow.report_outcome(FakeResponse(200, {}, {})), "no receipt, nothing to report")
+        self.assertTrue(keptvow.report_outcome("0x" + "cd" * 32, delivered=False, background=False))
+        self.assertEqual(self.calls[-1][2], {"tx": "0x" + "cd" * 32, "delivered": False})
+
+    def test_a_fresh_signed_answer_is_reused(self):
+        keptvow.check(SIGNED)
+        keptvow.check(SIGNED.upper().replace("0X", "0x"))
+        self.assertEqual(sum(1 for c in self.calls if SIGNED in c[1].lower()), 1)
+        keptvow.check(SIGNED, cache=False)
+        self.assertEqual(sum(1 for c in self.calls if SIGNED in c[1].lower()), 2)
+        keptvow.check(GOOD)
+        keptvow.check(GOOD)
+        self.assertEqual(sum(1 for c in self.calls if GOOD in c[1]), 2, "unsigned answers are never reused")
+
+    def test_a_report_sent_with_a_key_carries_it(self):
+        keptvow.report_outcome("0x" + "ab" * 32, delivered=True, api_key="k_test", background=False)
+        self.assertEqual(self.report_headers[-1].get("X-Api-Key"), "k_test")
+
+
+@unittest.skipUnless(os.environ.get("KEPTVOW_TEST_URL"), "set KEPTVOW_TEST_URL to test against a server")
+class Live(unittest.TestCase):
+    def test_a_real_server_answers(self):
+        r = keptvow.check("0x" + "12" * 20, base_url=os.environ["KEPTVOW_TEST_URL"])
+        self.assertIn(r["verdict"], ("ok", "careful", "stop"))
+        with self.assertRaises(RuntimeError):
+            keptvow.check("not-a-wallet", base_url=os.environ["KEPTVOW_TEST_URL"])
+
+
+if __name__ == "__main__":
+    unittest.main()