settled-x402 0.1.0__py3-none-any.whl

settled_x402/__init__.py

@@ -0,0 +1,113 @@
+"""settled-x402: check an x402 quote against Settled's independent evidence before your agent pays.
+
+    from settled_x402 import settled_guard
+    settled_guard(x402_client, max_usd_per_call=0.25, daily_budget_usd=5)
+
+Docs: https://settled.tools/for-agents · the JavaScript twin: npm `settled-x402`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .core import (
+    DEFAULT_BASE_URL,
+    VERSION,
+    Answer,
+    Checker,
+    EndpointInfo,
+    OptionResult,
+    ParsedAccept,
+    ParsedQuote,
+    QuoteSummary,
+    SettledBlockedError,
+    SettledResult,
+    SettledSummary,
+    acheck,
+    ainspect,
+    assess,
+    block_message,
+    check,
+    decode_payment_required_header,
+    inspect,
+    normalize_network,
+    parse_quote,
+    quote_from_response,
+)
+from .guard import guard_all, settled_guard
+from .spend import (
+    RARITIES,
+    RARITY_LEGENDARY_OVER_USD,
+    FileLedger,
+    LedgerInfo,
+    MemoryLedger,
+    SpendInfo,
+    SpendLedger,
+    SpendLimits,
+    SpendQuestion,
+    SpendToday,
+    default_budget_file,
+    rarity_of,
+    spent_today,
+    utc_day,
+)
+
+__version__ = VERSION
+
+__all__ = [
+    "VERSION",
+    "__version__",
+    "DEFAULT_BASE_URL",
+    # entry points
+    "check",
+    "acheck",
+    "inspect",
+    "ainspect",
+    "settled_guard",
+    "guard_all",
+    "SettledAsyncTransport",
+    "SettledTransport",
+    # results and errors
+    "SettledResult",
+    "SettledBlockedError",
+    "QuoteSummary",
+    "OptionResult",
+    "SettledSummary",
+    "EndpointInfo",
+    "Answer",
+    # quotes
+    "parse_quote",
+    "quote_from_response",
+    "decode_payment_required_header",
+    "ParsedQuote",
+    "ParsedAccept",
+    "normalize_network",
+    # the pieces
+    "assess",
+    "block_message",
+    "Checker",
+    # spending limits and rarity
+    "rarity_of",
+    "RARITIES",
+    "RARITY_LEGENDARY_OVER_USD",
+    "spent_today",
+    "SpendToday",
+    "SpendInfo",
+    "SpendLimits",
+    "SpendQuestion",
+    "SpendLedger",
+    "FileLedger",
+    "MemoryLedger",
+    "LedgerInfo",
+    "default_budget_file",
+    "utc_day",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # The httpx transports import httpx, so they load on first use.
+    if name in ("SettledAsyncTransport", "SettledTransport"):
+        from . import guard
+
+        return getattr(guard, name)
+    raise AttributeError(f"module 'settled_x402' has no attribute {name!r}")

settled_x402/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+import sys
+
+sys.exit(main())

settled_x402/_networks.py

@@ -0,0 +1,138 @@
+# Network and asset tables, copied from settled-x402 (JavaScript) so both guards read a quote the same way.
+# x402 v1 network names as CAIP-2 ids (@x402/evm's v1 table, plus the names Settled also accepts).
+
+V1_NETWORKS: dict[str, str] = {
+    "ethereum": "eip155:1",
+    "sepolia": "eip155:11155111",
+    "abstract": "eip155:2741",
+    "abstract-testnet": "eip155:11124",
+    "base": "eip155:8453",
+    "base-sepolia": "eip155:84532",
+    "avalanche": "eip155:43114",
+    "avalanche-fuji": "eip155:43113",
+    "iotex": "eip155:4689",
+    "sei": "eip155:1329",
+    "sei-testnet": "eip155:1328",
+    "polygon": "eip155:137",
+    "polygon-amoy": "eip155:80002",
+    "peaq": "eip155:3338",
+    "story": "eip155:1514",
+    "educhain": "eip155:41923",
+    "skale-base-sepolia": "eip155:324705682",
+    "megaeth": "eip155:4326",
+    "monad": "eip155:143",
+    "monad-testnet": "eip155:10143",
+    "stable": "eip155:988",
+    "stable-testnet": "eip155:2201",
+    "celo": "eip155:42220",
+    "flare": "eip155:14",
+    "arbitrum": "eip155:42161",
+    "optimism": "eip155:10",
+    "solana": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+    "solana-devnet": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+}
+NETWORK_NAMES: dict[str, str] = {v: k for k, v in V1_NETWORKS.items()}
+
+# USD stablecoins and their decimals by network: @x402/evm 2.28's default assets, plus USDbC on Base, Optimism USDC and
+# Solana USDC. EVM addresses are lowercased; Solana mints keep their case.
+USD_ASSETS: dict[str, dict[str, int]] = {
+    "eip155:8453": {
+        "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": 6,
+        "0xd9aaec86b65d86f6a7b5b1b0c42ffa531710b6ca": 6,
+    },
+    "eip155:84532": {
+        "0x036cbd53842c5426634e7929541ec2318f3dcf7e": 6,
+    },
+    "eip155:1": {
+        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": 6,
+    },
+    "eip155:43114": {
+        "0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e": 6,
+    },
+    "eip155:4326": {
+        "0xfafddbb3fc7688494971a79cc65dca3ef82079e7": 18,
+    },
+    "eip155:143": {
+        "0x754704bc059f8c67012fed69bc8a327a5aafb603": 6,
+    },
+    "eip155:10143": {
+        "0x534b2f3a21130d7a60830c2df862319e593943a3": 6,
+    },
+    "eip155:988": {
+        "0x779ded0c9e1022225f8e0630b35a9b54be713736": 6,
+    },
+    "eip155:2201": {
+        "0x78cf24370174180738c5b8e352b6d14c83a6c9a9": 6,
+    },
+    "eip155:137": {
+        "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359": 6,
+    },
+    "eip155:42161": {
+        "0xaf88d065e77c8cc2239327c5edb3a432268e5831": 6,
+    },
+    "eip155:421614": {
+        "0x75faf114eafb1bdbe2f0316df893fd58ce46aa4d": 6,
+    },
+    "eip155:31612": {
+        "0xdd468a1ddc392dcdbef6db6e34e89aa338f9f186": 18,
+    },
+    "eip155:31611": {
+        "0x118917a40faf1cd7a13db0ef56c86de7973ac503": 18,
+    },
+    "eip155:723487": {
+        "0x33ad9e4bd16b69b5bfded37d8b5d9ff9aba014fb": 6,
+    },
+    "eip155:72344": {
+        "0x33ad9e4bd16b69b5bfded37d8b5d9ff9aba014fb": 6,
+    },
+    "eip155:36900": {
+        "0x9cb8142aebbcdc60af7c97af897a67a8f3ca71c2": 6,
+    },
+    "eip155:190415": {
+        "0x401ecb1d350407f13ba348573e5630b83638e30d": 6,
+    },
+    "eip155:181228": {
+        "0x401ecb1d350407f13ba348573e5630b83638e30d": 6,
+    },
+    "eip155:50": {
+        "0xfa2958cb79b0491cc627c1557f441ef849ca8eb1": 6,
+    },
+    "eip155:51": {
+        "0xb5ab69f7bbada22b28e79c8ffaece55ef1c771d4": 6,
+    },
+    "eip155:38833": {
+        "0xa5b8bf902b2844da17d4506cc827f7f1681735e7": 6,
+    },
+    "eip155:14": {
+        "0xe7cd86e13ac4309349f30b3435a9d337750fc82d": 6,
+    },
+    "eip155:42220": {
+        "0xceba9300f2b948710d2653dd7b07f33a8b32118c": 6,
+        "0x48065fbbe25f71c9282ddf5e1cd6d6a887483d5e": 6,
+        "0xd2ab3c9a02dbbab236bfec45d1d755df4267f771": 6,
+    },
+    "eip155:11142220": {
+        "0x01c5c0122039549ad1493b8220cabedd739bc44e": 6,
+    },
+    "eip155:1329": {
+        "0xe15fc38f6d8c56af07bbcbe3baf5708a2bf42392": 6,
+    },
+    "eip155:1328": {
+        "0x4fcf1784b31630811181f670aea7a7bef803eaed": 6,
+    },
+    "eip155:5042": {
+        "0x3600000000000000000000000000000000000000": 6,
+    },
+    "eip155:5042002": {
+        "0x3600000000000000000000000000000000000000": 6,
+    },
+    "eip155:10": {
+        "0x0b2c639c533813f4aa9d7837caf62653d097ff85": 6,
+    },
+    "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": {
+        "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": 6,
+    },
+    "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": {
+        "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU": 6,
+    },
+}

settled_x402/cli.py

@@ -0,0 +1,184 @@
+"""settled-x402 on the command line: `settled-x402 check <url>` and `settled-x402 spend`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from .core import VERSION, inspect, normalize_network
+from .spend import RARITIES, spent_today
+
+HELP = f"""settled-x402 {VERSION}: check x402 endpoints against Settled before paying
+
+Usage:
+  settled-x402 check <url> [--network <name>] [--post] [--json] [--pass <token>]
+      Read the endpoint's 402 quote (nothing is paid) and ask Settled about it.
+      --network picks the option you would pay on (default: the network Settled has on record).
+      Exit code: 0 pay, 2 caution, 3 avoid, 4 unknown, 1 usage or internal error.
+  settled-x402 spend [--budget-file <path>] [--json]
+      Today's tally from the spend ledger a guard with daily_budget_usd keeps (default: SETTLED_BUDGET_FILE,
+      else ~/.settled-x402/spend.json): what the guard let through, per call, with each call's loot rarity.
+  settled-x402 --version
+
+Environment: SETTLED_PASS (a Settled day pass), SETTLED_PAYER_TOKEN (an x4t_ payer token), SETTLED_BASE_URL,
+SETTLED_ALLOW_PRIVATE_HOSTS=1.
+Docs: https://settled.tools/for-agents"""
+
+EXIT = {"pay": 0, "skipped": 0, "caution": 2, "avoid": 3, "unknown": 4}
+
+NETS = {
+    "eip155:8453": "base",
+    "eip155:84532": "base-sepolia",
+    "eip155:137": "polygon",
+    "eip155:42161": "arbitrum",
+    "eip155:10": "optimism",
+    "eip155:1": "ethereum",
+    "eip155:43114": "avalanche",
+    "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "solana",
+}
+MATCH = {
+    "match": "payTo matches Settled",
+    "evm_match": "same address as on Settled's network",
+    "mismatch": "payTo DIFFERS from Settled",
+    "asset_mismatch": "different asset and payTo",
+    "evm_mismatch": "different address",
+    "not_compared": "not on record at Settled",
+}
+
+
+def _short(a: Any) -> str:
+    return f"{a[:6]}…{a[-4:]}" if isinstance(a, str) and len(a) > 14 else str(a if a is not None else "?")
+
+
+def _money(n: Any) -> str:
+    if isinstance(n, bool) or not isinstance(n, (int, float)):
+        return "an unknown amount"
+    if n >= 1:
+        return f"${n:.2f}"
+    v = float(f"{n:.4g}")
+    return f"${int(v)}" if v == int(v) else f"${v!r}"
+
+
+def _net(n: Any) -> str:
+    return NETS.get(n, n or "?") if isinstance(n, str) else "?"
+
+
+def run_check(target: str, args: argparse.Namespace) -> int:
+    from urllib.parse import urlsplit
+
+    try:
+        parsed = urlsplit(target)
+    except ValueError:
+        parsed = None
+    if parsed is None or parsed.scheme not in ("http", "https") or not parsed.hostname:
+        sys.stderr.write(f"Not an http(s) URL: {target}\n")
+        return 1
+    result = inspect(
+        target,
+        method="POST" if args.post else "GET",
+        network=normalize_network(args.network) if args.network else "auto",
+        pass_token=args.pass_token or os.environ.get("SETTLED_PASS"),
+        payer_token=os.environ.get("SETTLED_PAYER_TOKEN"),
+        base_url=os.environ.get("SETTLED_BASE_URL"),
+        allow_private_hosts=os.environ.get("SETTLED_ALLOW_PRIVATE_HOSTS") == "1",
+    )
+    live = result.endpoint
+    assert live is not None
+    if args.json:
+        d = result.to_dict()
+        d.pop("endpoint", None)
+        d["endpoint_http_status"] = live.http_status
+        d["endpoint_error"] = live.error
+        sys.stdout.write(json.dumps(d, indent=2) + "\n")
+        return EXIT[result.verdict]
+    loot = f" · {RARITIES[result.rarity]['label'].lower()} loot ({RARITIES[result.rarity]['rule']})" if result.rarity else ""
+    lines = [f"{result.verdict.upper()} · {result.url or live.url}{loot}"]
+    q = result.quote
+    if q is not None:
+        lines.append(f"  quote     {_money(q.price_usd)} on {_net(q.network)} to {_short(q.pay_to)}{f' ({q.accepts} options)' if q.accepts > 1 else ''}")
+    elif live.error:
+        lines.append(f"  quote     none (could not reach the endpoint: {live.error})")
+    elif live.http_status == 402:
+        lines.append("  quote     unreadable (the endpoint answered 402, but its quote could not be parsed)")
+    else:
+        lines.append(f"  quote     none (the endpoint answered HTTP {live.http_status} without asking for payment{'' if args.post else '; try --post'})")
+    if len(result.options) > 1:
+        for i, o in enumerate(result.options):
+            head = "  options   " if i == 0 else "            "
+            text = f"{_net(o.network)}: {_money(o.price_usd)} to {_short(o.pay_to)} · {MATCH.get(o.match, o.match)}"
+            lines.append(f"{head}{text if o.considered else f'({text})'}")
+        judged: list[str] = []
+        for o in result.options:
+            if o.considered and _net(o.network) not in judged:
+                judged.append(_net(o.network))
+        if judged and any(not o.considered for o in result.options):
+            lines.append(f"            the verdict covers the options on {', '.join(judged)}; pick another with --network")
+    s = result.settled
+    if s is not None:
+        bits = ", ".join(x for x in (s.status, s.payability) if x)
+        scout = f" · scout's last purchase {str(s.last_delivery_at)[:10]}{f' (tx {_short(s.receipt_tx)})' if s.receipt_tx else ''}" if s.last_delivery_at else ""
+        lines.append(f"  Settled   {bits or 'no record'}{f' · {_money(s.price_usd)} on {_net(s.network)} to {_short(s.pay_to)}' if s.pay_to else ''}{scout}")
+        if s.recommendation:
+            lines.append(f"  preflight {s.recommendation}")
+    for i, r in enumerate(result.reasons):
+        lines.append(f"{'  why       ' if i == 0 else '            '}{r}")
+    if result.details:
+        lines.append(f"  details   {result.details}")
+    sys.stdout.write("\n".join(lines) + "\n")
+    return EXIT[result.verdict]
+
+
+def run_spend(args: argparse.Namespace) -> int:
+    today = spent_today(budget_file=args.budget_file or os.environ.get("SETTLED_BUDGET_FILE") or None)
+    if args.json:
+        sys.stdout.write(json.dumps(today.to_dict(), indent=2) + "\n")
+        return 0
+    lines = [f"{today.day} (UTC) · {_money(today.spent_usd)} let through in {today.calls} paid call{'' if today.calls == 1 else 's'} · ledger {today.ledger.where or today.ledger.kind}"]
+    for e in today.entries:
+        at = str(e.get("at", ""))[11:19]
+        lines.append(f"  {at}  {_money(e.get('priceUsd')):>8}  {str(e.get('rarity') or '?'):<9}  {e.get('url') or '?'}")
+    if not today.entries:
+        lines.append("  nothing yet today")
+    sys.stdout.write("\n".join(lines) + "\n")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="settled-x402", add_help=False)
+    parser.add_argument("command", nargs="?")
+    parser.add_argument("target", nargs="?")
+    parser.add_argument("--post", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--pass", dest="pass_token")
+    parser.add_argument("--network")
+    parser.add_argument("--budget-file", dest="budget_file")
+    parser.add_argument("-v", "--version", action="store_true")
+    parser.add_argument("-h", "--help", action="store_true")
+    try:
+        args = parser.parse_args(list(argv) if argv is not None else None)
+    except SystemExit:
+        sys.stderr.write(HELP + "\n")
+        return 1
+    if args.version:
+        sys.stdout.write(VERSION + "\n")
+        return 0
+    if args.help or not args.command:
+        sys.stdout.write(HELP + "\n")
+        return 0 if args.help else 1
+    if args.command == "check":
+        if not args.target:
+            sys.stderr.write("Usage: settled-x402 check <url>\n")
+            return 1
+        return run_check(args.target, args)
+    if args.command == "spend":
+        return run_spend(args)
+    sys.stderr.write(f"Unknown command: {args.command}\n\n{HELP}\n")
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())