autonomo 0.1.0__tar.gz

autonomo-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

autonomo-0.1.0/LICENSE

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

autonomo-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: autonomo
+Version: 0.1.0
+Summary: One call for AI agents: find the right paid API on Autonomo, pay in USDG or $AUTONOMO (privately through Gloam, or on Borro credit), within spending caps, and get a receipt.
+Project-URL: Homepage, https://autonomo.fun
+Author: Autonomo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,autonomo,borro,gloam,payments,robinhood-chain,usdg,x402
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.13
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Autonomo SDK for Python
+
+One call for AI agents. Say what you need, and the SDK:
+
+1. **Finds the right API** on [Autonomo](https://autonomo.fun), from your words and the kind of input you give
+   (a token or wallet address, a transaction hash, a link).
+2. **Pays for it** with x402 on Robinhood Chain, in USDG or $AUTONOMO, whichever the wallet can afford.
+3. **Pays privately through [Gloam](https://gloam.trade)** when you ask, so the payment doesn't link to your wallet.
+4. **Borrows from a [Borro](https://borro.markets) credit line** when the wallet is short of USDG.
+5. **Keeps to your caps**: a most-per-call and a daily budget, checked before anything is signed.
+6. **Returns the answer and a receipt**: which API, how it was paid, the amount and the transaction link.
+
+```bash
+pip install autonomo
+```
+
+Full examples for each way to pay: [autonomo.fun/docs/sdk](https://autonomo.fun/docs/sdk).
+
+```python
+import os
+from autonomo import Autonomo
+
+autonomo = Autonomo(private_key=os.environ["AUTONOMO_WALLET_KEY"])
+
+result = autonomo.call("is this token safe", input="0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49")
+print(result.data)
+print(result.receipt.route, result.receipt.amount, result.receipt.token, result.receipt.explorer)
+```
+
+Use a **new wallet just for the agent**, holding only what it may spend. A little USDG covers many calls (most APIs
+cost 0.01 USDG). Paying in $AUTONOMO needs a little ETH once, for a Permit2 approval.
+
+## Finding APIs without paying
+
+```python
+autonomo = Autonomo()                      # no key needed to look
+autonomo.find("wallet holdings")           # best matches first
+autonomo.quote("explain this transaction", input="0x…")   # the API, the URL and every price
+```
+
+To skip the search, name the API: `autonomo.call(slug="token-risk", path="/risk/0x…")`.
+
+## Limits
+
+```python
+Autonomo(
+    private_key=...,
+    pay_with="auto",                                  # or "usdg" / "autonomo"
+    per_call={"usdg": "0.05", "autonomo": "5000"},    # the defaults
+    daily={"usdg": "1", "autonomo": "10000"},         # per UTC day; Gloam and Borro count as USDG
+)
+```
+
+A call over a limit is refused before anything is signed, with the reason. Spending is kept in
+`~/.autonomo/spend.json` (shared with the TypeScript SDK); pass `spend_store=MemoryStore()` or your own store to change
+that.
+
+## Private payments with Gloam
+
+`private=True` pays from a private Gloam balance through Gloam's own MCP server, `@gloamtrade/mcp`, running on your
+machine with its key and limits in `~/.gloam/agent.env`. The SDK calls its `gloam_fetch_paid` tool; Gloam cashes out
+exactly the price through its relay and calls the API with it. The SDK holds no Gloam keys, and no wallet key is needed.
+See the [SDK guide](https://autonomo.fun/docs/sdk) for the setup and a full example (it uses `pip install mcp`).
+
+```python
+def fetch_paid(args):   # runs gloam_fetch_paid on an MCP session with @gloamtrade/mcp
+    out = asyncio.run_coroutine_threadsafe(gloam.call_tool("gloam_fetch_paid", args), loop).result()
+    return json.loads(out.content[0].text)
+
+autonomo = Autonomo(gloam_fetch_paid=fetch_paid)
+autonomo.call("newest launches", private=True)
+```
+
+A private call only ever pays through Gloam. If the API doesn't offer it, or Gloam isn't set up, it's refused, never
+sent as a public payment. The price includes Gloam's 0.5% cash-out fee.
+
+## Borrowing with Borro
+
+```python
+autonomo = Autonomo(private_key=..., borro_account="0xYourCreditLine")
+```
+
+When the wallet can't afford a call, the SDK asks Borro's MCP server to prepare a borrow of just what it's short,
+sends it from the wallet (this needs a little ETH for gas), waits for the USDG and pays. The line needs x402 bills
+turned on; see [Pay with a Borro credit line](https://autonomo.fun/docs/borro). Borro's own daily limit still applies.
+
+## The receipt
+
+| Field | |
+| --- | --- |
+| `api` | The API's slug and name |
+| `route` | `usdg`, `autonomo`, `gloam` or `borro` |
+| `amount`, `token` | What was paid |
+| `payer`, `pay_to` | The wallet (or "private (Gloam)") and the API's payment address |
+| `tx`, `explorer` | The payment transaction and its Blockscout link |
+| `borrow_txs`, `approve_tx` | Borro borrows and the one-time Permit2 approval, when there were any |
+| `spent_today` | Today's total against the daily budget |
+
+Errors are `AutonomoError` with a `code` such as `cannot_pay`, `over_limit`, `no_private_option` or `payment_refused`.
+If an API fails after a payment is signed, the payment doesn't settle, so you aren't charged.

autonomo-0.1.0/README.md

@@ -0,0 +1,100 @@
+# Autonomo SDK for Python
+
+One call for AI agents. Say what you need, and the SDK:
+
+1. **Finds the right API** on [Autonomo](https://autonomo.fun), from your words and the kind of input you give
+   (a token or wallet address, a transaction hash, a link).
+2. **Pays for it** with x402 on Robinhood Chain, in USDG or $AUTONOMO, whichever the wallet can afford.
+3. **Pays privately through [Gloam](https://gloam.trade)** when you ask, so the payment doesn't link to your wallet.
+4. **Borrows from a [Borro](https://borro.markets) credit line** when the wallet is short of USDG.
+5. **Keeps to your caps**: a most-per-call and a daily budget, checked before anything is signed.
+6. **Returns the answer and a receipt**: which API, how it was paid, the amount and the transaction link.
+
+```bash
+pip install autonomo
+```
+
+Full examples for each way to pay: [autonomo.fun/docs/sdk](https://autonomo.fun/docs/sdk).
+
+```python
+import os
+from autonomo import Autonomo
+
+autonomo = Autonomo(private_key=os.environ["AUTONOMO_WALLET_KEY"])
+
+result = autonomo.call("is this token safe", input="0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49")
+print(result.data)
+print(result.receipt.route, result.receipt.amount, result.receipt.token, result.receipt.explorer)
+```
+
+Use a **new wallet just for the agent**, holding only what it may spend. A little USDG covers many calls (most APIs
+cost 0.01 USDG). Paying in $AUTONOMO needs a little ETH once, for a Permit2 approval.
+
+## Finding APIs without paying
+
+```python
+autonomo = Autonomo()                      # no key needed to look
+autonomo.find("wallet holdings")           # best matches first
+autonomo.quote("explain this transaction", input="0x…")   # the API, the URL and every price
+```
+
+To skip the search, name the API: `autonomo.call(slug="token-risk", path="/risk/0x…")`.
+
+## Limits
+
+```python
+Autonomo(
+    private_key=...,
+    pay_with="auto",                                  # or "usdg" / "autonomo"
+    per_call={"usdg": "0.05", "autonomo": "5000"},    # the defaults
+    daily={"usdg": "1", "autonomo": "10000"},         # per UTC day; Gloam and Borro count as USDG
+)
+```
+
+A call over a limit is refused before anything is signed, with the reason. Spending is kept in
+`~/.autonomo/spend.json` (shared with the TypeScript SDK); pass `spend_store=MemoryStore()` or your own store to change
+that.
+
+## Private payments with Gloam
+
+`private=True` pays from a private Gloam balance through Gloam's own MCP server, `@gloamtrade/mcp`, running on your
+machine with its key and limits in `~/.gloam/agent.env`. The SDK calls its `gloam_fetch_paid` tool; Gloam cashes out
+exactly the price through its relay and calls the API with it. The SDK holds no Gloam keys, and no wallet key is needed.
+See the [SDK guide](https://autonomo.fun/docs/sdk) for the setup and a full example (it uses `pip install mcp`).
+
+```python
+def fetch_paid(args):   # runs gloam_fetch_paid on an MCP session with @gloamtrade/mcp
+    out = asyncio.run_coroutine_threadsafe(gloam.call_tool("gloam_fetch_paid", args), loop).result()
+    return json.loads(out.content[0].text)
+
+autonomo = Autonomo(gloam_fetch_paid=fetch_paid)
+autonomo.call("newest launches", private=True)
+```
+
+A private call only ever pays through Gloam. If the API doesn't offer it, or Gloam isn't set up, it's refused, never
+sent as a public payment. The price includes Gloam's 0.5% cash-out fee.
+
+## Borrowing with Borro
+
+```python
+autonomo = Autonomo(private_key=..., borro_account="0xYourCreditLine")
+```
+
+When the wallet can't afford a call, the SDK asks Borro's MCP server to prepare a borrow of just what it's short,
+sends it from the wallet (this needs a little ETH for gas), waits for the USDG and pays. The line needs x402 bills
+turned on; see [Pay with a Borro credit line](https://autonomo.fun/docs/borro). Borro's own daily limit still applies.
+
+## The receipt
+
+| Field | |
+| --- | --- |
+| `api` | The API's slug and name |
+| `route` | `usdg`, `autonomo`, `gloam` or `borro` |
+| `amount`, `token` | What was paid |
+| `payer`, `pay_to` | The wallet (or "private (Gloam)") and the API's payment address |
+| `tx`, `explorer` | The payment transaction and its Blockscout link |
+| `borrow_txs`, `approve_tx` | Borro borrows and the one-time Permit2 approval, when there were any |
+| `spent_today` | Today's total against the daily budget |
+
+Errors are `AutonomoError` with a `code` such as `cannot_pay`, `over_limit`, `no_private_option` or `payment_refused`.
+If an API fails after a payment is signed, the payment doesn't settle, so you aren't charged.

autonomo-0.1.0/examples/borro.py

@@ -0,0 +1,14 @@
+"""Borrow what the wallet is short from a Borro credit line, then pay."""
+import os
+
+from autonomo import Autonomo
+
+autonomo = Autonomo(
+    private_key=os.environ["AUTONOMO_WALLET_KEY"],
+    pay_with="usdg",
+    borro_account=os.environ["BORRO_CREDIT_LINE"],
+)
+
+result = autonomo.call("explain this transaction", input="0x0f1635d41a8fbbde7d61ad39e045e067780b921329112c16955bc26ad3423041")
+print(result.data)
+print(result.receipt.route, result.receipt.borrow_txs, result.receipt.explorer)

autonomo-0.1.0/examples/gloam.py

@@ -0,0 +1,28 @@
+"""Pay privately from a Gloam balance, through Gloam's own MCP server running on this machine.
+It reads its key and limits from ~/.gloam/agent.env (GLOAM_NETWORK=robinhood-mainnet). Needs `pip install mcp`."""
+import asyncio
+import json
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+from autonomo import Autonomo
+
+
+async def main():
+    server = StdioServerParameters(command="npx", args=["-y", "@gloamtrade/mcp"])
+    async with stdio_client(server) as (read, write), ClientSession(read, write) as gloam:
+        await gloam.initialize()
+        loop = asyncio.get_running_loop()
+
+        def fetch_paid(args):
+            out = asyncio.run_coroutine_threadsafe(gloam.call_tool("gloam_fetch_paid", args), loop).result()
+            return json.loads(out.content[0].text)
+
+        autonomo = Autonomo(gloam_fetch_paid=fetch_paid)
+        result = await asyncio.to_thread(autonomo.call, "newest launches", private=True)
+        print(result.data)
+        print(result.receipt.route, result.receipt.amount, result.receipt.explorer)
+
+
+asyncio.run(main())

autonomo-0.1.0/examples/pay.py

@@ -0,0 +1,14 @@
+"""Pay from the agent's own wallet: USDG first, then $AUTONOMO."""
+import os
+
+from autonomo import Autonomo
+
+autonomo = Autonomo(
+    private_key=os.environ["AUTONOMO_WALLET_KEY"],
+    per_call={"usdg": "0.02"},
+    daily={"usdg": "0.50"},
+)
+
+result = autonomo.call("is this token safe", input="0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49")
+print(result.data)
+print(result.receipt.route, result.receipt.amount, result.receipt.token, result.receipt.explorer)

autonomo-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "autonomo"
+version = "0.1.0"
+description = "One call for AI agents: find the right paid API on Autonomo, pay in USDG or $AUTONOMO (privately through Gloam, or on Borro credit), within spending caps, and get a receipt."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Autonomo" }]
+keywords = ["x402", "autonomo", "ai-agents", "robinhood-chain", "usdg", "payments", "gloam", "borro"]
+dependencies = ["eth-account>=0.13", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://autonomo.fun"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/autonomo"]

autonomo-0.1.0/src/autonomo/__init__.py

@@ -0,0 +1,720 @@
+"""Autonomo SDK: one call that finds the right paid API on Autonomo, pays for it on Robinhood Chain and returns the
+answer with a receipt.
+
+    from autonomo import Autonomo
+    autonomo = Autonomo(private_key=os.environ["AUTONOMO_WALLET_KEY"])
+    result = autonomo.call("is this token safe", input="0x…")
+    result.data, result.receipt
+
+How a call is paid, in order:
+    private=True   Only through Gloam, from a private balance, so the payment doesn't link to the wallet. Never falls
+                   back to a public payment.
+    otherwise      USDG, then $AUTONOMO (or just the one set in pay_with), from the wallet, whichever it can afford.
+                   If it can't afford either and a Borro credit line is set, it borrows the USDG it's short and pays.
+Every route checks the per-call cap and the daily budget before anything is signed or sent.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import secrets
+import time
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from decimal import Decimal
+from pathlib import Path
+from typing import Any, Callable, Literal, Optional, Protocol
+from urllib.parse import quote as urlquote, urlparse
+
+import httpx
+from eth_account import Account
+from eth_utils import to_checksum_address
+
+__version__ = "0.1.0"
+__all__ = ["Autonomo", "AutonomoError", "Api", "Receipt", "CallResult", "MemoryStore", "FileStore", "rank_apis", "find_transactions"]
+
+NETWORK = "eip155:4663"
+CHAIN_ID = 4663
+EXPLORER = "https://robinhoodchain.blockscout.com"
+PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3"
+PERMIT2_PROXY = "0x402085c248EeA27D92E8b30b2C58ed07f9E20001"  # x402's exact-scheme Permit2 proxy
+BORRO_MCP = "https://borro.markets/mcp"
+MAX_UINT256 = 2**256 - 1
+
+TokenName = Literal["usdg", "autonomo"]
+Route = Literal["usdg", "autonomo", "gloam", "borro"]
+
+
+@dataclass(frozen=True)
+class Token:
+    name: str
+    symbol: str
+    address: str
+    decimals: int
+
+
+TOKENS = {
+    "usdg": Token("usdg", "USDG", "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", 6),
+    "autonomo": Token("autonomo", "AUTONOMO", "0xe83c85e1ead16fcfe85401e2b337fb4fb5b5cc96", 18),
+}
+DEFAULT_PER_CALL = {"usdg": "0.05", "autonomo": "5000"}
+DEFAULT_DAILY = {"usdg": "1", "autonomo": "10000"}
+
+
+class AutonomoError(Exception):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def _fail(code: str, message: str):
+    raise AutonomoError(code, message)
+
+
+def _units(amount: str, decimals: int) -> int:
+    return int(Decimal(amount) * (10**decimals))
+
+
+def _fmt(amount: int, decimals: int) -> str:
+    s = format(Decimal(amount) / (Decimal(10) ** decimals), "f")
+    return s.rstrip("0").rstrip(".") if "." in s else s
+
+
+def _today() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def _b64(obj: Any) -> str:
+    return base64.b64encode(json.dumps(obj, separators=(",", ":")).encode()).decode()
+
+
+def _unb64(h: Optional[str]) -> Optional[dict]:
+    if not h:
+        return None
+    try:
+        return json.loads(base64.b64decode(h))
+    except Exception:
+        return None
+
+
+# ---------- Public types ----------
+
+
+@dataclass
+class Api:
+    slug: str
+    name: str
+    description: str
+    path: str
+    price: dict
+    verified: bool
+    success_rate: Optional[float]
+    paid_calls_30d: int
+
+
+@dataclass
+class Receipt:
+    api: dict
+    url: str
+    route: str
+    amount: str
+    token: str
+    payer: str
+    pay_to: str
+    tx: Optional[str]
+    explorer: Optional[str]
+    borrow_txs: list = field(default_factory=list)
+    approve_tx: Optional[str] = None
+    at: str = ""
+    spent_today: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class CallResult:
+    data: Any
+    receipt: Receipt
+
+
+class SpendStore(Protocol):
+    def get(self, day: str) -> dict: ...
+    def add(self, day: str, token: str, amount: int) -> None: ...
+
+
+class MemoryStore:
+    """Keeps spending in memory only, for tests or short-lived agents."""
+
+    def __init__(self):
+        self.days: dict[str, dict[str, int]] = {}
+
+    def get(self, day: str) -> dict:
+        return dict(self.days.get(day, {}))
+
+    def add(self, day: str, token: str, amount: int) -> None:
+        d = self.days.setdefault(day, {})
+        d[token] = d.get(token, 0) + amount
+
+
+class FileStore:
+    """Today's spending in a JSON file, ~/.autonomo/spend.json by default (shared with the TypeScript SDK)."""
+
+    def __init__(self, path: Optional[str] = None):
+        self.path = Path(path) if path else Path.home() / ".autonomo" / "spend.json"
+
+    def _read(self) -> dict:
+        try:
+            return json.loads(self.path.read_text())
+        except Exception:
+            return {}
+
+    def get(self, day: str) -> dict:
+        s = self._read()
+        if s.get("date") != day:
+            return {}
+        return {k: int(s.get(k, 0)) for k in ("usdg", "autonomo")}
+
+    def add(self, day: str, token: str, amount: int) -> None:
+        s = self._read()
+        cur = s if s.get("date") == day else {"date": day}
+        cur[token] = str(int(cur.get(token, 0)) + amount)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(cur))
+
+
+# ---------- Finding the right API ----------
+
+
+def _kind_of(value: Optional[str]) -> Optional[str]:
+    if value is None:
+        return None
+    if re.fullmatch(r"0x[0-9a-fA-F]{64}", value):
+        return "tx"
+    if re.fullmatch(r"0x[0-9a-fA-F]{40}", value):
+        return "address"
+    if re.match(r"https?://", value, re.I):
+        return "url"
+    return "text"
+
+
+def _placeholders(path: str) -> list[str]:
+    return [m.lower() for m in re.findall(r"<([^>]+)>", path)]
+
+
+def _fits(path: str, kind: Optional[str]) -> bool:
+    ph = _placeholders(path)
+    if kind is None:
+        return not ph
+    if len(ph) != 1:
+        return False
+    p = ph[0]
+    if kind == "tx":
+        return bool(re.search(r"transaction|hash", p))
+    if kind == "address":
+        return "address" in p
+    if kind == "url":
+        return bool(re.search(r"url|link", p))
+    return not re.search(r"address|hash|url|link", p)
+
+
+def _fill(path: str, value: Optional[str]) -> str:
+    if value is None:
+        return path
+
+    def repl(m: re.Match) -> str:
+        return urlquote(value, safe="") if re.search(r"url|link", m.group(1), re.I) else value
+
+    return re.sub(r"<([^>]+)>", repl, path, count=1)
+
+
+def rank_apis(apis: list[Api], query: str, input: Optional[str] = None) -> list[Api]:
+    """Ranks APIs for a query and input: word matches first, then a fitting path, then verified and the track record."""
+    words = [w for w in re.split(r"[^a-z0-9$]+", query.lower()) if len(w) > 2]
+    kind = _kind_of(input)
+    scored = []
+    for a in apis:
+        if not _fits(a.path, kind):
+            continue
+        hay = f"{a.slug} {a.name} {a.description}".lower()
+        hits = sum(1 for w in words if w in hay)
+        if hits == 0 and words:
+            continue
+        rate = a.success_rate if a.success_rate is not None else 0.5
+        trust = (1 if a.verified else 0) + rate + min(a.paid_calls_30d, 100) / 1000
+        scored.append((hits, trust, a))
+    scored.sort(key=lambda s: (-s[0], -s[1]))
+    return [s[2] for s in scored]
+
+
+# ---------- Typed data ----------
+
+
+def eip3009_typed_data(auth: dict, asset: str, name: str, version: str) -> dict:
+    return {
+        "domain": {"name": name, "version": version, "chainId": CHAIN_ID, "verifyingContract": to_checksum_address(asset)},
+        "types": {
+            "TransferWithAuthorization": [
+                {"name": "from", "type": "address"},
+                {"name": "to", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "validAfter", "type": "uint256"},
+                {"name": "validBefore", "type": "uint256"},
+                {"name": "nonce", "type": "bytes32"},
+            ]
+        },
+        "message": {
+            "from": to_checksum_address(auth["from"]),
+            "to": to_checksum_address(auth["to"]),
+            "value": int(auth["value"]),
+            "validAfter": int(auth["validAfter"]),
+            "validBefore": int(auth["validBefore"]),
+            "nonce": bytes.fromhex(auth["nonce"][2:]),
+        },
+    }
+
+
+def permit2_typed_data(auth: dict) -> dict:
+    return {
+        "domain": {"name": "Permit2", "chainId": CHAIN_ID, "verifyingContract": PERMIT2},
+        "types": {
+            "PermitWitnessTransferFrom": [
+                {"name": "permitted", "type": "TokenPermissions"},
+                {"name": "spender", "type": "address"},
+                {"name": "nonce", "type": "uint256"},
+                {"name": "deadline", "type": "uint256"},
+                {"name": "witness", "type": "Witness"},
+            ],
+            "TokenPermissions": [{"name": "token", "type": "address"}, {"name": "amount", "type": "uint256"}],
+            "Witness": [{"name": "to", "type": "address"}, {"name": "validAfter", "type": "uint256"}],
+        },
+        "message": {
+            "permitted": {"token": to_checksum_address(auth["permitted"]["token"]), "amount": int(auth["permitted"]["amount"])},
+            "spender": to_checksum_address(auth["spender"]),
+            "nonce": int(auth["nonce"]),
+            "deadline": int(auth["deadline"]),
+            "witness": {"to": to_checksum_address(auth["witness"]["to"]), "validAfter": int(auth["witness"]["validAfter"])},
+        },
+    }
+
+
+def _sign_typed(key: str, typed: dict) -> str:
+    signed = Account.sign_typed_data(key, domain_data=typed["domain"], message_types=typed["types"], message_data=typed["message"])
+    return "0x" + bytes(signed.signature).hex()
+
+
+def find_transactions(value: Any) -> list[dict]:
+    """Every transaction ({to, data}) inside a tool result, in order, skipping the typed data to sign."""
+    out: list[dict] = []
+
+    def walk(v: Any) -> None:
+        if isinstance(v, list):
+            for x in v:
+                walk(x)
+            return
+        if not isinstance(v, dict):
+            return
+        to, data = v.get("to"), v.get("data")
+        if isinstance(to, str) and re.fullmatch(r"0x[0-9a-fA-F]{40}", to) and isinstance(data, str) and re.fullmatch(r"0x[0-9a-fA-F]+", data):
+            out.append({"to": to, "data": data, "value": None if v.get("value") is None else str(v["value"])})
+            return
+        for k, x in v.items():
+            if k != "typed_data":
+                walk(x)
+
+    walk(value)
+    return out
+
+
+# ---------- The client ----------
+
+GloamFetchPaid = Callable[[dict], dict]
+"""Runs Gloam's gloam_fetch_paid tool (from `npx -y @gloamtrade/mcp`) with these arguments ({url, maxAmount, prefer})
+and returns its result: Gloam cashes out exactly the quoted USDG from your private balance through its relay, retries the
+request with the payment, and answers {"status": "ok", "hash": ..., "body": ..., "httpStatus": ...}. The SDK holds no
+Gloam keys."""
+
+
+class Autonomo:
+    def __init__(
+        self,
+        private_key: Optional[str] = None,
+        pay_with: str = "auto",
+        per_call: Optional[dict] = None,
+        daily: Optional[dict] = None,
+        gloam_fetch_paid: Optional[GloamFetchPaid] = None,
+        borro_account: Optional[str] = None,
+        borro_mcp_url: str = BORRO_MCP,
+        spend_store: Optional[SpendStore] = None,
+        base_url: str = "https://autonomo.fun",
+        rpc_url: str = "https://rpc.mainnet.chain.robinhood.com",
+        http: Optional[httpx.Client] = None,
+    ):
+        key = (private_key or "").strip()
+        if key and not re.fullmatch(r"0x[0-9a-fA-F]{64}", key):
+            _fail("bad_key", "private_key should be 0x followed by 64 hex characters.")
+        self._key = key or None
+        self.address: Optional[str] = Account.from_key(key).address if key else None
+        if pay_with not in ("auto", "usdg", "autonomo"):
+            _fail("bad_option", 'pay_with should be "auto", "usdg" or "autonomo".')
+        self.pay_with = pay_with
+        pc = {**DEFAULT_PER_CALL, **(per_call or {})}
+        dl = {**DEFAULT_DAILY, **(daily or {})}
+        self.per_call = {t: _units(pc[t], TOKENS[t].decimals) for t in TOKENS}
+        self.daily = {t: _units(dl[t], TOKENS[t].decimals) for t in TOKENS}
+        self.gloam_fetch_paid = gloam_fetch_paid
+        self.borro_account = to_checksum_address(borro_account) if borro_account else None
+        self.borro_mcp_url = borro_mcp_url
+        self.store: SpendStore = spend_store or FileStore()
+        self.base = base_url.rstrip("/")
+        self.rpc_url = rpc_url
+        self.http = http or httpx.Client(timeout=30, follow_redirects=False)
+
+    # ----- Public -----
+
+    def find(self, query: str = "", input: Optional[str] = None) -> list[Api]:
+        """Every Autonomo API, or the best matches for a query and input. Free."""
+        res = self.http.get(f"{self.base}/api/v1/gateways", timeout=15)
+        if res.status_code == 503:
+            _fail("updating", "Autonomo is being updated right now. Try again in a few minutes.")
+        if res.status_code != 200:
+            _fail("http_error", f"/api/v1/gateways answered {res.status_code}.")
+        apis = [
+            Api(
+                slug=g["slug"],
+                name=g["name"],
+                description=g.get("description") or "",
+                path=g.get("usage") or "/",
+                price=g.get("price") or {},
+                verified=bool(g.get("verified")),
+                success_rate=(g.get("trackRecord") or {}).get("successRate"),
+                paid_calls_30d=(g.get("trackRecord") or {}).get("paidCalls") or 0,
+            )
+            for g in res.json()["data"]
+        ]
+        return rank_apis(apis, query, input) if (query or input is not None) else apis
+
+    def quote(self, query: str = "", input: Optional[str] = None, slug: Optional[str] = None, path: Optional[str] = None) -> dict:
+        """What a call would cost, without paying."""
+        api, url = self._resolve(query, input, slug, path)
+        required = self._price_list(url)
+        offers = []
+        for a in required["accepts"]:
+            t = _token_by_asset(a["asset"])
+            offers.append(
+                {
+                    "scheme": a["scheme"],
+                    "token": t.symbol if t else a["asset"],
+                    "amount": _fmt(int(a["amount"]), t.decimals if t else 18),
+                    "private": a["scheme"] == "gloam-cashout",
+                }
+            )
+        return {"api": api, "url": url, "offers": offers}
+
+    def call(
+        self,
+        query: str = "",
+        input: Optional[str] = None,
+        slug: Optional[str] = None,
+        path: Optional[str] = None,
+        private: bool = False,
+        pay_with: Optional[str] = None,
+    ) -> CallResult:
+        """Finds the right API, pays for one call and returns its answer with a receipt."""
+        if not private and not self._key:
+            _fail("no_wallet", "No wallet set. Pass private_key (a wallet just for this agent).")
+        api, url = self._resolve(query, input, slug, path)
+        required = self._price_list(url)
+        day = _today()
+        spent = self.store.get(day)
+
+        def within(token: Token, amount: int) -> Optional[str]:
+            price = f"{_fmt(amount, token.decimals)} {token.symbol}"
+            if amount > self.per_call[token.name]:
+                return f"{price} is above the per-call cap of {_fmt(self.per_call[token.name], token.decimals)} {token.symbol}"
+            so_far = spent.get(token.name, 0)
+            if so_far + amount > self.daily[token.name]:
+                return f"{price} would pass today's {token.symbol} budget ({_fmt(so_far, token.decimals)} of {_fmt(self.daily[token.name], token.decimals)} spent)"
+            return None
+
+        def finish(route: str, token: Token, amount: int, res: httpx.Response, tx: Optional[str], extra: dict) -> CallResult:
+            if res.status_code != 200:
+                reason = (_unb64(res.headers.get("payment-required")) or {}).get("error")
+                detail = ""
+                try:
+                    j = res.json()
+                    detail = j.get("message") or j.get("error") or ""
+                except Exception:
+                    pass
+                _fail(
+                    "payment_refused",
+                    f"Payment refused: {reason}" if reason else f"The API answered {res.status_code}{': ' + detail if detail else ''}. You aren't charged unless it settled.",
+                )
+            self.store.add(day, token.name, amount)
+            after = self.store.get(day).get(token.name, 0)
+            try:
+                data = res.json()
+            except Exception:
+                data = res.text
+            receipt = Receipt(
+                api={"slug": api.slug, "name": api.name},
+                url=url,
+                route=route,
+                amount=_fmt(amount, token.decimals),
+                token=token.symbol,
+                payer="private (Gloam)" if route == "gloam" else self.address,
+                pay_to=extra.get("pay_to", ""),
+                tx=tx,
+                explorer=f"{EXPLORER}/tx/{tx}" if tx else None,
+                borrow_txs=extra.get("borrow_txs", []),
+                approve_tx=extra.get("approve_tx"),
+                at=datetime.now(timezone.utc).isoformat(),
+                spent_today=f"{_fmt(after, token.decimals)} of {_fmt(self.daily[token.name], token.decimals)} {token.symbol}",
+            )
+            return CallResult(data=data, receipt=receipt)
+
+        # Private: Gloam only.
+        if private:
+            if not self.gloam_fetch_paid:
+                _fail("no_gloam", "private=True needs Gloam set up (gloam_fetch_paid=...).")
+            offer = next((a for a in required["accepts"] if a["scheme"] == "gloam-cashout"), None)
+            if not offer:
+                _fail("no_private_option", f"{api.name} doesn't offer private payment.")
+            amount = int(offer["amount"])
+            why = within(TOKENS["usdg"], amount)
+            if why:
+                _fail("over_limit", f"Not paid: {why}.")
+            # Gloam asks for its own quote, whose tag can differ by under 0.001 USDG; never more than the per-call cap.
+            most = min(amount + 1000, self.per_call["usdg"])
+            r = self.gloam_fetch_paid({"url": url, "maxAmount": float(_fmt(most, 6)), "prefer": "gloam-cashout"})
+            if r.get("status") == "paid_not_served":
+                self.store.add(day, "usdg", amount)
+                _fail(
+                    "paid_not_served",
+                    f"Paid through Gloam, but the API didn't answer yet: {r.get('message', '')} Retry gloam_fetch_paid with this paymentHeader, don't pay again: {r.get('paymentHeader')}",
+                )
+            if r.get("status") != "ok":
+                _fail("payment_refused", f"Gloam didn't pay: {r.get('message') or r.get('error') or r.get('code') or r.get('status')}")
+            res = httpx.Response(r.get("httpStatus") or 200, content=(r.get("body") or "").encode())
+            return finish("gloam", TOKENS["usdg"], amount, res, r.get("hash"), {"pay_to": to_checksum_address(offer["payTo"])})
+
+        # Public: the wallet's tokens, then Borro.
+        want = pay_with or self.pay_with
+        order = ["usdg", "autonomo"] if want == "auto" else [want]
+        reasons: list[str] = []
+        usdg_short: Optional[tuple[dict, int]] = None
+        for name in order:
+            token = TOKENS[name]
+            offer = next(
+                (a for a in required["accepts"] if a["scheme"] == "exact" and a["network"] == NETWORK and a["asset"].lower() == token.address.lower()),
+                None,
+            )
+            if not offer:
+                reasons.append(f"{api.name} doesn't take {token.symbol}")
+                continue
+            amount = int(offer["amount"])
+            why = within(token, amount)
+            if why:
+                reasons.append(why)
+                continue
+            balance = self._balance(token.address, self.address)
+            if balance < amount:
+                reasons.append(f"the wallet holds {_fmt(balance, token.decimals)} {token.symbol}, the call costs {_fmt(amount, token.decimals)}")
+                if name == "usdg":
+                    usdg_short = (offer, amount)
+                continue
+            res, tx, extra = self._pay_exact(url, required, offer)
+            return finish(name, token, amount, res, tx, extra)
+
+        if self.borro_account and usdg_short:
+            offer, amount = usdg_short
+            borrow_txs = self._borrow(url, offer)
+            res, tx, extra = self._pay_exact(url, required, offer)
+            extra["borrow_txs"] = [f"{EXPLORER}/tx/{h}" for h in borrow_txs]
+            return finish("borro", TOKENS["usdg"], amount, res, tx, extra)
+        _fail("cannot_pay", f"Not paid: {'; '.join(reasons)}.")
+
+    # ----- Internals -----
+
+    def _gateway_url(self, slug: str, path: str) -> str:
+        if not re.fullmatch(r"[a-z0-9][a-z0-9-]{0,63}", slug):
+            _fail("bad_slug", "slug should look like token-risk.")
+        p = path if path.startswith("/") else f"/{path}"
+        if ".." in p or p.startswith("//") or re.search(r"[\s\\<>]", p):
+            _fail("bad_path", f"The path {p} isn't a plain, filled-in path.")
+        url = f"{self.base}/x/{slug}{p}"
+        u, b = urlparse(url), urlparse(self.base)
+        if (u.scheme, u.netloc) != (b.scheme, b.netloc) or not (u.path == f"/x/{slug}" or u.path.startswith(f"/x/{slug}/")):
+            _fail("bad_path", "That path leaves the API.")
+        return url
+
+    def _resolve(self, query: str, input: Optional[str], slug: Optional[str], path: Optional[str]) -> tuple[Api, str]:
+        if slug:
+            api = next((a for a in self.find() if a.slug == slug), None)
+            if not api:
+                _fail("not_found", f"No Autonomo API called {slug}.")
+        else:
+            matches = self.find(query, input)
+            if not matches:
+                kind = _kind_of(input)
+                _fail("not_found", f'No Autonomo API matches "{query}"' + (f" for a {kind}" if kind and kind != "text" else "") + ". Use find() to see them all.")
+            api = matches[0]
+        return api, self._gateway_url(api.slug, path or _fill(api.path, input))
+
+    def _price_list(self, url: str) -> dict:
+        res = self.http.get(url, timeout=20)
+        required = _unb64(res.headers.get("payment-required"))
+        if not required and res.status_code == 402:
+            try:
+                required = res.json()
+            except Exception:
+                required = None
+        if res.status_code == 503:
+            _fail("updating", "This API is paused or being updated. Try again later.")
+        if res.status_code != 402 or not isinstance((required or {}).get("accepts"), list):
+            _fail("no_price", f"Expected a 402 price list from {url}, got {res.status_code}.")
+        return required
+
+    def _pay_exact(self, url: str, required: dict, offer: dict) -> tuple[httpx.Response, Optional[str], dict]:
+        """Signs an x402 exact payment (EIP-3009 for USDG, Permit2 for $AUTONOMO) and sends the request with it."""
+        now = int(time.time())
+        timeout = int(offer.get("maxTimeoutSeconds") or 300)
+        extra_in = offer.get("extra") or {}
+        approve_tx = None
+        if extra_in.get("assetTransferMethod") == "permit2":
+            if self._allowance(offer["asset"], self.address, PERMIT2) < int(offer["amount"]):
+                data = "0x095ea7b3" + _word(PERMIT2) + format(MAX_UINT256, "064x")
+                approve_tx = f"{EXPLORER}/tx/{self._send({'to': to_checksum_address(offer['asset']), 'data': data})}"
+            auth = {
+                "from": self.address,
+                "permitted": {"token": to_checksum_address(offer["asset"]), "amount": offer["amount"]},
+                "spender": PERMIT2_PROXY,
+                "nonce": str(int.from_bytes(secrets.token_bytes(32), "big")),
+                "deadline": str(now + timeout),
+                "witness": {"to": to_checksum_address(offer["payTo"]), "validAfter": "0"},
+            }
+            payload = {"signature": _sign_typed(self._key, permit2_typed_data(auth)), "permit2Authorization": auth}
+        else:
+            name, version = extra_in.get("name"), extra_in.get("version")
+            if not name or not version:
+                _fail("bad_offer", "The price list is missing the token's EIP-712 name and version.")
+            auth = {
+                "from": self.address,
+                "to": to_checksum_address(offer["payTo"]),
+                "value": offer["amount"],
+                "validAfter": "0",
+                "validBefore": str(now + timeout),
+                "nonce": "0x" + secrets.token_hex(32),
+            }
+            payload = {"authorization": auth, "signature": _sign_typed(self._key, eip3009_typed_data(auth, offer["asset"], name, version))}
+
+        if required.get("x402Version") == 1:
+            envelope = {"x402Version": 1, "scheme": offer["scheme"], "network": offer["network"], "payload": payload}
+            headers = {"X-PAYMENT": _b64(envelope)}
+        else:
+            envelope = {"x402Version": required["x402Version"], "payload": payload, "resource": required.get("resource"), "accepted": offer}
+            if required.get("extensions") is not None:
+                envelope["extensions"] = required["extensions"]
+            headers = {"PAYMENT-SIGNATURE": _b64(envelope)}
+        res = self.http.get(url, headers=headers, timeout=60)
+        settled = _unb64(res.headers.get("payment-response") or res.headers.get("x-payment-response")) or {}
+        return res, settled.get("transaction"), {"approve_tx": approve_tx, "pay_to": to_checksum_address(offer["payTo"])}
+
+    def _borrow(self, url: str, offer: dict) -> list[str]:
+        """Asks Borro for the borrow that covers what the wallet is short, sends it and waits for the USDG to land."""
+        required = self._price_list(url)
+        result = _mcp_call(
+            self.http,
+            self.borro_mcp_url,
+            "credit_bill",
+            {"wallet": self.address, "account": self.borro_account, "payment_required": _b64(required), "max_usdg": _fmt(self.per_call["usdg"], 6)},
+        )
+        hashes = [self._send(t) for t in find_transactions(result)]
+        need = int(offer["amount"])
+        for _ in range(20):
+            if self._balance(TOKENS["usdg"].address, self.address) >= need:
+                return hashes
+            time.sleep(1)
+        _fail("borrow_failed", "The borrowed USDG hasn't reached the wallet yet. Nothing was paid; try again shortly.")
+
+    # ----- Chain -----
+
+    def _rpc(self, method: str, params: list) -> Any:
+        res = self.http.post(self.rpc_url, json={"jsonrpc": "2.0", "id": 1, "method": method, "params": params}, timeout=20)
+        body = res.json()
+        if "error" in body:
+            _fail("rpc_error", f"{method}: {body['error'].get('message')}")
+        return body["result"]
+
+    def _balance(self, token: str, owner: str) -> int:
+        return int(self._rpc("eth_call", [{"to": token, "data": "0x70a08231" + _word(owner)}, "latest"]), 16)
+
+    def _allowance(self, token: str, owner: str, spender: str) -> int:
+        return int(self._rpc("eth_call", [{"to": token, "data": "0xdd62ed3e" + _word(owner) + _word(spender)}, "latest"]), 16)
+
+    def _send(self, tx: dict) -> str:
+        """Signs and sends a transaction from the wallet, waits for it, and returns its hash. Needs a little ETH for gas."""
+        value = int(tx.get("value") or 0, 0) if isinstance(tx.get("value"), str) else int(tx.get("value") or 0)
+        base = {"from": self.address, "to": to_checksum_address(tx["to"]), "data": tx["data"], "value": hex(value)}
+        gas = int(int(self._rpc("eth_estimateGas", [base]), 16) * 1.2)
+        signed = Account.sign_transaction(
+            {
+                "to": base["to"],
+                "data": tx["data"],
+                "value": value,
+                "gas": gas,
+                "gasPrice": int(self._rpc("eth_gasPrice", []), 16),
+                "nonce": int(self._rpc("eth_getTransactionCount", [self.address, "pending"]), 16),
+                "chainId": CHAIN_ID,
+            },
+            self._key,
+        )
+        h = self._rpc("eth_sendRawTransaction", ["0x" + bytes(signed.raw_transaction).hex()])
+        for _ in range(60):
+            r = self._rpc("eth_getTransactionReceipt", [h])
+            if r:
+                if r.get("status") != "0x1":
+                    _fail("tx_failed", f"Transaction failed: {EXPLORER}/tx/{h}")
+                return h
+            time.sleep(1)
+        _fail("tx_timeout", f"Transaction not confirmed yet: {EXPLORER}/tx/{h}")
+
+
+def _word(address: str) -> str:
+    return address.lower().replace("0x", "").rjust(64, "0")
+
+
+def _token_by_asset(asset: str) -> Optional[Token]:
+    return next((t for t in TOKENS.values() if t.address.lower() == asset.lower()), None)
+
+
+def _mcp_call(http: httpx.Client, url: str, name: str, args: dict) -> Any:
+    """Calls one tool on an MCP server over plain JSON-RPC and returns its result, parsed from JSON when it's JSON."""
+    res = http.post(
+        url,
+        json={"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": name, "arguments": args}},
+        headers={"accept": "application/json, text/event-stream"},
+        timeout=30,
+    )
+    text = res.text
+    if text.startswith("event:") or text.startswith("data:"):
+        text = "".join(line[5:] for line in text.splitlines() if line.startswith("data:"))
+    try:
+        body = json.loads(text)
+    except Exception:
+        _fail("borro_error", f"Borro answered {res.status_code}.")
+    if body.get("error"):
+        _fail("borro_error", f"Borro: {body['error'].get('message', 'error')}")
+    result = body.get("result") or {}
+    out = "".join(c.get("text", "") for c in result.get("content") or [])
+    if result.get("isError"):
+        _fail("borro_refused", f"Borro: {out}")
+    if result.get("structuredContent") is not None:
+        return result["structuredContent"]
+    try:
+        return json.loads(out)
+    except Exception:
+        return out

autonomo-0.1.0/tests/test_sdk.py

@@ -0,0 +1,173 @@
+"""Offline tests: no network, no wallet balance, no payments. Run with `pytest`."""
+
+import base64
+import json
+from datetime import datetime, timezone
+
+import httpx
+import pytest
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+from autonomo import Api, Autonomo, AutonomoError, MemoryStore, find_transactions, rank_apis
+from autonomo import eip3009_typed_data, permit2_typed_data
+
+KEY = "0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d"  # a throwaway test key
+USDG = "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168"
+AUTONOMO = "0xe83c85e1ead16fcfe85401e2b337fb4fb5b5cc96"
+PAY_TO = "0x00000000000000000000000000000000000000aa"
+ADDR = "0x86b57bcb9d249cf096cf8e21426c9dc9cafdec49"
+TX = "0x" + "ab" * 32
+
+APIS = [
+    ("token-price", "Token Price", "show live $autonomo token price", "/price/autonomo", 38),
+    ("new-launches", "New Launches", "Newest token launches on Robinhood Chain", "/launches?limit=10", 24),
+    ("token-risk", "Token Risk", "Rug-risk check for a launchpad token: holders, creator, safety score", "/risk/<token contract address>", 10),
+    ("token-lookup", "Token Lookup", "Price and market cap of any launchpad token", "/price/<token contract address>", 5),
+    ("tx-explainer", "Transaction Explainer", "Explains a transaction in plain words", "/tx/<transaction hash>", 3),
+    ("wallet-portfolio", "Wallet Portfolio", "What a wallet holds, with USD values", "/portfolio/<wallet address>", 3),
+    ("page-reader", "Page Reader", "Reads a web page and returns its text", "/page?url=<url-encoded https:// link>", 2),
+]
+API_OBJS = [Api(s, n, d, p, {}, True, 1.0, c) for s, n, d, p, c in APIS]
+
+
+def test_finds_the_right_api():
+    assert rank_apis(API_OBJS, "is this token a rug risk", ADDR)[0].slug == "token-risk"
+    assert rank_apis(API_OBJS, "token price", ADDR)[0].slug == "token-lookup"
+    assert rank_apis(API_OBJS, "what does this wallet hold", ADDR)[0].slug == "wallet-portfolio"
+    assert rank_apis(API_OBJS, "explain this transaction", TX)[0].slug == "tx-explainer"
+    assert rank_apis(API_OBJS, "read this page", "https://example.com/a?b=c")[0].slug == "page-reader"
+    assert rank_apis(API_OBJS, "newest launches")[0].slug == "new-launches"
+    assert rank_apis(API_OBJS, "explain this transaction", ADDR) == []
+
+
+def _recover(typed, sig):
+    msg = encode_typed_data(domain_data=typed["domain"], message_types=typed["types"], message_data=typed["message"])
+    return Account.recover_message(msg, signature=sig)
+
+
+def test_typed_data_recovers_to_the_wallet():
+    acct = Account.from_key(KEY)
+    usdg = eip3009_typed_data(
+        {"from": acct.address, "to": PAY_TO, "value": "10000", "validAfter": "0", "validBefore": "9999999999", "nonce": "0x" + "11" * 32}, USDG, "Global Dollar", "1"
+    )
+    sig = Account.sign_typed_data(KEY, domain_data=usdg["domain"], message_types=usdg["types"], message_data=usdg["message"]).signature
+    assert _recover(usdg, sig) == acct.address
+    p2 = permit2_typed_data(
+        {"permitted": {"token": AUTONOMO, "amount": "100"}, "spender": "0x402085c248EeA27D92E8b30b2C58ed07f9E20001", "nonce": "5", "deadline": "9999999999", "witness": {"to": PAY_TO, "validAfter": "0"}}
+    )
+    sig = Account.sign_typed_data(KEY, domain_data=p2["domain"], message_types=p2["types"], message_data=p2["message"]).signature
+    assert _recover(p2, sig) == acct.address
+
+
+def test_finds_borro_borrow_transaction():
+    result = {
+        "borrow": {"to": "0x1111111111111111111111111111111111111111", "data": "0xabcdef", "value": "0"},
+        "typed_data": {"message": {"from": "0x2222222222222222222222222222222222222222", "to": PAY_TO, "value": "10000"}},
+        "authorization": {"to": PAY_TO, "value": "10000"},
+    }
+    assert find_transactions(result) == [{"to": "0x1111111111111111111111111111111111111111", "data": "0xabcdef", "value": "0"}]
+
+
+def _exact(asset, amount, extra=None):
+    return {"scheme": "exact", "network": "eip155:4663", "asset": asset, "amount": amount, "payTo": PAY_TO, "maxTimeoutSeconds": 300, "extra": extra or {}}
+
+
+def _fake(accepts, on_paid=None):
+    sent = []
+
+    def handler(request: httpx.Request):
+        sent.append(request)
+        if request.url.path == "/api/v1/gateways":
+            data = [{"slug": s, "name": n, "description": d, "usage": p, "verified": True, "trackRecord": {"successRate": 1, "paidCalls": c}} for s, n, d, p, c in APIS]
+            return httpx.Response(200, json={"data": data})
+        if on_paid and (request.headers.get("x-payment") or request.headers.get("payment-signature")):
+            return on_paid(request)
+        required = {"x402Version": 2, "accepts": accepts, "resource": {"url": str(request.url)}}
+        return httpx.Response(402, json={}, headers={"payment-required": base64.b64encode(json.dumps(required).encode()).decode()})
+
+    return httpx.Client(transport=httpx.MockTransport(handler)), sent
+
+
+def test_refuses_over_the_per_call_cap_before_signing():
+    client, sent = _fake([_exact(USDG, "100000", {"name": "Global Dollar", "version": "1"})])  # 0.10 USDG
+    a = Autonomo(private_key=KEY, pay_with="usdg", http=client, spend_store=MemoryStore())
+    with pytest.raises(AutonomoError) as e:
+        a.call("newest launches")
+    assert e.value.code == "cannot_pay" and "per-call cap" in str(e.value)
+    assert not any(r.headers.get("payment-signature") for r in sent)
+
+
+def test_refuses_when_todays_budget_is_used():
+    store = MemoryStore()
+    store.add(datetime.now(timezone.utc).strftime("%Y-%m-%d"), "usdg", 995_000)
+    client, _ = _fake([_exact(USDG, "10000", {"name": "Global Dollar", "version": "1"})])
+    a = Autonomo(private_key=KEY, pay_with="usdg", http=client, spend_store=store)
+    with pytest.raises(AutonomoError) as e:
+        a.call("newest launches")
+    assert e.value.code == "cannot_pay" and "budget" in str(e.value)
+
+
+def test_private_never_falls_back_to_public():
+    client, _ = _fake([_exact(USDG, "10000", {"name": "Global Dollar", "version": "1"})])
+    a = Autonomo(private_key=KEY, http=client, spend_store=MemoryStore(), gloam_fetch_paid=lambda args: pytest.fail("no Gloam option"))
+    with pytest.raises(AutonomoError) as e:
+        a.call("newest launches", private=True)
+    assert e.value.code == "no_private_option"
+    b = Autonomo(private_key=KEY, http=client, spend_store=MemoryStore())
+    with pytest.raises(AutonomoError) as e:
+        b.call("newest launches", private=True)
+    assert e.value.code == "no_gloam"
+
+
+def test_pays_privately_through_gloam():
+    gloam = {"scheme": "gloam-cashout", "network": "eip155:4663", "asset": USDG, "amount": "10051", "payTo": PAY_TO, "extra": {"quoteId": "q1"}}
+    client, _ = _fake([_exact(USDG, "10000", {"name": "Global Dollar", "version": "1"}), gloam])
+    store = MemoryStore()
+    calls = []
+    h = "0x" + "cd" * 32
+
+    def fetch_paid(args):
+        calls.append(args)
+        return {"status": "ok", "hash": h, "httpStatus": 200, "body": json.dumps({"ok": True})}
+
+    a = Autonomo(http=client, spend_store=store, gloam_fetch_paid=fetch_paid)  # no wallet key needed
+    result = a.call("newest launches", private=True)
+    assert result.data == {"ok": True}
+    assert calls[0] == {"url": "https://autonomo.fun/x/new-launches/launches?limit=10", "maxAmount": 0.011051, "prefer": "gloam-cashout"}
+    r = result.receipt
+    assert (r.route, r.payer, r.amount, r.tx) == ("gloam", "private (Gloam)", "0.010051", h)
+    assert store.get(datetime.now(timezone.utc).strftime("%Y-%m-%d"))["usdg"] == 10051
+
+
+def test_gloam_refusal_pays_and_records_nothing():
+    gloam = {"scheme": "gloam-cashout", "network": "eip155:4663", "asset": USDG, "amount": "10051", "payTo": PAY_TO, "extra": {"quoteId": "q1"}}
+    client, _ = _fake([gloam])
+    store = MemoryStore()
+    a = Autonomo(private_key=KEY, http=client, spend_store=store, gloam_fetch_paid=lambda args: {"status": "refused", "code": "over_daily", "message": "over the daily limit"})
+    with pytest.raises(AutonomoError) as e:
+        a.call("newest launches", private=True)
+    assert e.value.code == "payment_refused" and "over the daily limit" in str(e.value)
+    assert store.get(datetime.now(timezone.utc).strftime("%Y-%m-%d")) == {}
+
+
+def test_signed_usdg_payment_header():
+    """The wallet has the USDG (faked), so the SDK signs and sends a PAYMENT-SIGNATURE header that recovers to it."""
+    seen = {}
+
+    def paid(request):
+        seen["env"] = json.loads(base64.b64decode(request.headers["payment-signature"]))
+        settled = base64.b64encode(json.dumps({"transaction": "0x" + "ef" * 32}).encode()).decode()
+        return httpx.Response(200, json={"ok": 1}, headers={"payment-response": settled})
+
+    client, _ = _fake([_exact(USDG, "10000", {"name": "Global Dollar", "version": "1"})], on_paid=paid)
+    a = Autonomo(private_key=KEY, pay_with="usdg", http=client, spend_store=MemoryStore())
+    a._balance = lambda token, owner: 10**9
+    result = a.call("newest launches")
+    env = seen["env"]
+    assert env["x402Version"] == 2 and env["accepted"]["amount"] == "10000" and "extensions" not in env
+    auth = env["payload"]["authorization"]
+    assert auth["from"] == a.address and auth["value"] == "10000"
+    typed = eip3009_typed_data(auth, USDG, "Global Dollar", "1")
+    assert _recover(typed, env["payload"]["signature"]) == a.address
+    assert result.receipt.route == "usdg" and result.receipt.tx == "0x" + "ef" * 32