botsrated 0.1.0__py3-none-any.whl

botsrated/__init__.py

@@ -0,0 +1,41 @@
+"""BotsRated: ask what was measured about an x402 seller before paying it."""
+
+from botsrated.client import (
+    BASE_MAINNET,
+    BASE_USDC,
+    BOTSRATED_BASE_URL,
+    BOTSRATED_PAY_TO,
+    FREE_DAILY_QUOTA,
+    PAID_ROUTE_MAX_ATOMIC,
+    BotsRatedClient,
+    BotsRatedError,
+    Budget,
+    PreflightResult,
+    host_of,
+    is_free_quota_answer,
+    usd_to_atomic,
+)
+from botsrated.guard import Decision, GuardPolicy, PrePaymentGuard, Reason, SellerFacts, evaluate_payment, facts_from
+
+__all__ = [
+    "BASE_MAINNET",
+    "BASE_USDC",
+    "BOTSRATED_BASE_URL",
+    "BOTSRATED_PAY_TO",
+    "FREE_DAILY_QUOTA",
+    "PAID_ROUTE_MAX_ATOMIC",
+    "BotsRatedClient",
+    "BotsRatedError",
+    "Budget",
+    "Decision",
+    "GuardPolicy",
+    "PreflightResult",
+    "PrePaymentGuard",
+    "Reason",
+    "SellerFacts",
+    "evaluate_payment",
+    "facts_from",
+    "host_of",
+    "is_free_quota_answer",
+    "usd_to_atomic",
+]

botsrated/client.py

@@ -0,0 +1,282 @@
+"""HTTP client for BotsRated. Free routes by default; paid routes only with an explicit budget."""
+
+from __future__ import annotations
+
+import base64
+import json
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from decimal import Decimal
+from typing import Any, Literal, Protocol
+from urllib.parse import quote, urlencode, urlsplit
+
+import httpx
+
+BOTSRATED_BASE_URL = "https://botsrated.com"
+BOTSRATED_PAY_TO = "0x7F936f42F46B6c4Cbd3242cF8A1759dfe829E349"
+BASE_MAINNET = "eip155:8453"
+BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+# Published prices (since 2026-10-23) in atomic USDC. Quotes above these are refused.
+PAID_ROUTE_MAX_ATOMIC: dict[str, int] = {"check": 1000, "report": 2000, "best": 10000}
+# Free calls per client (IP) per UTC day. Inside the quota BotsRated answers 200 with charged: false, no 402.
+FREE_DAILY_QUOTA: dict[str, int] = {"check": 100, "report": 10, "best": 0}
+
+
+def is_free_quota_answer(body: Any) -> bool:
+    """True when a 2xx BotsRated body was served from the free daily quota (nothing was charged)."""
+    return isinstance(body, dict) and body.get("charged") is False and isinstance(body.get("free_quota"), dict)
+
+PaidRoute = Literal["check", "report", "best"]
+
+
+class BotsRatedError(Exception):
+    def __init__(self, message: str, code: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class _ResponseLike(Protocol):
+    status_code: int
+    headers: Any
+
+    def json(self) -> Any: ...
+
+
+PayingGet = Callable[[str], _ResponseLike]
+"""A GET that pays x402 challenges, e.g. ``x402_requests(x402_client).get`` or a sync httpx x402 client's ``get``."""
+
+
+def usd_to_atomic(usd: float | str | Decimal) -> int:
+    d = Decimal(str(usd))
+    if d < 0:
+        raise BotsRatedError(f"invalid USD amount: {usd}", "invalid_amount")
+    return int((d * 1_000_000).to_integral_value())
+
+
+def host_of(url_or_host: str) -> str:
+    s = url_or_host.strip()
+    host = urlsplit(s if "://" in s else f"https://{s}").hostname
+    if not host:
+        raise BotsRatedError(f"not a URL or host: {url_or_host}", "invalid_host")
+    return host.lower()
+
+
+def _eq(a: str | None, b: str | None) -> bool:
+    return bool(a) and bool(b) and a.lower() == b.lower()  # type: ignore[union-attr]
+
+
+class Budget:
+    """Spend tracker in atomic USDC. Thread-safe. Reserve before paying; commit or release after."""
+
+    def __init__(self, limit_atomic: int) -> None:
+        if limit_atomic <= 0:
+            raise BotsRatedError("budget must be greater than 0", "invalid_budget")
+        self.limit_atomic = limit_atomic
+        self.spent_atomic = 0
+        self.pending_atomic = 0
+        self._lock = threading.Lock()
+
+    @property
+    def remaining_atomic(self) -> int:
+        return self.limit_atomic - self.spent_atomic - self.pending_atomic
+
+    def reserve(self, amount: int) -> None:
+        with self._lock:
+            if amount > self.remaining_atomic:
+                raise BotsRatedError(
+                    f"budget exceeded: need {amount / 1e6} USD, {self.remaining_atomic / 1e6} USD left",
+                    "budget_exceeded",
+                )
+            self.pending_atomic += amount
+
+    def commit(self, amount: int) -> None:
+        with self._lock:
+            self.pending_atomic -= amount
+            self.spent_atomic += amount
+
+    def release(self, amount: int) -> None:
+        with self._lock:
+            self.pending_atomic -= amount
+
+
+@dataclass
+class PreflightResult:
+    found: bool
+    host: str
+    body: dict[str, Any]
+
+
+def read_payment_required(resp: _ResponseLike) -> dict[str, Any]:
+    header = resp.headers.get("payment-required")
+    try:
+        return json.loads(base64.b64decode(header)) if header else resp.json()
+    except Exception as e:  # noqa: BLE001
+        raise BotsRatedError("could not parse the 402 payment terms", "bad_402") from e
+
+
+class BotsRatedClient:
+    """BotsRated client.
+
+    Args:
+        base_url: Defaults to https://botsrated.com.
+        http: Optional ``httpx.Client`` for unpaid requests.
+        timeout: Seconds per unpaid request.
+        cache_ttl: Preflight cache per host, seconds. 0 disables.
+        budget_usd: Total USD allowed for paid routes. Paid routes stay disabled unless this and ``paying_get`` are set.
+        paying_get: A GET callable that pays x402 challenges.
+        expected_pay_to: BotsRated payTo to accept. Defaults to ``BOTSRATED_PAY_TO``.
+    """
+
+    def __init__(
+        self,
+        base_url: str = BOTSRATED_BASE_URL,
+        *,
+        http: httpx.Client | None = None,
+        timeout: float = 4.0,
+        cache_ttl: float = 300.0,
+        budget_usd: float | str | None = None,
+        paying_get: PayingGet | None = None,
+        expected_pay_to: str = BOTSRATED_PAY_TO,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.host = host_of(self.base_url)
+        self._http = http or httpx.Client(timeout=timeout, headers={"accept": "application/json"})
+        self._cache_ttl = cache_ttl
+        self._cache: dict[str, tuple[float, PreflightResult]] = {}
+        self._paying_get = paying_get
+        self._expected_pay_to = expected_pay_to
+        self.budget: Budget | None = None
+        self.last_free_quota: dict[str, Any] | None = None
+        if (budget_usd is None) != (paying_get is None):
+            raise BotsRatedError("paid routes need both budget_usd and paying_get", "invalid_config")
+        if budget_usd is not None:
+            self.budget = Budget(usd_to_atomic(budget_usd))
+
+    @property
+    def paid_enabled(self) -> bool:
+        return self.budget is not None
+
+    def _get(self, path: str) -> httpx.Response:
+        try:
+            return self._http.get(self.base_url + path)
+        except httpx.HTTPError as e:
+            raise BotsRatedError(f"BotsRated unreachable: {e}", "unreachable") from e
+
+    def preflight(self, url_or_host: str) -> PreflightResult:
+        """Free. Latest stored probe for a seller; ``found=False`` when the host is not covered."""
+        host = host_of(url_or_host)
+        hit = self._cache.get(host)
+        if hit and time.monotonic() - hit[0] < self._cache_ttl:
+            return hit[1]
+        target = url_or_host if "://" in url_or_host else host
+        resp = self._get(f"/v1/preflight?url={quote(target, safe='')}")
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {}
+        err = body.get("error") if isinstance(body, dict) else None
+        if resp.status_code == 404 and isinstance(err, dict) and err.get("code") == "host_not_covered":
+            result = PreflightResult(False, host, {**body, "found": False})
+        elif resp.status_code >= 400:
+            msg = err.get("message") if isinstance(err, dict) else None
+            code = err.get("code") if isinstance(err, dict) else None
+            raise BotsRatedError(msg or f"preflight returned {resp.status_code}", code or "http_error", resp.status_code)
+        else:
+            result = PreflightResult(body.get("found") is not False, host, body)
+        if self._cache_ttl > 0:
+            self._cache[host] = (time.monotonic(), result)
+        return result
+
+    def check(self, url_or_host: str) -> dict[str, Any]:
+        """Paid ($0.001; first 100/day free). Facts, paid test-buys and recent receipts for one host."""
+        return self._paid(f"/v1/check?host={quote(host_of(url_or_host), safe='')}", "check")
+
+    def report(self, url_or_host: str) -> dict[str, Any]:
+        """Paid ($0.002; first 10/day free). Full receipt history for one host."""
+        return self._paid(f"/v1/report/{quote(host_of(url_or_host), safe='')}", "report")
+
+    def best(self, task: str, sort: str | None = None, max_price_usd: float | None = None) -> dict[str, Any]:
+        """Paid ($0.01). Top providers for a task."""
+        q: dict[str, str] = {"task": task}
+        if sort:
+            q["sort"] = sort
+        if max_price_usd is not None:
+            q["max_price"] = str(max_price_usd)
+        return self._paid(f"/v1/best?{urlencode(q)}", "best")
+
+    def acceptable_payment(self, req: dict[str, Any], max_atomic: int = PAID_ROUTE_MAX_ATOMIC["best"]) -> bool:
+        amount = str(req.get("amount", ""))
+        return (
+            req.get("scheme") == "exact"
+            and req.get("network") == BASE_MAINNET
+            and _eq(req.get("asset"), BASE_USDC)
+            and _eq(req.get("payTo") or req.get("pay_to"), self._expected_pay_to)
+            and amount.isdigit()
+            and int(amount) <= max_atomic
+        )
+
+    def is_reserved_payment(self, req: dict[str, Any]) -> bool:
+        """True if ``req`` is an acceptable BotsRated payment this client has reserved budget for."""
+        return (
+            self.budget is not None
+            and self.acceptable_payment(req)
+            and self.budget.pending_atomic >= int(req["amount"])
+        )
+
+    def _paid(self, path: str, route: PaidRoute) -> dict[str, Any]:
+        # Ask unpaid first. Inside the free daily quota this already returns the data (200, charged: false):
+        # nothing is paid and the budget is untouched. Bad input gets a free 4xx here, before any payment.
+        quote_resp = self._get(path)
+        if 200 <= quote_resp.status_code < 300:
+            try:
+                body = quote_resp.json()
+            except ValueError:
+                body = None
+            if is_free_quota_answer(body):
+                self.last_free_quota = body["free_quota"]
+                return body
+            raise BotsRatedError(
+                f"expected 402 or a free-quota answer, got {quote_resp.status_code}", "unexpected_status", quote_resp.status_code
+            )
+        if self.budget is None or self._paying_get is None:
+            msg = "paid BotsRated routes are disabled; pass budget_usd and paying_get"
+            if quote_resp.status_code == 402:
+                msg = "free daily quota used up and " + msg
+            raise BotsRatedError(msg, "paid_disabled", quote_resp.status_code)
+        if quote_resp.status_code != 402:
+            try:
+                err = quote_resp.json().get("error") or {}
+            except ValueError:
+                err = {}
+            raise BotsRatedError(
+                err.get("message") or f"expected 402, got {quote_resp.status_code}",
+                err.get("code") or "unexpected_status",
+                quote_resp.status_code,
+            )
+        terms = read_payment_required(quote_resp)
+        option = next((a for a in terms.get("accepts", []) if self.acceptable_payment(a, PAID_ROUTE_MAX_ATOMIC[route])), None)
+        if option is None:
+            raise BotsRatedError(
+                "no acceptable payment option (Base USDC, exact, BotsRated payTo, published price)", "terms_rejected"
+            )
+        amount = int(option["amount"])
+        self.budget.reserve(amount)
+        try:
+            resp = self._paying_get(self.base_url + path)
+        except Exception:
+            self.budget.release(amount)
+            raise
+        if not 200 <= resp.status_code < 300:
+            self.budget.release(amount)
+            raise BotsRatedError(f"paid {route} returned {resp.status_code}", "paid_call_failed", resp.status_code)
+        out = resp.json()
+        if is_free_quota_answer(out):
+            # Answered from the free quota on the paid attempt: no payment happened.
+            self.budget.release(amount)
+            self.last_free_quota = out["free_quota"]
+            return out
+        self.budget.commit(amount)
+        return out

botsrated/guard.py

@@ -0,0 +1,218 @@
+"""Pre-payment guard: decide whether to pay an x402 seller, using BotsRated's measurements."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+from urllib.parse import urlsplit
+
+from botsrated.client import BotsRatedClient, BotsRatedError, host_of, usd_to_atomic
+
+Effect = Literal["block", "warn", "info"]
+
+
+@dataclass
+class Reason:
+    code: str
+    detail: str
+    effect: Effect
+
+
+@dataclass
+class SellerFacts:
+    covered: bool
+    host: str
+    source: Literal["preflight", "check"]
+    known_pay_tos: list[str] = field(default_factory=list)
+    observed_network: str | None = None
+    probed_url: str | None = None
+    observed_amount: str | None = None
+    valid_402_rate: float | None = None
+    recent_probes: int | None = None
+    stale: bool | None = None
+    last_probe_at: str | None = None
+    receipt_url: str | None = None
+
+
+@dataclass
+class Decision:
+    action: Literal["allow", "block"]
+    host: str | None
+    reasons: list[Reason]
+    facts: SellerFacts | None = None
+
+    def summary(self) -> str:
+        blocking = [r for r in self.reasons if r.effect == "block"] or self.reasons
+        listed = "; ".join(f"{r.code}: {r.detail}" for r in blocking)
+        receipt = f" (receipt: {self.facts.receipt_url})" if self.facts and self.facts.receipt_url else ""
+        verb = "blocked" if self.action == "block" else "allowed"
+        return f"BotsRated pre-payment check {verb} {self.host or 'payment'}" + (f" - {listed}" if listed else "") + receipt
+
+
+@dataclass
+class GuardPolicy:
+    not_covered: Literal["allow", "block"] = "allow"
+    pay_to_mismatch: Literal["allow", "warn", "block"] = "block"
+    price_above_observed: Literal["allow", "warn", "block"] = "warn"
+    stale: Literal["allow", "block"] = "allow"
+    min_valid_402_rate: float | None = None
+
+
+def facts_from(body: dict[str, Any], host: str, source: Literal["preflight", "check"]) -> SellerFacts:
+    probe = body.get("latest_probe") or (body.get("receipts") or [{}])[0] or {}
+    measured = body.get("measured") or {}
+    listing = body.get("listing") or {}
+    rw = body.get("recent_window") or measured.get("recent_window") or {}
+    pay_tos = [listing.get("payTo"), probe.get("live_payTo"), measured.get("last_quoted_payTo")]
+    freshness = body.get("freshness") or {}
+    return SellerFacts(
+        covered=body.get("found") is not False,
+        host=host,
+        source=source,
+        known_pay_tos=sorted({p.lower() for p in pay_tos if isinstance(p, str) and p}),
+        observed_network=probe.get("live_network") or listing.get("network"),
+        probed_url=probe.get("url") or (body.get("route_probed") or {}).get("url"),
+        observed_amount=probe.get("live_amount") or measured.get("last_quoted_amount_atomic"),
+        valid_402_rate=rw.get("valid_402_rate"),
+        recent_probes=rw.get("probes"),
+        stale=freshness.get("stale"),
+        last_probe_at=freshness.get("last_probe_at"),
+        receipt_url=probe.get("receipt_url"),
+    )
+
+
+def _same_route(a: str | None, b: str | None) -> bool:
+    if not a or not b:
+        return False
+    x, y = urlsplit(a), urlsplit(b)
+    return (x.hostname or "") == (y.hostname or "") and x.path.rstrip("/") == y.path.rstrip("/")
+
+
+def as_requirements(req: Any) -> dict[str, Any]:
+    """Accepts a dict or an x402 ``PaymentRequirements`` model; returns camelCase keys."""
+    if isinstance(req, dict):
+        d = dict(req)
+    elif hasattr(req, "model_dump"):
+        d = req.model_dump(by_alias=True)
+    else:
+        d = {k: getattr(req, k, None) for k in ("scheme", "network", "asset", "amount", "pay_to")}
+    if "payTo" not in d and "pay_to" in d:
+        d["payTo"] = d["pay_to"]
+    return d
+
+
+def evaluate_payment(facts: SellerFacts, req: dict[str, Any], resource_url: str | None, policy: GuardPolicy | None = None) -> Decision:
+    p = policy or GuardPolicy()
+    reasons: list[Reason] = []
+
+    def add(code: str, detail: str, effect: str) -> None:
+        if effect != "allow":
+            reasons.append(Reason(code, detail, effect))  # type: ignore[arg-type]
+
+    req = as_requirements(req)
+    pay_to = str(req.get("payTo") or "")
+    amount = str(req.get("amount") or "")
+    if not facts.covered:
+        add("not_covered", f"{facts.host} is not in BotsRated's probe set", "block" if p.not_covered == "block" else "info")
+    else:
+        if facts.observed_network and facts.observed_network != req.get("network"):
+            add("network_not_measured", f"paying on {req.get('network')}; BotsRated measured {facts.observed_network}", "info")
+        elif facts.known_pay_tos and pay_to.lower() not in facts.known_pay_tos:
+            add(
+                "payto_mismatch",
+                f"payTo {pay_to} was never seen by BotsRated for {facts.host} (seen: {', '.join(facts.known_pay_tos)})",
+                p.pay_to_mismatch,
+            )
+        if (
+            facts.observed_amount
+            and str(facts.observed_amount).isdigit()
+            and amount.isdigit()
+            and _same_route(resource_url, facts.probed_url)
+            and int(amount) > int(facts.observed_amount)
+        ):
+            add("price_above_observed", f"quoted {amount} atomic; BotsRated last observed {facts.observed_amount} on this route", p.price_above_observed)
+        if facts.stale:
+            add("stale", f"BotsRated data is older than 24 h (last probe {facts.last_probe_at})", "block" if p.stale == "block" else "info")
+        if (
+            p.min_valid_402_rate is not None
+            and facts.valid_402_rate is not None
+            and (facts.recent_probes or 0) >= 3
+            and facts.valid_402_rate < p.min_valid_402_rate
+        ):
+            add("low_valid_402_rate", f"recent valid-402 rate {facts.valid_402_rate} is below {p.min_valid_402_rate}", "block")
+    action: Literal["allow", "block"] = "block" if any(r.effect == "block" for r in reasons) else "allow"
+    return Decision(action, facts.host, reasons, facts)
+
+
+class PrePaymentGuard:
+    """Decides on x402 payments using BotsRated's free preflight (and, opt-in, a paid check).
+
+    Args:
+        client: A ``BotsRatedClient``; a free-only client is created if omitted.
+        policy: What to block or warn on.
+        fail_open: Allow the payment when BotsRated is unreachable. Default True.
+        paid_check_at_or_above_usd: Run a check for payments at or above this: free within the daily quota
+            (100/day), then a $0.001 paid check with a paid-enabled client (skipped otherwise).
+        on_decision: Called with every decision.
+    """
+
+    def __init__(
+        self,
+        client: BotsRatedClient | None = None,
+        policy: GuardPolicy | None = None,
+        *,
+        fail_open: bool = True,
+        paid_check_at_or_above_usd: float | None = None,
+        on_decision: Callable[[Decision], None] | None = None,
+    ) -> None:
+        self.client = client or BotsRatedClient()
+        self.policy = policy or GuardPolicy()
+        self.fail_open = fail_open
+        self.paid_threshold = paid_check_at_or_above_usd
+        self.on_decision = on_decision
+
+    def decide(self, resource_url: str | None, requirements: Any) -> Decision:
+        req = as_requirements(requirements)
+        if not resource_url:
+            eff: Effect = "info" if self.fail_open else "block"
+            return Decision("allow" if self.fail_open else "block", None, [Reason("no_resource_url", "payment has no resource URL", eff)])
+        host = host_of(resource_url)
+        if host == self.client.host:
+            ok = self.client.is_reserved_payment(req)
+            reasons = [] if ok else [Reason("botsrated_payment_not_reserved", "payments to BotsRated must go through BotsRatedClient with a budget", "block")]
+            return Decision("allow" if ok else "block", host, reasons)
+        try:
+            pre = self.client.preflight(resource_url)
+            facts = facts_from(pre.body, host, "preflight")
+            extra: list[Reason] = []
+            if (
+                pre.found
+                and self.paid_threshold is not None
+                and str(req.get("amount", "")).isdigit()
+                and int(req["amount"]) >= usd_to_atomic(self.paid_threshold)
+            ):
+                try:
+                    facts = facts_from(self.client.check(host), host, "check")
+                except BotsRatedError as e:
+                    extra.append(Reason("paid_check_skipped", str(e), "info"))
+            d = evaluate_payment(facts, req, resource_url, self.policy)
+            d.reasons.extend(extra)
+            return d
+        except BotsRatedError as e:
+            eff = "info" if self.fail_open else "block"
+            return Decision("allow" if self.fail_open else "block", host, [Reason("botsrated_unavailable", str(e), eff)])
+
+    def x402_hook(self, context: Any) -> Any:
+        """Hook for ``x402Client(Sync).on_before_payment_creation``. Returns ``AbortResult`` to block."""
+        pr = context.payment_required
+        resource = getattr(pr, "resource", None)
+        url = getattr(resource, "url", None) if resource is not None else None
+        d = self.decide(url, context.selected_requirements)
+        if self.on_decision:
+            self.on_decision(d)
+        if d.action == "block":
+            from x402 import AbortResult  # optional dependency: botsrated[x402]
+
+            return AbortResult(reason=d.summary())
+        return None

botsrated-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: botsrated
+Version: 0.1.0
+Summary: Pre-payment check for x402 agents: free BotsRated preflight before paying a seller; paid lookups opt-in with a budget.
+Project-URL: Homepage, https://botsrated.com
+Project-URL: Repository, https://github.com/botsrated/botsrated
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,base,botsrated,payments,preflight,usdc,x402
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: x402
+Requires-Dist: x402[evm,httpx]>=2.25; extra == 'x402'
+Description-Content-Type: text/markdown
+
+# botsrated (Python)
+
+A pre-payment check for x402 agents. Before your agent pays a seller, it asks
+[BotsRated](https://botsrated.com) what it has measured about that seller, using the free
+`GET /v1/preflight` route. Paid lookups are opt-in and capped by a budget you set.
+
+BotsRated is in beta. It covers about 4,800 x402 seller hosts on Base, taken from the CDP Bazaar,
+Agentic.Market, 402index and x402-list. Each host gets an unpaid probe about every 5.4 h, and every
+receipt is signed.
+
+**Status: published on PyPI: [`botsrated`](https://pypi.org/project/botsrated/) 0.1.0.**
+
+```bash
+pip install botsrated            # free preflight + guard
+pip install "botsrated[x402]"    # + x402 SDK hook / paid lookups
+```
+
+## Guard an x402 client (free)
+
+```python
+from x402 import x402ClientSync
+from x402.mechanisms.evm import EthAccountSigner
+from x402.mechanisms.evm.exact import ExactEvmScheme
+from botsrated import PrePaymentGuard
+
+client = x402ClientSync()
+client.register("eip155:*", ExactEvmScheme(signer=EthAccountSigner(account)))
+client.on_before_payment_creation(PrePaymentGuard().x402_hook)
+```
+
+Defaults:
+- A payTo that differs from every payTo BotsRated saw for the host, on the same network, is **blocked**.
+- A price above the last observed price on the same route is a warning.
+- A host that is not covered is allowed.
+- Data older than 24 h is allowed.
+- If BotsRated cannot be reached (4 s timeout), the payment is allowed (`fail_open`).
+- The minimum valid-402 rate is off.
+
+Change these with `GuardPolicy(...)`. Preflight answers are cached for 5 minutes per host.
+
+## Opt-in paid lookups with a budget
+
+```python
+from x402.http.clients import x402_requests
+from botsrated import BotsRatedClient, PrePaymentGuard
+
+session = x402_requests(client)                      # pays x402 challenges
+botsrated = BotsRatedClient(budget_usd="0.05", paying_get=session.get)
+guard = PrePaymentGuard(botsrated, paid_check_at_or_above_usd=0.25)
+client.on_before_payment_creation(guard.x402_hook)
+
+botsrated.check("seller.example")     # $0.001 (first 100/day free)
+botsrated.report("seller.example")    # $0.002 (first 10/day free)
+botsrated.best("web search")          # $0.01
+```
+
+How paid calls work:
+- Free daily quota: the first 100 `/v1/check` and 10 `/v1/report` calls per client per UTC day are
+  served free (200 with `charged: false` and a `free_quota` block). The client asks unpaid first, so
+  inside the quota nothing is paid and the budget is untouched; `check()`/`report()` also work without
+  a budget until the quota is used up (then `paid_disabled`). `client.last_free_quota` shows what is left.
+- Otherwise the client reads the 402 quote unpaid first. It accepts only `exact` USDC on Base to BotsRated's payTo
+  `0x7F936f42F46B6c4Cbd3242cF8A1759dfe829E349`, at or below the published price.
+- The amount is reserved from the budget before paying and released if the call fails.
+- When the guard is registered, it refuses any payment to botsrated.com that the client did not reserve.
+
+## Tests
+
+```bash
+uv run --with pytest --with respx --with "x402[evm]" pytest
+```
+
+License: MIT. BotsRated reports measurements, not endorsements.

botsrated-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+botsrated/__init__.py,sha256=eVINDliCS2nS3zePFoZKYKz2WGbuNIVOt1cJlvyXQKI,924
+botsrated/client.py,sha256=1fv6fGJ76KwsmvlZ6E-717EJGWdnS25M118074Hgksw,11602
+botsrated/guard.py,sha256=kDDOI0wq4naPpdgTwRNJud9oFILGr2mTohqjlS9v0O8,9455
+botsrated-0.1.0.dist-info/METADATA,sha256=6LHNgDg7O-5bFvTKFeJvPQgCa_Vd2LSu5kc-4c6mTV4,3717
+botsrated-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+botsrated-0.1.0.dist-info/licenses/LICENSE,sha256=3mkSwjwOJ_YSnozCObgbawNbWffdiM2Z04kunzx7yBg,1066
+botsrated-0.1.0.dist-info/RECORD,,

botsrated-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

botsrated-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BotsRated
+
+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.