toll-sdk 0.1.0__tar.gz

toll_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.test-build/

toll_sdk-0.1.0/LICENSE

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

toll_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.5
+Name: toll-sdk
+Version: 0.1.0
+Summary: Client for Toll's coin checks (Robinhood Chain, Solana, BSC) over MCP. Standard library only.
+Project-URL: Homepage, https://t0ll.xyz/agents
+Project-URL: Documentation, https://t0ll.xyz/llms.txt
+Project-URL: Repository, https://github.com/t0ll-xyz/toll-plugins
+Author: Toll
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,bsc,larp,mcp,robinhood-chain,rug-check,solana,toll,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# toll-sdk
+
+Python client for [Toll](https://t0ll.xyz/agents)'s coin checks, read from the chain (Robinhood Chain, Solana, BSC), over Toll's remote MCP server. Who is behind a coin, the dev's record, and whether there is a real product behind it. Standard library only, Python >= 3.9, typed.
+
+Information only, not financial advice.
+
+## Install
+
+```sh
+pip install toll-sdk        # import name: toll_sdk
+```
+
+## Example
+
+```python
+from toll_sdk import Toll
+
+toll = Toll()
+check = toll.check_coin("0xff9e86e6b21fd688027981bee4b64c8b6b804ed3", chain="rh")
+print(check.text)                      # markdown facts from the chain
+larp = toll.larp_check("0xff9e86e6b21fd688027981bee4b64c8b6b804ed3", wait=True)
+print(larp.text)                       # product found / partly found / not found / not read
+```
+
+Every method returns `TollResult(text, paid_url, pending)`. `pending` (`{"retry_after_s": n}` or None) means part of the answer is still being read: ask again after that many seconds. `paid_url` is set when the free coins are used up (see below).
+
+## API
+
+`Toll(base_url="https://t0ll.xyz", opener=None, timeout=30.0, sign=None, pay_timeout=300.0)`
+
+- `check_coin(address, chain=None)` - chain is `rh`, `sol` or `bsc`
+- `larp_check(token, chain=None, wait=False)` - `rh` or `sol`; `wait=True` asks again after the seconds the server gives while part of the answer is still being read or Toll is busy with many new LARP checks (max 3 tries, max 120 s)
+- `dev_record(wallet, chain=None)`, `launch_record(address)`, `wallet_privacy(wallet)`, `fresh_launches(limit=None)`, `chain_pulse()`
+- `tools()` lists the server's tools, `call(name, args)` calls any of them
+- `pay(paid_url, sign=None, timeout=None)` - pays a paid URL once and returns its JSON (see below)
+- `is_valid_address(x)`, `is_valid_wallet(x)` - the checks run before anything is sent
+- Failures (HTTP, JSON-RPC, timeouts, server-side input errors) raise `TollError`.
+
+## Free limit and the paid path
+
+10 new coins a day per caller are free (coins already read stay free). Past that, the result carries `paid_url`, the x402 endpoint for that coin (0.05 USDG on Robinhood Chain, charged only for a whole answer).
+
+`pay(paid_url)` runs the x402 flow itself and asks your `sign` function for one payment:
+
+1. GET the URL without payment. Toll answers 402 with what to pay: x402 v2 in the `PAYMENT-REQUIRED` header, v1 in the body.
+2. Call `sign(requirements, url)` **once**. It returns the payment header value.
+3. GET again with it (`PAYMENT-SIGNATURE` for v2, `X-PAYMENT` for v1, following what the 402 offered). While Toll is still reading the coin it answers 402 `{"pending": true}` (nothing charged): `pay` resends **exactly the same header** after `Retry-After` (at least 1 s), up to 5 tries and 300 s. A 200 is the answer. Any other 402 after paying raises `TollError` "payment not accepted"; `pay` never signs a second payment for one call.
+
+The whole call has its own timeout (`pay_timeout`, default 300 s). If it times out or the connection drops after the payment was sent, the error says the payment may have settled: do not retry that call with a new signature; resend the same header.
+
+### The `sign` contract
+
+```python
+from toll_sdk import PaymentRequirements, Toll
+
+def sign(req: PaymentRequirements, url: str) -> str:
+    # req.x402_version: 2 when the 402 had a PAYMENT-REQUIRED header, else 1
+    # req.payment_required: the decoded 402 object; req.accepts: scheme, network "eip155:4663",
+    #   asset (USDG), amount (v2) / maxAmountRequired (v1), payTo, maxTimeoutSeconds, extra
+    # Check the amount and payTo, sign an EIP-3009 USDG transfer authorization with your x402 client,
+    # and return the header value for req.x402_version (the base64 payment payload).
+    ...
+
+toll = Toll(sign=sign)
+r = toll.check_coin(address)
+if r.paid_url:
+    print(toll.pay(r.paid_url))
+```
+
+Your key never touches this SDK. Without a `sign`, `pay` raises before any request. The JavaScript SDK's README has a worked `sign` built on `@priors/x402`. Docs: <https://t0ll.xyz/agents>, <https://t0ll.xyz/llms.txt>, <https://t0ll.xyz/agents/x402>.
+
+MIT.

toll_sdk-0.1.0/README.md

@@ -0,0 +1,72 @@
+# toll-sdk
+
+Python client for [Toll](https://t0ll.xyz/agents)'s coin checks, read from the chain (Robinhood Chain, Solana, BSC), over Toll's remote MCP server. Who is behind a coin, the dev's record, and whether there is a real product behind it. Standard library only, Python >= 3.9, typed.
+
+Information only, not financial advice.
+
+## Install
+
+```sh
+pip install toll-sdk        # import name: toll_sdk
+```
+
+## Example
+
+```python
+from toll_sdk import Toll
+
+toll = Toll()
+check = toll.check_coin("0xff9e86e6b21fd688027981bee4b64c8b6b804ed3", chain="rh")
+print(check.text)                      # markdown facts from the chain
+larp = toll.larp_check("0xff9e86e6b21fd688027981bee4b64c8b6b804ed3", wait=True)
+print(larp.text)                       # product found / partly found / not found / not read
+```
+
+Every method returns `TollResult(text, paid_url, pending)`. `pending` (`{"retry_after_s": n}` or None) means part of the answer is still being read: ask again after that many seconds. `paid_url` is set when the free coins are used up (see below).
+
+## API
+
+`Toll(base_url="https://t0ll.xyz", opener=None, timeout=30.0, sign=None, pay_timeout=300.0)`
+
+- `check_coin(address, chain=None)` - chain is `rh`, `sol` or `bsc`
+- `larp_check(token, chain=None, wait=False)` - `rh` or `sol`; `wait=True` asks again after the seconds the server gives while part of the answer is still being read or Toll is busy with many new LARP checks (max 3 tries, max 120 s)
+- `dev_record(wallet, chain=None)`, `launch_record(address)`, `wallet_privacy(wallet)`, `fresh_launches(limit=None)`, `chain_pulse()`
+- `tools()` lists the server's tools, `call(name, args)` calls any of them
+- `pay(paid_url, sign=None, timeout=None)` - pays a paid URL once and returns its JSON (see below)
+- `is_valid_address(x)`, `is_valid_wallet(x)` - the checks run before anything is sent
+- Failures (HTTP, JSON-RPC, timeouts, server-side input errors) raise `TollError`.
+
+## Free limit and the paid path
+
+10 new coins a day per caller are free (coins already read stay free). Past that, the result carries `paid_url`, the x402 endpoint for that coin (0.05 USDG on Robinhood Chain, charged only for a whole answer).
+
+`pay(paid_url)` runs the x402 flow itself and asks your `sign` function for one payment:
+
+1. GET the URL without payment. Toll answers 402 with what to pay: x402 v2 in the `PAYMENT-REQUIRED` header, v1 in the body.
+2. Call `sign(requirements, url)` **once**. It returns the payment header value.
+3. GET again with it (`PAYMENT-SIGNATURE` for v2, `X-PAYMENT` for v1, following what the 402 offered). While Toll is still reading the coin it answers 402 `{"pending": true}` (nothing charged): `pay` resends **exactly the same header** after `Retry-After` (at least 1 s), up to 5 tries and 300 s. A 200 is the answer. Any other 402 after paying raises `TollError` "payment not accepted"; `pay` never signs a second payment for one call.
+
+The whole call has its own timeout (`pay_timeout`, default 300 s). If it times out or the connection drops after the payment was sent, the error says the payment may have settled: do not retry that call with a new signature; resend the same header.
+
+### The `sign` contract
+
+```python
+from toll_sdk import PaymentRequirements, Toll
+
+def sign(req: PaymentRequirements, url: str) -> str:
+    # req.x402_version: 2 when the 402 had a PAYMENT-REQUIRED header, else 1
+    # req.payment_required: the decoded 402 object; req.accepts: scheme, network "eip155:4663",
+    #   asset (USDG), amount (v2) / maxAmountRequired (v1), payTo, maxTimeoutSeconds, extra
+    # Check the amount and payTo, sign an EIP-3009 USDG transfer authorization with your x402 client,
+    # and return the header value for req.x402_version (the base64 payment payload).
+    ...
+
+toll = Toll(sign=sign)
+r = toll.check_coin(address)
+if r.paid_url:
+    print(toll.pay(r.paid_url))
+```
+
+Your key never touches this SDK. Without a `sign`, `pay` raises before any request. The JavaScript SDK's README has a worked `sign` built on `@priors/x402`. Docs: <https://t0ll.xyz/agents>, <https://t0ll.xyz/llms.txt>, <https://t0ll.xyz/agents/x402>.
+
+MIT.

toll_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "toll-sdk"
+version = "0.1.0"
+description = "Client for Toll's coin checks (Robinhood Chain, Solana, BSC) over MCP. Standard library only."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Toll" }]
+keywords = ["robinhood-chain", "solana", "bsc", "x402", "mcp", "ai-agent", "rug-check", "larp", "toll"]
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://t0ll.xyz/agents"
+Documentation = "https://t0ll.xyz/llms.txt"
+Repository = "https://github.com/t0ll-xyz/toll-plugins"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/toll_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

toll_sdk-0.1.0/src/toll_sdk/__init__.py

@@ -0,0 +1,397 @@
+"""toll-sdk (import toll_sdk): client for Toll's remote MCP server (https://t0ll.xyz/mcp).
+
+Information only, not financial advice.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import re
+import socket
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+__all__ = [
+    "PaymentRequirements",
+    "SignPayment",
+    "Toll",
+    "TollError",
+    "TollResult",
+    "is_valid_address",
+    "is_valid_wallet",
+    "parse_paid_url",
+    "parse_pending",
+    "read_requirements",
+]
+
+_EVM = re.compile(r"0x[0-9a-fA-F]{40}")
+_BASE58 = re.compile(r"[1-9A-HJ-NP-Za-km-z]{32,44}")
+# Only the upsell line counts: a finished LARP answer also lists Toll's own x402 endpoint as a "working part".
+_PAID_URL = re.compile(r"paid (?:LARP )?check of this coin \(x402\):\s*(https://t0ll\.xyz/api/x402/[^\s)\"'<>]+)", re.I)
+_AGAIN = re.compile(r"again in (?:about )?(\d+)\s*(?:s\b|sec)", re.I)
+_PAID_PREFIX = "https://t0ll.xyz/api/x402/"
+_TIMEOUTS = (TimeoutError, socket.timeout)
+_SETTLE_NOTE = (
+    " The payment may have settled: do not retry this call with a new signature;"
+    " resend the same payment header to get the answer."
+)
+
+
+class TollError(Exception):
+    """Any failure: HTTP, JSON-RPC, timeout, server-side input error, bad input."""
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        code: Optional[int] = None,
+        retry_after_s: Optional[int] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retry_after_s = retry_after_s
+
+
+@dataclass
+class TollResult:
+    text: str
+    paid_url: Optional[str]
+    pending: Optional[Dict[str, int]]  # {"retry_after_s": n}: part of the answer is still being read, ask again then
+
+
+@dataclass
+class PaymentRequirements:
+    """What a paid URL asks for, read from its 402 answer."""
+
+    x402_version: int
+    """2 when the 402 carried a PAYMENT-REQUIRED header (sent back as PAYMENT-SIGNATURE), else 1 (X-PAYMENT)."""
+    payment_required: Dict[str, Any]
+    """The decoded 402 object: base64 JSON of the PAYMENT-REQUIRED header (v2) or the JSON body (v1)."""
+    accepts: List[Dict[str, Any]]
+    """payment_required["accepts"]: scheme, network, asset, amount (v2) or maxAmountRequired (v1), payTo, ..."""
+
+
+SignPayment = Callable[[PaymentRequirements, str], str]
+"""sign(requirements, url) -> the payment header value. pay() calls it at most once per call."""
+
+
+def _clamp_seconds(value: Any, fallback: int) -> int:
+    """Seconds to wait, never below 1 (a 0 or junk value must not become a tight loop)."""
+    try:
+        n = float(value)
+    except (TypeError, ValueError):
+        return fallback
+    if n != n or n in (float("inf"), float("-inf")):
+        return fallback
+    return max(1, int(-(-n // 1)))
+
+
+def is_valid_address(value: object) -> bool:
+    """Token address: 0x + 40 hex, or a Solana base58 mint (32-44 chars)."""
+    return isinstance(value, str) and bool(_EVM.fullmatch(value) or _BASE58.fullmatch(value))
+
+
+def is_valid_wallet(value: object) -> bool:
+    """Wallet address: 0x + 40 hex."""
+    return isinstance(value, str) and bool(_EVM.fullmatch(value))
+
+
+def parse_paid_url(text: str) -> Optional[str]:
+    m = _PAID_URL.search(text)
+    return m.group(1).rstrip(".,;:") if m else None
+
+
+def parse_pending(text: str) -> Optional[Dict[str, int]]:
+    m = _AGAIN.search(text)
+    return {"retry_after_s": _clamp_seconds(m.group(1), 5)} if m else None
+
+
+def _check_address(value: object, what: str = "address") -> None:
+    if not is_valid_address(value):
+        raise TollError(f"Invalid {what}: expected 0x + 40 hex characters or a Solana base58 mint (32-44 characters).")
+
+
+def _check_wallet(value: object) -> None:
+    if not is_valid_wallet(value):
+        raise TollError("Invalid wallet: expected 0x + 40 hex characters.")
+
+
+def _check_chain(chain: Optional[str], allowed: tuple) -> None:
+    if chain is not None and chain not in allowed:
+        raise TollError(f'Invalid chain "{chain}": use {", ".join(allowed)}.')
+
+
+def _parse_body(raw: str) -> Any:
+    t = raw.strip()
+    if t.startswith("{"):
+        return json.loads(t)
+    for line in t.splitlines():
+        if line.startswith("data:"):
+            return json.loads(line[5:].strip())
+    raise ValueError("no data")
+
+
+class Toll:
+    """Client. `opener` is a urllib OpenerDirector (or anything with .open(request, timeout=...))."""
+
+    def __init__(
+        self,
+        base_url: str = "https://t0ll.xyz",
+        opener: Any = None,
+        timeout: float = 30.0,
+        sleep: Callable[[float], None] = time.sleep,
+        sign: Optional[SignPayment] = None,
+        pay_timeout: float = 300.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._opener = opener or urllib.request.build_opener()
+        self.timeout = timeout
+        self.pay_timeout = pay_timeout
+        self._sign = sign
+        self._sleep = sleep
+        self._next_id = 1
+
+    # -- transport ---------------------------------------------------------
+    def _http(self, req: urllib.request.Request, timeout: float, note: str = "") -> tuple:
+        """One request, body read inside the timeout. Returns (status, headers, text); HTTP errors are returned too."""
+        try:
+            with self._opener.open(req, timeout=timeout) as res:
+                raw = res.read().decode("utf-8", "replace")
+                return int(getattr(res, "status", 200) or 200), getattr(res, "headers", None) or {}, raw
+        except urllib.error.HTTPError as e:
+            try:
+                raw = e.read().decode("utf-8", "replace") if hasattr(e, "read") else ""
+            except Exception:
+                raw = ""
+            return int(e.code), e.headers or {}, raw
+        except _TIMEOUTS:
+            raise TollError(f"Request to {req.full_url} timed out after {timeout:g} s.{note}") from None
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, _TIMEOUTS):
+                raise TollError(f"Request to {req.full_url} timed out after {timeout:g} s.{note}") from None
+            raise TollError(f"Request to {req.full_url} failed: {e}.{note}") from None
+        except OSError as e:
+            raise TollError(f"Request to {req.full_url} failed: {e}.{note}") from None
+
+    def _rpc(self, method: str, params: Dict[str, Any]) -> Any:
+        payload = json.dumps({"jsonrpc": "2.0", "id": self._next_id, "method": method, "params": params}).encode()
+        self._next_id += 1
+        req = urllib.request.Request(
+            f"{self.base_url}/mcp",
+            data=payload,
+            method="POST",
+            headers={"content-type": "application/json", "accept": "application/json, text/event-stream"},
+        )
+        status, _headers, raw = self._http(req, self.timeout)
+        if not 200 <= status < 300:
+            raise TollError(f"Toll answered HTTP {status}" + (f": {raw[:200]}" if raw else ""), status=status)
+        try:
+            body = _parse_body(raw)
+        except ValueError:
+            raise TollError("Toll sent an answer that is not JSON-RPC.") from None
+        if isinstance(body, dict) and body.get("error"):
+            err = body["error"]
+            raise TollError(f"Toll JSON-RPC error {err.get('code')}: {err.get('message')}", code=err.get("code"))
+        return body.get("result") if isinstance(body, dict) else None
+
+    # -- tools -------------------------------------------------------------
+    def tools(self) -> List[Dict[str, Any]]:
+        r = self._rpc("tools/list", {})
+        return (r or {}).get("tools", [])
+
+    def call(self, name: str, args: Optional[Dict[str, Any]] = None) -> TollResult:
+        """Call any tool by its server name. isError answers raise TollError."""
+        r = self._rpc("tools/call", {"name": name, "arguments": args or {}}) or {}
+        content = r.get("content")
+        text = "\n".join(str(c.get("text", "")) for c in content if isinstance(c, dict) and c.get("type") == "text") if isinstance(content, list) else ""
+        if r.get("isError"):
+            p = parse_pending(text)
+            raise TollError(text.split("\n\n")[0] or "Toll reported an error.", retry_after_s=p["retry_after_s"] if p else None)
+        pending = parse_pending(text) if re.search(r"still reading", text, re.I) else None
+        return TollResult(text=text, paid_url=parse_paid_url(text), pending=pending)
+
+    def check_coin(self, address: str, chain: Optional[str] = None) -> TollResult:
+        _check_address(address)
+        _check_chain(chain, ("rh", "sol", "bsc"))
+        return self.call("check_coin", {"address": address, **({"chain": chain} if chain else {})})
+
+    def larp_check(self, token: str, chain: Optional[str] = None, wait: bool = False) -> TollResult:
+        """LARP check.
+
+        wait=True asks again while part of the answer is still being read, or while Toll answers that it is
+        busy with many new LARP checks (a TollError with retry_after_s): max 3 tries, max 120 s waiting.
+        """
+        _check_address(token, "token")
+        _check_chain(chain, ("rh", "sol"))
+        args = {"token": token, **({"chain": chain} if chain else {})}
+        if not wait:
+            return self.call("larp_check", args)
+        waited = 0
+        tries = 0
+        while True:
+            tries += 1
+            res: Optional[TollResult] = None
+            busy: Optional[TollError] = None
+            try:
+                res = self.call("larp_check", args)
+            except TollError as e:
+                if e.retry_after_s is None:
+                    raise
+                busy = e
+            if res is not None:
+                if not res.pending:
+                    return res
+                s = res.pending["retry_after_s"]
+            else:
+                assert busy is not None and busy.retry_after_s is not None
+                s = busy.retry_after_s
+            if tries >= 3 or waited + s > 120:
+                if busy is not None:
+                    raise busy
+                assert res is not None
+                return res
+            self._sleep(s)
+            waited += s
+
+    def dev_record(self, wallet: str, chain: Optional[str] = None) -> TollResult:
+        _check_wallet(wallet)
+        _check_chain(chain, ("rh", "bsc"))
+        return self.call("dev_record", {"wallet": wallet, **({"chain": chain} if chain else {})})
+
+    def launch_record(self, address: str) -> TollResult:
+        _check_wallet(address)
+        return self.call("launch_record", {"address": address})
+
+    def wallet_privacy(self, wallet: str) -> TollResult:
+        _check_wallet(wallet)
+        return self.call("wallet_privacy", {"wallet": wallet})
+
+    def fresh_launches(self, limit: Optional[int] = None) -> TollResult:
+        if limit is not None and (isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 20):
+            raise TollError("Invalid limit: use a whole number from 1 to 20.")
+        return self.call("fresh_launches", {} if limit is None else {"limit": limit})
+
+    def chain_pulse(self) -> TollResult:
+        return self.call("chain_pulse", {})
+
+    # -- paying ------------------------------------------------------------
+    def pay(self, paid_url: str, sign: Optional[SignPayment] = None, timeout: Optional[float] = None) -> Any:
+        """Pay a paid x402 URL (the paid_url of a result) and return its JSON.
+
+        1. GET without payment: 402 with the requirements (v2 PAYMENT-REQUIRED header, else the v1 body).
+        2. Call sign(requirements, url) ONCE for the payment header value.
+        3. GET with it (v2: PAYMENT-SIGNATURE, v1: X-PAYMENT). On 402 {"pending": true} resend EXACTLY the
+           same header after Retry-After (at least 1 s), max 5 tries and 300 s of waiting. 200 JSON is the
+           answer; any other 402 after paying raises TollError "payment not accepted". It never signs twice.
+        The whole call is bounded by `timeout` (default pay_timeout, 300 s).
+        """
+        if not isinstance(paid_url, str) or not paid_url.startswith(_PAID_PREFIX):
+            raise TollError("pay() only takes https://t0ll.xyz/api/x402/... URLs.")
+        signer = sign or self._sign
+        if signer is None:
+            raise TollError("pay() needs a sign function: Toll(sign=...) or pay(url, sign=...). See the README (paying).")
+        total = self.pay_timeout if timeout is None else timeout
+        deadline = time.monotonic() + total
+
+        def left() -> float:
+            return max(0.001, deadline - time.monotonic())
+
+        def get(headers: Dict[str, str], note: str = "") -> tuple:
+            req = urllib.request.Request(paid_url, method="GET", headers={"accept": "application/json", **headers})
+            return self._http(req, left(), note)
+
+        # 1. Unpaid GET: read what to pay.
+        status, headers, raw = get({})
+        if 200 <= status < 300:
+            return _json_answer(raw, status)
+        if status != 402:
+            raise _http_error(status, raw)
+        requirements = read_requirements(headers, raw)
+
+        # 2. One signature for this call.
+        try:
+            header = signer(requirements, paid_url)
+        except Exception as e:
+            raise TollError(f"sign() failed, nothing was sent: {e}") from None
+        if not isinstance(header, str) or not header.strip() or "\r" in header or "\n" in header:
+            raise TollError("sign() must return the payment header value as one non-empty line; nothing was sent.")
+        name = "PAYMENT-SIGNATURE" if requirements.x402_version == 2 else "X-PAYMENT"
+
+        # 3. Paid GET, resending the same header while the answer is pending.
+        waited = 0
+        tries = 0
+        while True:
+            tries += 1
+            if time.monotonic() >= deadline:
+                raise TollError(f"pay() timed out after {total:g} s.{_SETTLE_NOTE}")
+            status, headers, raw = get({name: header}, _SETTLE_NOTE)
+            data = _try_json(raw)
+            if status == 402 and isinstance(data, dict) and data.get("pending") is True:
+                s = _clamp_seconds(_header(headers, "retry-after"), 5)
+                if tries >= 5 or waited + s > 300 or time.monotonic() + s > deadline:
+                    raise TollError(
+                        f"The paid answer is still being read after {tries} tries (nothing is charged while it is pending)."
+                        " Resend the same payment header later; do not sign a new one for this call.",
+                        status=402,
+                        retry_after_s=s,
+                    )
+                self._sleep(s)
+                waited += s
+                continue
+            if status == 402:
+                why = f" ({data['error']})" if isinstance(data, dict) and isinstance(data.get("error"), str) else ""
+                raise TollError(f"payment not accepted: Toll answered 402 to the signed payment{why}. pay() does not sign again.", status=402)
+            if not 200 <= status < 300:
+                raise _http_error(status, raw, _SETTLE_NOTE)
+            return _json_answer(raw, status)
+
+
+def read_requirements(headers: Any, raw: str) -> PaymentRequirements:
+    """Read a 402: v2 from the PAYMENT-REQUIRED header when it decodes, else v1 from the JSON body."""
+    h = _header(headers, "payment-required")
+    if h:
+        try:
+            pr = json.loads(base64.b64decode(h.strip()).decode("utf-8"))
+            if isinstance(pr, dict) and isinstance(pr.get("accepts"), list) and pr["accepts"]:
+                return PaymentRequirements(x402_version=2, payment_required=pr, accepts=pr["accepts"])
+        except (ValueError, UnicodeDecodeError):
+            pass
+    body = _try_json(raw)
+    if isinstance(body, dict) and isinstance(body.get("accepts"), list) and body["accepts"]:
+        return PaymentRequirements(x402_version=1, payment_required=body, accepts=body["accepts"])
+    raise TollError("Toll answered 402 without x402 payment requirements; nothing was signed.", status=402)
+
+
+def _try_json(raw: str) -> Any:
+    try:
+        return json.loads(raw) if raw else None
+    except ValueError:
+        return None
+
+
+def _json_answer(raw: str, status: int) -> Any:
+    data = _try_json(raw)
+    if data is None:
+        raise TollError("The paid answer was not JSON.", status=status)
+    return data
+
+
+def _http_error(status: int, raw: str, note: str = "") -> TollError:
+    return TollError(f"Toll answered HTTP {status}" + (f": {raw[:200]}" if raw else "") + "." + note, status=status)
+
+
+def _header(headers: Any, name: str) -> Optional[str]:
+    if not headers:
+        return None
+    get = getattr(headers, "get", None)
+    if get is not None and hasattr(headers, "get_all"):  # http.client.HTTPMessage: case-insensitive
+        v = get(name)
+        return None if v is None else str(v)
+    for k in headers:
+        if str(k).lower() == name:
+            return str(headers[k])
+    return None

toll_sdk-0.1.0/tests/fixtures/chain_pulse.json

@@ -0,0 +1 @@
+{"result":{"content":[{"type":"text","text":"Robinhood Chain, right now, as our engine counts it.\n\n- Launches, last 5 min: 1 (Pons)\n- Launches, last hour: 40 (Pons and Long)\n- Of those, graduated: 0 (moved from the curve to a pool)\n- Launches by launchpad, last hour: Pons 27, Long 13; and, not in that total, pools.trade 1\n- Trades on the chain, last minute: 434 (every Uniswap v4 swap)\n- Trades we price, last minute: 214 (the pools we follow plus launch-curve trades)\n- Volume in the pools we follow, only 40 min so far, not a full hour: $3.55M\n- Volume on every venue, last 20 min: $5.37M\n\nRobinhood Chain only. Counted live from the chain by our engine; a figure it did not send is left out, never shown as zero.\n\nLive terminal: https://t0ll.xyz/terminal?utm_source=mcp"}]},"jsonrpc":"2.0","id":1}

toll_sdk-0.1.0/tests/fixtures/check_coin.json

@@ -0,0 +1 @@
+{"result":{"content":[{"type":"text","text":"$TOLL (Toll), a Robinhood Chain token\nDeclared bundle of 1 wallet · 8 flagged wallets bought 5.9% · dev holds 1.2%\nToken: 0xff9e86e6b21fd688027981bee4b64c8b6b804ed3\nLaunched on Pons, 22 days ago. Paired with ETH. On its curve, 25% to graduation.\nMaker: 0x5388872a6bbb5fd94533a4dab2a7a1cab02fa5bc\n\nFindings: 2 against, 1 careful, 5 clear\nCoins that launched like this one (bundle under 1%, snipers under 1%, dev's first launch): 54% dead within 24 h, 0% graduated · 4870 coins, last 30 days\nAt launch:\n- against: 3 wallets sold in the same tenth of a second by the same route, 18 min after launch: 7.7% of supply in one block. 3 of them moved together more than once\n- against: 5 wallets bought in the same tenth of a second by the same route, 7 min after launch: 5.88% of supply in one block\n- careful: first launch from this wallet; who funded it was not read in time\n- clear: the only wallet exempt from the opening tax is the dev's own\n- clear: nobody but the dev bought in the first 3 s\n- clear: 3.24% of supply burned\n- clear: socials declared at launch\n- clear: creator fees go to a Toll fee vault: 90% to the wallet 0x5388…a5bc, 10% buys back and burns $TOLL\n\nNow:\n- Still reading who holds it now: ask again in 20 s.\n\nFigures:\n- Maker's launches: 1 launch\n- Buyers on the curve: at least 296\n- Wallets exempt from tax: 1\n- Flagged wallets: 8, bought 5.9%\n- Creator tax: 1%\n- In the curve: $2k\n- Maker holds now: 1.2% of supply\n- Burned: 3.2% of supply\n\nRead-out:\n- This is the first coin we can find from the wallet that made it.\n- No wallet besides the maker was exempt from the opening tax.\n- The maker has not sold any of its own buy.\n- At least 296 wallets have bought on the curve. It is 25% of the way to graduating.\n\nCould not read: the dev's funder.\nRobinhood Chain only. Read from the chain at block 99,050,751. What it means is yours to decide.\n\nFull report: https://t0ll.xyz/check/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3?utm_source=mcp"}]},"jsonrpc":"2.0","id":1}

toll_sdk-0.1.0/tests/fixtures/check_coin_over.json

@@ -0,0 +1 @@
+{"result": {"content": [{"type": "text", "text": "free checks for today are used (10 coins). unlimited: hold 1M $TOLL, or pay per check with x402 at t0ll.xyz/api/x402.\n\npaid check of this coin (x402): https://t0ll.xyz/api/x402/check/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3?chain=rh\nhow to pay: GET it, sign the 0.05 USDG payment on Robinhood Chain that the 402 answer asks for, and send it in the PAYMENT-SIGNATURE header; charged only for a whole answer."}]}, "jsonrpc": "2.0", "id": 1}

toll_sdk-0.1.0/tests/fixtures/larp_check.json

@@ -0,0 +1 @@
+{"result":{"content":[{"type":"text","text":"LARP check of $TOLL on Robinhood Chain: product found.\n2 claims read from its site. Four different working parts of it answered our own reads, among them: its API at t0ll.xyz/api/check answered with data (fields token, sym, name, supply); its MCP server at t0ll.xyz/mcp answered and listed 7 tools (check_coin, dev_record, wallet_privacy, fresh_launches).\nRead 2026-10-26 16:57 UTC.\n\nWhat it says, and what we found:\n- found: \"Read from the chain for any coin on Robinhood Chain, Solana, BSC and Arc. Free.\" (its site). its API at t0ll.xyz/api/check answered with data (fields token, sym, name, supply); its MCP server at t0ll.xyz/mcp answered and listed 7 tools (check_coin, dev_record, wallet_privacy, fresh_launches)\n- found: \"131 coins checked 20 launchpads 53% dead within 24 h\" (its site). its API at t0ll.xyz/api/check answered with data (fields token, sym, name, supply); its MCP server at t0ll.xyz/mcp answered and listed 7 tools (check_coin, dev_record, wallet_privacy, fresh_launches)\n\nWorking parts we tested:\n- API: answered. its API at t0ll.xyz/api/check answered with data (fields token, sym, name, supply) (https://t0ll.xyz/api/check?addr=0xff9e86e6b21fd688027981bee4b64c8b6b804ed3)\n- MCP: answered. its MCP server at t0ll.xyz/mcp answered and listed 7 tools (check_coin, dev_record, wallet_privacy, fresh_launches) (https://t0ll.xyz/mcp)\n- x402: answered. its x402 endpoint at t0ll.xyz/api/x402/larp/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3 asks 0.05 USDG on Robinhood Chain; 0 payments in 3 days (chain) (https://t0ll.xyz/api/x402/larp/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3)\n- Chrome extension: answered. its Chrome extension “Toll: coin check for Solana, Robinhood Chain and Arc” is listed on the Chrome Web Store (https://chromewebstore.google.com/detail/aclfobbnomcddmcldacomchepinloeeh)\n- Telegram bot: exists. its Telegram bot @t0ll_bot exists, no monthly users shown (https://t.me/t0ll_bot)\n- X account @Tollxyz_: exists (an account is not a working part; it backs no claim).\n- The page we read: https://t0ll.xyz/ (declared at launch).\n\nThe claims are their own words, quoted by Claude Haiku 5.5; Claude Sonnet 5.5 checked each result against our evidence and Claude Opus 5.5 had the final say; every check of them is our own read, and chain facts come from the chain.\nFacts, not a verdict: a quiet contract can be a product that launched yesterday, and a busy one can still lose you money. Not advice.\nHolders of 1M $TOLL get re-reads, the second reader's notes and the dev's full record.\n\nFull LARP check: https://t0ll.xyz/larp/rh/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3?utm_source=mcp"}]},"jsonrpc":"2.0","id":1}

toll_sdk-0.1.0/tests/fixtures/larp_check_busy.json

@@ -0,0 +1 @@
+{"result": {"content": [{"type": "text", "text": "Many new LARP checks are being asked right now. Nothing is wrong with the address. Try again in about 20 seconds.\n\nFull LARP check: https://t0ll.xyz/larp/rh/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3?utm_source=mcp"}], "isError": true}, "jsonrpc": "2.0", "id": 1}

toll_sdk-0.1.0/tests/fixtures/larp_check_over.json

@@ -0,0 +1 @@
+{"result": {"content": [{"type": "text", "text": "free checks for today are used (10 coins). unlimited: hold 1M $TOLL, or pay per check with x402 at t0ll.xyz/api/x402.\n\npaid LARP check of this coin (x402): https://t0ll.xyz/api/x402/larp/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3?chain=rh\nhow to pay: GET it, sign the 0.05 USDG payment on Robinhood Chain that the 402 answer asks for, and send it in the PAYMENT-SIGNATURE header; charged only for a whole answer."}]}, "jsonrpc": "2.0", "id": 1}

toll_sdk-0.1.0/tests/fixtures/larp_check_reading.json

@@ -0,0 +1 @@
+{"result": {"content": [{"type": "text", "text": "Still reading 0xff9e86e6b21fd688027981bee4b64c8b6b804ed3 on Robinhood Chain: it is in the LARP check queue with 2 ahead. The read keeps going on our side.\nCall larp_check again and try again in about 30 seconds.\n\nFull LARP check: https://t0ll.xyz/larp/rh/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3?utm_source=mcp"}]}, "jsonrpc": "2.0", "id": 1}

toll_sdk-0.1.0/tests/fixtures/tools_list.json

@@ -0,0 +1 @@
+{"result":{"tools":[{"name":"check_coin","title":"Check a coin","description":"Check one token on Robinhood Chain, Arc, BSC or Solana from the chain itself: who is behind it and how it launched. On Robinhood Chain: where and when it launched, the maker (dev) and its launch record, snipers in the first 3 seconds, wallets the launch made exempt from tax (bundles), flagged wallets, what the maker holds and sold, burned supply, the curve or pool. On Arc, BSC: the launch, the dev's record, the first buyers, wallets that moved together, who holds the liquidity and whether it can be pulled, and the market. On BSC (four.meme and flap.sh coins): also how far along its curve it is and the tax the token declares. On Solana (pump.fun coins): mint and freeze authority, metadata, Token-2022 extensions, the creation slot and first 3 seconds, the dev's launch buy and whether it sold, its other pump.fun coins, the curve or graduation, the top holders and who first funded them. Toll's findings are tallied as against / careful / clear. The answer's first line names the chain. Reads Robinhood Chain (4663), Arc (5042), BSC (56) and Solana.","inputSchema":{"type":"object","properties":{"address":{"type":"string","pattern":"^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$","description":"The token contract address (a Solana mint address works too): 0x followed by 40 hex characters, or a Solana mint address (base58, case-sensitive)"},"chain":{"type":"string","enum":["rh","arc","bsc","sol"],"description":"Which chain: rh = Robinhood Chain (4663), arc = Arc (5042), bsc = BSC (56), sol = Solana. Leave it out and Toll finds which chain the token is on."}},"required":["address"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Check a coin","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"}},{"name":"larp_check","title":"LARP check","description":"LARP check: is there a real product behind a coin on Robinhood Chain or Solana? Toll reads the coin's own site, launch post and code README, lists each thing it says it offers, and checks every claim against the chain and against its working parts that Toll tries itself (app page, API, MCP server, x402 payments, Chrome extension, Telegram bot, public code). Answers the label (product found / partly found / not found / not read: what we could check, never a verdict), each claim with found / partly / not found and the line that shows it, and the working parts that answered. A coin nobody asked about yet is queued and read within minutes: the answer says how many seconds to wait before calling again. Free: 10 new coins a day per caller, coins already read are always free.","inputSchema":{"type":"object","properties":{"token":{"type":"string","pattern":"^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$","description":"The coin: its token contract on Robinhood Chain, or its Solana mint: 0x followed by 40 hex characters, or a Solana mint address (base58, case-sensitive)"},"chain":{"type":"string","enum":["rh","sol"],"description":"Which chain: rh = Robinhood Chain, sol = Solana. Leave it out and Toll tells them apart by the address (0x is Robinhood Chain, base58 is Solana)."}},"required":["token"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"LARP check","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"execution":{"taskSupport":"forbidden"}},{"name":"dev_record","title":"Deployer record","description":"Every coin one wallet launched on Robinhood Chain, Arc or BSC. On Robinhood Chain (Pons and Long launchpads): how many, how many graduated from the bonding curve, whether the dev sold, and the latest launches with how each ended. On Arc, BSC: how many it launched through the launchpads we know and which of them it still holds. Reads Robinhood Chain unless chain names another.","inputSchema":{"type":"object","properties":{"wallet":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"The deployer (dev) wallet address: 0x followed by 40 hex characters"},"chain":{"type":"string","enum":["rh","arc","bsc"],"description":"Which chain: rh = Robinhood Chain (4663), arc = Arc (5042), bsc = BSC (56). Leave it out for Robinhood Chain."}},"required":["wallet"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Deployer record","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"}},{"name":"wallet_privacy","title":"Wallet privacy check","description":"What anyone can learn about a wallet from Robinhood Chain alone: a privacy grade (A to F), a score out of 100, and each leak found (who funded it, linked wallets, holdings, active hours, launches, trading record, linked accounts) with tips. The grade measures what anyone can see, not whether the wallet is good or bad. Robinhood Chain only.","inputSchema":{"type":"object","properties":{"wallet":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"The wallet address on Robinhood Chain: 0x followed by 40 hex characters"}},"required":["wallet"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Wallet privacy check","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"}},{"name":"fresh_launches","title":"Newest coins","description":"The newest coins launched on Robinhood Chain, newest first, from Toll's live engine: launchpad, age, pair, and the engine's short notes on each (dev record, first buyers, buyers, curve), with a link to the full check. At most 20. Robinhood Chain only.","inputSchema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":20,"description":"How many coins, 1 to 20 (default 10)"}},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Newest coins","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"execution":{"taskSupport":"forbidden"}},{"name":"chain_pulse","title":"Chain pulse","description":"How busy Robinhood Chain is right now, as Toll's live engine counts it: launches in the last 5 minutes and hour, graduations, launches by launchpad, new pools, trades a minute and volume. Robinhood Chain only.","inputSchema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{}},"annotations":{"title":"Chain pulse","readOnlyHint":true,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true},"execution":{"taskSupport":"forbidden"}},{"name":"launch_record","title":"Call at launch","description":"The call Toll made 3 minutes after a Robinhood Chain coin launched, frozen and never edited: against / careful / clear (or launch facts only), the findings tallied, why, the dev's and funder's other coins of the week, and how it ended 24 hours later. Not the coin now: use check_coin for that. Robinhood Chain only.","inputSchema":{"type":"object","properties":{"address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"The token contract address on Robinhood Chain: 0x followed by 40 hex characters"}},"required":["address"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"annotations":{"title":"Call at launch","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},"execution":{"taskSupport":"forbidden"}}]},"jsonrpc":"2.0","id":1}

toll_sdk-0.1.0/tests/fixtures/x402_required.json

@@ -0,0 +1,9 @@
+{
+ "_note": "Real unpaid GET https://t0ll.xyz/api/x402/check/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3 on 2026-10-27 (no payment header sent).",
+ "status": 402,
+ "headers": {
+  "payment-required": "eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwicmVzb3VyY2UiOnsidXJsIjoiaHR0cHM6Ly90MGxsLnh5ei9hcGkveDQwMi9jaGVjay8weGZmOWU4NmU2YjIxZmQ2ODgwMjc5ODFiZWU0YjY0YzhiNmI4MDRlZDMiLCJkZXNjcmlwdGlvbiI6IkNvaW4gY2hlY2sgZm9yIGFueSB0b2tlbiBvbiBSb2Jpbmhvb2QgQ2hhaW4sIFNvbGFuYSwgQlNDIG9yIEFyYzogc25pcGVycyBpbiB0aGUgZmlyc3QgMyBzLCBidW5kbGVzLCB3aG8gZnVuZGVkIHRoZSBkZXYsIHRoZSBkZXYncyBwYXN0IGxhdW5jaGVzLCBsaXF1aWRpdHkuIFJlcGxhY2Uge3Rva2VufSB3aXRoIGFueSBhZGRyZXNzOyA/Y2hhaW49cmh8c29sfGJzY3xhcmMiLCJtaW1lVHlwZSI6ImFwcGxpY2F0aW9uL2pzb24iLCJzZXJ2aWNlTmFtZSI6IlRvbGwgY29pbiBjaGVjayBBUEkiLCJ0YWdzIjpbInJ1Zy1jaGVjayIsIm1lbWVjb2luIiwiZHVlLWRpbGlnZW5jZSIsInNvbGFuYSIsInJvYmluaG9vZC1jaGFpbiJdLCJpY29uVXJsIjoiaHR0cHM6Ly90MGxsLnh5ei9hcHBsZS1pY29uLnBuZyJ9LCJhY2NlcHRzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6NDY2MyIsImFzc2V0IjoiMHg1ZmM1MzYwRDA0MDBhMEZkNGYyYWY1NTJBREQwNDJENzE2RjFkMTY4IiwiYW1vdW50IjoiNTAwMDAiLCJwYXlUbyI6IjB4ZEMzNkQ1MTk2M2QwODg2MmM1MjUwNDVjY0ZEMzlGQWU2YTBDN0Y0MCIsIm1heFRpbWVvdXRTZWNvbmRzIjozMDAsImV4dHJhIjp7Im5hbWUiOiJHbG9iYWwgRG9sbGFyIiwidmVyc2lvbiI6IjEifX1dLCJleHRlbnNpb25zIjp7ImJhemFhciI6eyJpbmZvIjp7ImlucHV0Ijp7InR5cGUiOiJodHRwIiwibWV0aG9kIjoiR0VUIiwicGF0aFBhcmFtcyI6eyJ0b2tlbiI6IjB4ZmY5ZTg2ZTZiMjFmZDY4ODAyNzk4MWJlZTRiNjRjOGI2YjgwNGVkMyJ9LCJxdWVyeVBhcmFtcyI6e319LCJvdXRwdXQiOnsidHlwZSI6Impzb24iLCJleGFtcGxlIjp7InRva2VuIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIiwic3ltIjoiRVhBTVBMRSIsImhlYWRsaW5lIjoiKHRoZSBvbmUtbGluZSBzdW1tYXJ5IG9mIHRoZSBsYXVuY2gsIHRoZSBMUCBhbmQgdGhlIGhvbGRlcnMpIiwiZmxhZ3MiOlt7Imdvb2QiOmZhbHNlLCJ0ZXh0IjoiKG9uZSBmaW5kaW5nKSJ9XSwidW5yZWFkIjpbXX19fSwicm91dGVUZW1wbGF0ZSI6Ii9hcGkveDQwMi9jaGVjay86dG9rZW4iLCJzY2hlbWEiOnsiJHNjaGVtYSI6Imh0dHBzOi8vanNvbi1zY2hlbWEub3JnL2RyYWZ0LzIwMjAtMTIvc2NoZW1hIiwidHlwZSI6Im9iamVjdCIsInByb3BlcnRpZXMiOnsiaW5wdXQiOnsidHlwZSI6Im9iamVjdCIsInByb3BlcnRpZXMiOnsidHlwZSI6eyJ0eXBlIjoic3RyaW5nIiwiY29uc3QiOiJodHRwIn0sIm1ldGhvZCI6eyJ0eXBlIjoic3RyaW5nIiwiZW51bSI6WyJHRVQiXX0sInBhdGhQYXJhbXMiOnsidHlwZSI6Im9iamVjdCIsInByb3BlcnRpZXMiOnsidG9rZW4iOnsidHlwZSI6InN0cmluZyIsInBhdHRlcm4iOiJeKDB4WzAtOWEtZkEtRl17NDB9fFsxLTlBLUhKLU5QLVphLWttLXpdezMyLDQ0fSkkIiwiZGVzY3JpcHRpb24iOiJhbnkgdG9rZW4gYWRkcmVzczogMHggKyA0MCBoZXggKFJvYmluaG9vZCBDaGFpbiwgQlNDLCBBcmMpIG9yIGEgU29sYW5hIG1pbnQgKGJhc2U1OCkifX0sInJlcXVpcmVkIjpbInRva2VuIl0sImFkZGl0aW9uYWxQcm9wZXJ0aWVzIjpmYWxzZX0sInF1ZXJ5UGFyYW1zIjp7InR5cGUiOiJvYmplY3QiLCJwcm9wZXJ0aWVzIjp7ImNoYWluIjp7InR5cGUiOiJzdHJpbmciLCJlbnVtIjpbInJoIiwic29sIiwiYnNjIiwiYXJjIl0sImRlc2NyaXB0aW9uIjoidGhlIGNvaW4ncyBjaGFpbjogcmggPSBSb2Jpbmhvb2QgQ2hhaW4gKGRlZmF1bHQgZm9yIDB4KSwgc29sID0gU29sYW5hIChkZWZhdWx0IGZvciBiYXNlNTgpLCBic2MgPSBCU0MsIGFyYyA9IEFyYyJ9fSwiYWRkaXRpb25hbFByb3BlcnRpZXMiOmZhbHNlfX0sInJlcXVpcmVkIjpbInR5cGUiLCJtZXRob2QiLCJwYXRoUGFyYW1zIl0sImFkZGl0aW9uYWxQcm9wZXJ0aWVzIjpmYWxzZX0sIm91dHB1dCI6eyJ0eXBlIjoib2JqZWN0IiwicHJvcGVydGllcyI6eyJ0eXBlIjp7InR5cGUiOiJzdHJpbmcifSwiZXhhbXBsZSI6eyJ0eXBlIjoib2JqZWN0IiwicHJvcGVydGllcyI6eyJjaGFpbiI6eyJ0eXBlIjoic3RyaW5nIn0sInRva2VuIjp7InR5cGUiOiJzdHJpbmcifSwic3ltIjp7InR5cGUiOiJzdHJpbmcifSwiaGVhZGxpbmUiOnsidHlwZSI6WyJzdHJpbmciLCJudWxsIl19LCJsYXVuY2giOnsidHlwZSI6WyJvYmplY3QiLCJudWxsIl19LCJkZXYiOnsidHlwZSI6WyJvYmplY3QiLCJudWxsIl19LCJkZXZSZWNvcmQiOnsidHlwZSI6WyJvYmplY3QiLCJudWxsIl19LCJjdXJ2ZSI6eyJ0eXBlIjpbIm9iamVjdCIsIm51bGwiXX0sImVhcmx5Ijp7InR5cGUiOlsib2JqZWN0IiwibnVsbCJdfSwiaG9sZGluZ3MiOnsidHlwZSI6Im9iamVjdCJ9LCJob2xkZXJzIjp7InR5cGUiOlsib2JqZWN0IiwibnVsbCJdfSwibHAiOnsidHlwZSI6WyJhcnJheSIsIm9iamVjdCIsIm51bGwiXX0sIm1hcmtldCI6eyJ0eXBlIjpbIm9iamVjdCIsIm51bGwiXX0sImZsYWdzIjp7InR5cGUiOiJhcnJheSJ9LCJmaW5kaW5ncyI6eyJ0eXBlIjoiYXJyYXkifSwibm93Ijp7InR5cGUiOiJvYmplY3QifSwidW5yZWFkIjp7InR5cGUiOiJhcnJheSJ9LCJmYWlsZWQiOnsidHlwZSI6ImFycmF5In0sInJlYWRfdHMiOnsidHlwZSI6Im51bWJlciJ9LCJjaGFyZ2VkIjp7InR5cGUiOiJib29sZWFuIn19LCJhZGRpdGlvbmFsUHJvcGVydGllcyI6dHJ1ZX19LCJyZXF1aXJlZCI6WyJ0eXBlIl19fSwicmVxdWlyZWQiOlsiaW5wdXQiXX19fX0=",
+  "content-type": "application/json"
+ },
+ "body": "{\"x402Version\":1,\"error\":\"Payment required\",\"accepts\":[{\"scheme\":\"exact\",\"network\":\"robinhood\",\"maxAmountRequired\":\"50000\",\"resource\":\"https://t0ll.xyz/api/x402/check/0xff9e86e6b21fd688027981bee4b64c8b6b804ed3\",\"description\":\"Coin check for any token on Robinhood Chain, Solana, BSC or Arc: snipers in the first 3 s, bundles, who funded the dev, the dev's past launches, liquidity. Replace {token} with any address; ?chain=rh|sol|bsc|arc\",\"mimeType\":\"application/json\",\"payTo\":\"0xdC36D51963d08862c525045ccFD39FAe6a0C7F40\",\"maxTimeoutSeconds\":300,\"asset\":\"0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168\",\"outputSchema\":{\"input\":{\"type\":\"http\",\"method\":\"GET\",\"discoverable\":true,\"resourceTemplate\":\"https://t0ll.xyz/api/x402/check/{token}\",\"pathParams\":{\"token\":{\"type\":\"string\",\"pattern\":\"^(0x[0-9a-fA-F]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$\",\"description\":\"any token address: 0x + 40 hex (Robinhood Chain, BSC, Arc) or a Solana mint (base58)\",\"required\":true}},\"queryParams\":{\"chain\":{\"type\":\"string\",\"enum\":[\"rh\",\"sol\",\"bsc\",\"arc\"],\"description\":\"the coin's chain: rh = Robinhood Chain (default for 0x), sol = Solana (default for base58), bsc = BSC, arc = Arc\"}}},\"output\":{\"type\":\"object\",\"description\":\"The same JSON as https://t0ll.xyz/api/check?addr=...&chain=... (Robinhood Chain answers carry flags/curve/holdings/now; Arc, BSC and Solana answers carry chain/findings/holders/lp/failed).\",\"properties\":{\"chain\":{\"type\":\"string\",\"description\":\"the chain read: arc, bsc or sol (absent on a Robinhood Chain answer)\"},\"token\":{\"type\":\"string\",\"description\":\"the token address\"},\"sym\":{\"type\":\"string\",\"description\":\"the ticker (Robinhood Chain; meta.sym elsewhere)\"},\"headline\":{\"type\":[\"string\",\"null\"],\"description\":\"one line: the launch facts, the LP and the holder cluster\"},\"launch\":{\"type\":[\"object\",\"null\"],\"description\":\"where and when it launched: launchpad, block, age, pair, dev\"},\"dev\":{\"type\":[\"object\",\"null\"],\"description\":\"the dev wallet's record: launches, graduated, partial (Robinhood Chain)\"},\"devRecord\":{\"type\":[\"object\",\"null\"],\"description\":\"the dev wallet's past launches (Arc, BSC, Solana)\"},\"curve\":{\"type\":[\"object\",\"null\"],\"description\":\"the bonding curve: snipers in the first 3 s, bundle_pct, dev bought/sold, progress, graduated\"},\"early\":{\"type\":[\"object\",\"null\"],\"description\":\"the first seconds: first buyers, snipers, wallets that moved together\"},\"holdings\":{\"type\":\"object\",\"description\":\"what the dev holds, burned supply\"},\"holders\":{\"type\":[\"object\",\"null\"],\"description\":\"top holders and who first funded them\"},\"lp\":{\"type\":[\"array\",\"object\",\"null\"],\"description\":\"who holds the liquidity and whether it can be pulled\"},\"market\":{\"type\":[\"object\",\"null\"],\"description\":\"mcap, liquidity, 24 h volume (DexScreener)\"},\"flags\":{\"type\":\"array\",\"description\":\"Robinhood Chain findings: { good, note, text }\"},\"findings\":{\"type\":\"array\",\"description\":\"Arc / BSC / Solana findings: { level: against|careful|clear, text }\"},\"now\":{\"type\":\"object\",\"description\":\"Robinhood Chain: who holds it now, which holders share a funder, the last 24 h\"},\"unread\":{\"type\":\"array\",\"description\":\"Robinhood Chain: the parts that could not be read\"},\"failed\":{\"type\":\"array\",\"description\":\"Arc / BSC / Solana: the sections that could not be read\"},\"read_ts\":{\"type\":\"number\",\"description\":\"when the chain was read, unix seconds\"},\"charged\":{\"type\":\"boolean\",\"description\":\"false only on a partial answer given free (then why: \\\"partial\\\" and missing: [...])\"}},\"additionalProperties\":true}},\"extra\":{\"name\":\"Global Dollar\",\"version\":\"1\"}}]}"
+}

toll_sdk-0.1.0/tests/test_toll.py

@@ -0,0 +1,374 @@
+import email.message
+import io
+import json
+import os
+import socket
+import urllib.error
+from pathlib import Path
+
+import pytest
+
+from toll_sdk import PaymentRequirements, Toll, TollError, is_valid_address, is_valid_wallet, parse_paid_url, parse_pending
+
+FX = Path(__file__).parent / "fixtures"
+TOKEN = "0xff9e86e6b21fd688027981bee4b64c8b6b804ed3"
+SOL = "So11111111111111111111111111111111111111112"
+
+
+def fx(name: str) -> str:
+    return (FX / f"{name}.json").read_text(encoding="utf-8")
+
+
+class FakeResponse:
+    def __init__(self, raw: str):
+        self._raw = raw
+
+    def read(self) -> bytes:
+        return self._raw.encode()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+
+class FakeOpener:
+    def __init__(self, *responses):
+        self.responses = list(responses)
+        self.requests = []
+
+    def open(self, req, timeout=None):
+        self.requests.append((req, timeout))
+        r = self.responses.pop(0)
+        if isinstance(r, Exception):
+            raise r
+        return FakeResponse(r)
+
+    def body(self, i=0):
+        return json.loads(self.requests[i][0].data)
+
+
+class Sleeper:
+    def __init__(self):
+        self.slept = []
+
+    def __call__(self, s):
+        self.slept.append(s)
+
+
+def test_validators():
+    assert is_valid_address(TOKEN) and is_valid_address(SOL)
+    assert not is_valid_address("0x123")
+    assert not is_valid_address(TOKEN + "\n")
+    assert not is_valid_address("0OIl" + "1" * 30)
+    assert is_valid_wallet(TOKEN) and not is_valid_wallet(SOL)
+
+
+def test_tools_from_real_list():
+    op = FakeOpener(fx("tools_list"))
+    tools = Toll(opener=op).tools()
+    assert [t["name"] for t in tools] == ["check_coin", "larp_check", "dev_record", "wallet_privacy", "fresh_launches", "chain_pulse", "launch_record"]
+    req, timeout = op.requests[0]
+    assert req.full_url == "https://t0ll.xyz/mcp" and timeout == 30.0
+    assert req.get_header("Accept") == "application/json, text/event-stream"
+
+
+def test_check_coin_real_answer():
+    op = FakeOpener(fx("check_coin"))
+    r = Toll(opener=op).check_coin(TOKEN, chain="rh")
+    assert op.body()["params"] == {"name": "check_coin", "arguments": {"address": TOKEN, "chain": "rh"}}
+    assert r.text.startswith("$TOLL (Toll)")
+    assert r.paid_url is None
+    assert r.pending == {"retry_after_s": 20}  # "Still reading who holds it now: ask again in 20 s."
+
+
+def test_larp_check_uses_token_argument():
+    op = FakeOpener(fx("larp_check"))
+    r = Toll(opener=op).larp_check(TOKEN, chain="rh")
+    assert op.body()["params"] == {"name": "larp_check", "arguments": {"token": TOKEN, "chain": "rh"}}
+    assert "product found" in r.text
+    assert r.pending is None
+    assert r.paid_url is None  # the answer names t0ll.xyz/api/x402/larp/... as a working part: not an upsell
+
+
+def test_chain_pulse():
+    op = FakeOpener(fx("chain_pulse"))
+    r = Toll(opener=op).chain_pulse()
+    assert op.body()["params"] == {"name": "chain_pulse", "arguments": {}}
+    assert r.text.startswith("Robinhood Chain, right now")
+
+
+def test_over_quota_paid_url():
+    t = Toll(opener=FakeOpener(fx("check_coin_over"), fx("larp_check_over")))
+    assert t.check_coin(TOKEN, chain="rh").paid_url == f"https://t0ll.xyz/api/x402/check/{TOKEN}?chain=rh"
+    assert t.larp_check(TOKEN, chain="rh").paid_url == f"https://t0ll.xyz/api/x402/larp/{TOKEN}?chain=rh"
+
+
+def test_parse_paid_url_strict():
+    assert parse_paid_url("paid check of this coin (x402): https://evil.example/api/x402/check/x") is None
+    assert parse_paid_url("a mention of https://t0ll.xyz/api/x402/check/abc") is None
+    assert parse_paid_url("paid check of this coin (x402): https://t0ll.xyz/api/x402/check/abc?chain=sol.") == "https://t0ll.xyz/api/x402/check/abc?chain=sol"
+
+
+def test_pending_still_reading():
+    r = Toll(opener=FakeOpener(fx("larp_check_reading"))).larp_check(TOKEN)
+    assert r.pending == {"retry_after_s": 30}
+    assert parse_pending("nothing") is None
+
+
+def test_larp_wait_retries_max_three_tries():
+    s = Sleeper()
+    op = FakeOpener(fx("larp_check_reading"), fx("larp_check_reading"), fx("larp_check"))
+    r = Toll(opener=op, sleep=s).larp_check(TOKEN, wait=True)
+    assert len(op.requests) == 3 and s.slept == [30, 30] and r.pending is None
+
+    op2 = FakeOpener(*[fx("larp_check_reading")] * 4)
+    r2 = Toll(opener=op2, sleep=Sleeper()).larp_check(TOKEN, wait=True)
+    assert len(op2.requests) == 3 and r2.pending
+
+
+def test_larp_wait_stops_before_120s():
+    long = json.dumps({"result": {"content": [{"type": "text", "text": "Still reading x. Try again in about 100 seconds."}]}})
+    s = Sleeper()
+    op = FakeOpener(long, long, long)
+    r = Toll(opener=op, sleep=s).larp_check(TOKEN, wait=True)
+    assert len(op.requests) == 2 and s.slept == [100] and r.pending
+
+
+def test_larp_wait_treats_busy_like_pending():
+    s = Sleeper()
+    op = FakeOpener(fx("larp_check_busy"), fx("larp_check_reading"), fx("larp_check"))
+    r = Toll(opener=op, sleep=s).larp_check(TOKEN, wait=True)
+    assert len(op.requests) == 3 and s.slept == [20, 30] and "product found" in r.text
+
+    s2 = Sleeper()
+    op2 = FakeOpener(*[fx("larp_check_busy")] * 3, fx("larp_check"))
+    with pytest.raises(TollError) as e:
+        Toll(opener=op2, sleep=s2).larp_check(TOKEN, wait=True)
+    assert e.value.retry_after_s == 20 and len(op2.requests) == 3 and s2.slept == [20, 20]
+
+    bad = json.dumps({"result": {"content": [{"type": "text", "text": "Not a token."}], "isError": True}})
+    op3 = FakeOpener(bad, fx("larp_check"))
+    with pytest.raises(TollError, match="Not a token"):
+        Toll(opener=op3, sleep=Sleeper()).larp_check(TOKEN, wait=True)
+    assert len(op3.requests) == 1
+
+
+def test_errors_become_toll_error():
+    with pytest.raises(TollError, match="Many new LARP checks") as e:
+        Toll(opener=FakeOpener(fx("larp_check_busy"))).larp_check(TOKEN)
+    assert e.value.retry_after_s == 20
+
+    rpc = json.dumps({"jsonrpc": "2.0", "id": 1, "error": {"code": -32602, "message": "bad params"}})
+    with pytest.raises(TollError, match="bad params") as e:
+        Toll(opener=FakeOpener(rpc)).chain_pulse()
+    assert e.value.code == -32602
+
+    http = urllib.error.HTTPError("https://t0ll.xyz/mcp", 429, "Too Many", {}, io.BytesIO(b"slow down"))
+    with pytest.raises(TollError, match="HTTP 429") as e:
+        Toll(opener=FakeOpener(http)).chain_pulse()
+    assert e.value.status == 429
+
+    with pytest.raises(TollError, match="timed out"):
+        Toll(opener=FakeOpener(TimeoutError())).chain_pulse()
+    with pytest.raises(TollError, match="failed"):
+        Toll(opener=FakeOpener(urllib.error.URLError("dns"))).chain_pulse()
+    with pytest.raises(TollError, match="not JSON-RPC"):
+        Toll(opener=FakeOpener("<html>")).chain_pulse()
+
+
+def test_bad_input_never_reaches_network():
+    op = FakeOpener()
+    t = Toll(opener=op)
+    for fn in (
+        lambda: t.check_coin("not an address"),
+        lambda: t.check_coin(TOKEN, chain="eth"),
+        lambda: t.larp_check(SOL + "!"),
+        lambda: t.dev_record(SOL),
+        lambda: t.wallet_privacy("0x1"),
+        lambda: t.launch_record(SOL),
+        lambda: t.fresh_launches(21),
+    ):
+        with pytest.raises(TollError):
+            fn()
+    assert op.requests == []
+
+
+def test_sse_frame():
+    r = Toll(opener=FakeOpener("event: message\ndata: " + fx("chain_pulse") + "\n\n")).chain_pulse()
+    assert "right now" in r.text
+
+
+PAID = f"https://t0ll.xyz/api/x402/check/{TOKEN}?chain=rh"
+# A real unpaid 402 from Toll (captured once, no payment header sent): v2 PAYMENT-REQUIRED header + v1 body.
+REAL_402 = json.loads(fx("x402_required"))
+
+
+def msg_headers(d):
+    m = email.message.Message()
+    for k, v in d.items():
+        m[k] = v
+    return m
+
+
+class HttpOpener:
+    """Answers like urllib: 2xx -> response object, 4xx/5xx -> HTTPError. Items: (status, headers, body) or a callable."""
+
+    def __init__(self, *answers):
+        self.answers = list(answers)
+        self.requests = []
+
+    def open(self, req, timeout=None):
+        self.requests.append((req, timeout))
+        a = self.answers.pop(0)
+        if callable(a):
+            a = a(req, timeout)
+        status, headers, body = a
+        hdrs = msg_headers(headers)
+        if status >= 400:
+            raise urllib.error.HTTPError(req.full_url, status, "x", hdrs, io.BytesIO(body.encode()))
+        r = FakeResponse(body)
+        r.status = status
+        r.headers = hdrs
+        return r
+
+    def header(self, i, name):
+        h = {k.lower(): v for k, v in self.requests[i][0].header_items()}
+        return h.get(name.lower())
+
+
+def required(headers=None):
+    return (402, REAL_402["headers"] if headers is None else headers, REAL_402["body"])
+
+
+def pending(retry_after=None):
+    return (402, {} if retry_after is None else {"Retry-After": retry_after}, '{"pending": true}')
+
+
+class Signer:
+    def __init__(self, value="c2lnbmVkLXBheW1lbnQ="):
+        self.value = value
+        self.seen = []
+
+    def __call__(self, req, url):
+        self.seen.append((req, url))
+        return self.value
+
+
+def test_pay_needs_sign_and_toll_url():
+    op = HttpOpener()
+    with pytest.raises(TollError, match="sign"):
+        Toll(opener=op).pay(PAID)
+    with pytest.raises(TollError):
+        Toll(opener=op, sign=Signer()).pay("https://evil.example/x")
+    assert op.requests == []
+
+
+def test_pay_signs_once_across_several_pendings():
+    s = Sleeper()
+    sg = Signer()
+    op = HttpOpener(required(), pending("7"), pending("0"), pending(), (200, {}, '{"token": "x", "charged": true}'))
+    assert Toll(opener=op, sign=sg, sleep=s).pay(PAID) == {"token": "x", "charged": True}
+
+    assert len(sg.seen) == 1  # one signature for the whole call
+    req, url = sg.seen[0]
+    assert isinstance(req, PaymentRequirements) and req.x402_version == 2 and url == PAID
+    assert req.accepts[0]["network"] == "eip155:4663" and req.accepts[0]["amount"] == "50000"
+    assert req.accepts[0]["asset"] == "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168"
+
+    assert len(op.requests) == 5
+    assert op.header(0, "payment-signature") is None and op.header(0, "x-payment") is None
+    for i in range(1, 5):
+        assert op.requests[i][0].full_url == PAID
+        assert op.header(i, "payment-signature") == "c2lnbmVkLXBheW1lbnQ="
+        assert op.header(i, "x-payment") is None
+    assert s.slept == [7, 1, 5]  # Retry-After 0 is clamped to 1 s, none means 5 s
+
+
+def test_pay_follows_v1_with_x_payment():
+    sg = Signer("djEtcGF5bWVudA==")
+    op = HttpOpener(required({"content-type": "application/json"}), (200, {}, '{"ok": 1}'))
+    assert Toll(opener=op, sign=sg).pay(PAID) == {"ok": 1}
+    req = sg.seen[0][0]
+    assert req.x402_version == 1 and req.accepts[0]["maxAmountRequired"] == "50000"
+    assert op.header(1, "x-payment") == "djEtcGF5bWVudA==" and op.header(1, "payment-signature") is None
+
+
+def test_pay_stops_after_five_pending_tries():
+    s = Sleeper()
+    sg = Signer()
+    op = HttpOpener(required(), *[pending("5")] * 6)
+    with pytest.raises(TollError, match="same payment header") as e:
+        Toll(opener=op, sign=sg, sleep=s).pay(PAID)
+    assert e.value.status == 402
+    assert len(op.requests) == 6 and len(sg.seen) == 1 and s.slept == [5, 5, 5, 5]
+
+
+def test_pay_stops_before_300s_waiting():
+    s = Sleeper()
+    sg = Signer()
+    op = HttpOpener(required(), pending("200"), pending("200"))
+    with pytest.raises(TollError):
+        Toll(opener=op, sign=sg, sleep=s).pay(PAID)
+    assert s.slept == [200] and len(sg.seen) == 1
+
+
+def test_other_402_after_paying_is_not_accepted():
+    sg = Signer()
+    op = HttpOpener(required(), pending("3"), required())
+    with pytest.raises(TollError, match="payment not accepted") as e:
+        Toll(opener=op, sign=sg, sleep=Sleeper()).pay(PAID)
+    assert e.value.status == 402 and len(sg.seen) == 1 and len(op.requests) == 3
+
+
+def test_no_payment_sent_without_requirements_or_when_sign_fails():
+    sg = Signer()
+    with pytest.raises(TollError, match="without x402 payment requirements"):
+        Toll(opener=HttpOpener((402, {}, "{}")), sign=sg).pay(PAID)
+    assert sg.seen == []
+
+    def bad(req, url):
+        raise RuntimeError("no funds")
+
+    op = HttpOpener(required())
+    with pytest.raises(TollError, match="nothing was sent: no funds"):
+        Toll(opener=op, sign=bad).pay(PAID)
+    assert len(op.requests) == 1
+
+    op = HttpOpener(required())
+    with pytest.raises(TollError, match="one non-empty line"):
+        Toll(opener=op, sign=lambda r, u: "a\r\nb").pay(PAID)
+    assert len(op.requests) == 1
+
+
+def test_pay_timeout_warns_not_to_sign_again():
+    sg = Signer()
+
+    def hang(req, timeout):
+        raise TimeoutError()
+
+    op = HttpOpener(required(), hang)
+    with pytest.raises(TollError, match="may have settled") as e:
+        Toll(opener=op, sign=sg).pay(PAID, timeout=40)
+    assert "new signature" in str(e.value) and len(sg.seen) == 1
+    assert op.requests[0][1] <= 40  # each request gets what is left of pay()'s own timeout
+
+    op = HttpOpener(required(), lambda r, t: (_ for _ in ()).throw(urllib.error.URLError(socket.timeout())))
+    with pytest.raises(TollError, match="timed out.*may have settled"):
+        Toll(opener=op, sign=Signer()).pay(PAID)
+
+
+def test_pay_unpaid_200_needs_no_signature():
+    sg = Signer()
+    assert Toll(opener=HttpOpener((200, {}, '{"free": true}')), sign=sg).pay(PAID) == {"free": True}
+    assert sg.seen == []
+
+
+def test_retry_after_clamped():
+    assert parse_pending("try again in 0 s") == {"retry_after_s": 1}
+
+
+@pytest.mark.skipif(os.environ.get("TOLL_LIVE") != "1", reason="set TOLL_LIVE=1 for the live smoke test")
+def test_live_smoke():
+    assert "Robinhood Chain" in Toll().chain_pulse().text

toll_sdk-0.1.0/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.9"
+
+[[package]]
+name = "toll-sdk"
+version = "0.1.0"
+source = { editable = "." }