usdf 0.1.2__py3-none-any.whl

usdf/client.py

@@ -0,0 +1,842 @@
+"""The client. Plain HTTP against the gateway's published endpoints; nothing here is computed that the
+gateway does not report, except the client-side estimates in ``usdf.estimate``, labelled as such."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Sequence, Union
+
+from ._http import Transport
+from .errors import USDFError
+from .sse import read_sse
+from .types import Account, ApiKey, Balance, ChatCompletion, CreatedKey, KeyLimits, Model, Pricing, Quote, Receipt, ReceiptLookup, X402Receipt
+from . import x402 as _x402
+from .x402 import CHAIN_ID, PaymentLimits, Signer, approve_permit2, check_accept, choose_accept, decode_payment_required, decode_payment_response, encode_payment_signature, known_asset, payment_limits, read_permit2_allowance, rpc_chain_id, sign_exact_payment, wallet_signer
+
+DEFAULT_BASE_URL = "https://api.usdf.fi"
+SDK_VERSION = "0.1.2"
+_UA = f"usdf-sdk-py/{SDK_VERSION}"
+_REQUEST_ID = __import__("re").compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+
+class ChatCompletionStream:
+    """A streamed completion: iterate the chunks (dicts in the OpenAI chunk shape); ``receipt`` is set
+    once the stream has been read to the end, from the gateway's final comment line. Stop early and it
+    stays None: the gateway bills what it produced and keeps the receipt under ``request_id``."""
+
+    def __init__(self, response, x402: bool = False):
+        self._res = response
+        self.x402 = x402
+        self.request_id: Optional[str] = response.headers.get("x-request-id")
+        self.receipt: Optional[Union[Receipt, X402Receipt]] = None
+        self.payment_response: Optional[Dict[str, Any]] = None
+        pr = response.headers.get("payment-response")
+        if pr:
+            try:
+                self.payment_response = decode_payment_response(pr)
+            except USDFError:
+                self.payment_response = None
+        # Set when the provider's stream ended before it closed the answer (stream_interrupted): what
+        # arrived is billed and the receipt still follows, status partial.
+        self.interrupted: Optional[Dict[str, Any]] = None
+        self._done = False
+
+    def __iter__(self) -> Iterator[Dict[str, Any]]:
+        if self._done:
+            raise RuntimeError("this stream has already been read")
+        self._done = True
+        error = None
+        finished = False
+        try:
+            for kind, payload in read_sse(self._res.chunks):
+                if kind == "comment":
+                    if payload.startswith("receipt "):
+                        try:
+                            d = json.loads(payload[8:])
+                            self.receipt = X402Receipt.of(d) if self.x402 else Receipt.of(d)
+                        except ValueError:
+                            pass
+                    continue
+                if payload == "[DONE]":
+                    finished = True
+                    break
+                try:
+                    obj = json.loads(payload)
+                except ValueError:
+                    continue
+                if isinstance(obj, dict) and isinstance(obj.get("error"), dict):
+                    error = obj["error"]
+                    if error.get("code") == "stream_interrupted":
+                        self.interrupted = error
+                    continue
+                yield obj
+            finished = True
+        finally:
+            try:
+                self._res.close()
+            except Exception:
+                pass
+        # An error with no receipt: nothing was produced and nothing charged (upstream_unavailable).
+        if error and self.receipt is None:
+            raise USDFError(502, str(error.get("message", "stream error")), str(error.get("type", "upstream_error")), error.get("code"), request_id=self.request_id)
+
+    def text(self) -> str:
+        """Reads the whole stream and returns the assistant text (content deltas joined)."""
+        out: List[str] = []
+        for chunk in self:
+            for c in chunk.get("choices") or []:
+                d = c.get("delta") or {}
+                if isinstance(d.get("content"), str):
+                    out.append(d["content"])
+        return "".join(out)
+
+
+@dataclass
+class RunResult:
+    """What ``USDF.run`` returns: the assistant's ``text`` and the gateway's ``receipt`` (as it returns
+    it: what was charged, or over x402 what was paid), the request ``id``, the whole completion when
+    the answer was not streamed, and over x402 the decoded PAYMENT-RESPONSE (``payment``)."""
+
+    text: str
+    receipt: Any  # Receipt, or X402Receipt over x402
+    id: str
+    completion: Optional[ChatCompletion] = None
+    payment: Optional[Dict[str, Any]] = None
+
+
+class _Chat:
+    def __init__(self, client: "USDF"):
+        self.completions = _Completions(client)
+
+
+class _Completions:
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def create(self, model: str, messages: Sequence[Mapping[str, Any]], *, stream: bool = False, timeout: Optional[float] = None, **params: Any) -> Union[ChatCompletion, ChatCompletionStream]:
+        """POST /v1/chat/completions. ``params`` are forwarded as sent (max_tokens, temperature, tools,
+        provider, stream_options, ...). With ``stream=True`` returns a ChatCompletionStream."""
+        body = {"model": model, "messages": list(messages), **params, "stream": stream}
+        if stream:
+            res = self._c._stream("POST", "/v1/chat/completions", body, auth="key", timeout=timeout)
+            return ChatCompletionStream(res)
+        out = self._c._json("POST", "/v1/chat/completions", body, auth="key", timeout=timeout)
+        if isinstance(out, dict) and out.get("object") == "batch.job":
+            raise USDFError(400, "this request was submitted as a batch job (a :batch model or batch=True); use batches.create to submit one and batches.wait to read it", "invalid_request_error", "batch_submitted", body=out)
+        return ChatCompletion.of(out)
+
+
+class _Receipts:
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def get(self, request_id: str) -> ReceiptLookup:
+        """GET /v1/receipts/{id}, with the key that made the request."""
+        if not _REQUEST_ID.match(request_id or ""):
+            raise USDFError(400, "not a request id", "invalid_request_error")
+        return ReceiptLookup.of(self._c._json("GET", f"/v1/receipts/{request_id}", auth="key"))
+
+    def list(self, **filters: Any) -> Dict[str, Any]:
+        """GET /v1/receipts: the latest receipts, newest first. With a key, that key's own requests; with
+        only a session, the account's. Filters: limit, before, model, status, from_, to, min_cost_units, key."""
+        return self._c._json("GET", "/v1/receipts" + _qs(filters), auth="any")
+
+    def attestation(self, request_id: str) -> Dict[str, Any]:
+        """GET /v1/privacy/receipts/{id}: the attested provider's signed receipt for a request served on
+        attested hardware (status pending, verified or failed)."""
+        if not _REQUEST_ID.match(request_id or ""):
+            raise USDFError(400, "not a request id", "invalid_request_error")
+        return self._c._json("GET", f"/v1/privacy/receipts/{request_id}", auth="key" if self._c.api_key else "none")
+
+
+class _Models:
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def list(self) -> List[Model]:
+        """GET /v1/models: what a key can call right now."""
+        return [Model.of(m) for m in self._c._json("GET", "/v1/models", auth="none").get("data") or []]
+
+
+class _Mcp:
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def call(self, name: str, arguments: Optional[Dict[str, Any]] = None, auth: str = "any") -> Dict[str, Any]:
+        """One of the gateway's MCP tools over Streamable HTTP; returns its structured result."""
+        c = self._c
+        headers = c._headers(auth)
+        headers["content-type"] = "application/json"
+        headers["accept"] = "application/json, text/event-stream"
+        body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": name, "arguments": arguments or {}}}).encode("utf-8")
+        res = c._transport.request("POST", f"{c.base_url}/mcp", headers, body, 120.0)
+        text = res.body.decode("utf-8", errors="replace")
+        msg = None
+        if "text/event-stream" in (res.headers.get("content-type") or ""):
+            for line in text.split("\n"):
+                if line.startswith("data: {"):
+                    msg = json.loads(line[6:])
+                    break
+        elif text:
+            msg = json.loads(text)
+        if res.status >= 400 or not msg:
+            raise USDFError(res.status, (msg or {}).get("error", {}).get("message", f"MCP answered {res.status}") if isinstance(msg, dict) else f"MCP answered {res.status}", "mcp_error", body=msg)
+        if msg.get("error"):
+            raise USDFError(400, str(msg["error"].get("message", "MCP error")), "mcp_error", str(msg["error"].get("code", "")), body=msg)
+        result = msg.get("result") or {}
+        if result.get("isError"):
+            env = None
+            try:
+                env = json.loads(((result.get("content") or [{}])[0] or {}).get("text") or "")
+            except ValueError:
+                env = None
+            if isinstance(env, dict) and isinstance(env.get("error"), dict):
+                raise USDFError(int(env.get("status") or 400), str(env["error"].get("message")), str(env["error"].get("type", "error")), env["error"].get("code"), body=env)
+            raise USDFError(400, str(((result.get("content") or [{}])[0] or {}).get("text") or "tool error"), "mcp_error", body=result)
+        return result.get("structuredContent") or {}
+
+
+class _Auth:
+    """Sign-in happens on the site (usdf.fi): pass its session token as ``session_token``. The gateway never
+    sees a password; email and password sign-in is retired."""
+
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def info(self) -> Dict[str, Any]:
+        """GET /v1/auth: which sign-in the site uses, how a session token is checked, and every account path."""
+        return self._c._json("GET", "/v1/auth", auth="none")
+
+    def sign_out(self) -> None:
+        """Ends this session at the gateway (DELETE /v1/session): it is refused from then on. The client
+        drops it either way."""
+        try:
+            self._c._request("DELETE", "/v1/session", auth="session")
+        finally:
+            self._c.session_token = None
+
+
+class _Keys:
+    """The account's keys on the gateway's own account endpoints, with the session (/v1/account/keys);
+    caps, the allowlist and the pause on /v1/keys/{id}."""
+
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def create(self, label: Optional[str] = None, budget_units: Optional[int] = None, rate_limit_rpm: int = 60) -> CreatedKey:
+        """POST /v1/account/keys: issues a key on the signed-in account; the key text is returned once.
+        ``budget_units`` is a lifetime spend limit in whole USDF base units (1 unit = $0.000001)."""
+        if budget_units is not None and budget_units < 0:
+            raise USDFError(400, "budget_units must be zero or more", "invalid_request_error")
+        body: Dict[str, Any] = {"rate_limit_rpm": rate_limit_rpm}
+        if label is not None:
+            body["label"] = label
+        if budget_units is not None:
+            body["budget_units"] = str(int(budget_units))
+        row = self._c._json("POST", "/v1/account/keys", body, auth="session")
+        if not isinstance(row, dict) or not row.get("api_key"):
+            raise USDFError(502, "the gateway returned no key; list the keys to see whether it was made", "server_error", body=row)
+        return CreatedKey(str(row["key_id"]), str(row["api_key"]), str(row.get("prefix")))
+
+    def list(self, revoked: bool = False, limit: int = 100) -> List[ApiKey]:
+        """GET /v1/account/keys: the account's active keys, or with ``revoked=True`` the revoked ones."""
+        q = _qs({"state": "revoked" if revoked else "active", "limit": min(max(limit, 1), 1000)})
+        page = self._c._json("GET", "/v1/account/keys" + q, auth="session")
+        return [ApiKey.of(r) for r in (page or {}).get("data") or []]
+
+    def revoke(self, key_id: str) -> bool:
+        """DELETE /v1/account/keys/{id}: True, or False when the account has no live key with that id."""
+        try:
+            r = self._c._json("DELETE", f"/v1/account/keys/{urllib.parse.quote(key_id, safe='')}", auth="session")
+        except USDFError as e:
+            if e.status == 404:
+                return False
+            raise
+        return isinstance(r, dict) and r.get("revoked") is True
+
+    def rotate(self, key_id: str) -> Dict[str, Any]:
+        """POST /v1/account/keys/{id}/rotate: a new key with the old one's label, scope and every control;
+        the old one is revoked in the same step. The new key is in the answer, once."""
+        return self._c._json("POST", f"/v1/account/keys/{urllib.parse.quote(key_id, safe='')}/rotate", {}, auth="session")
+
+    def limits(self, key_id: str) -> KeyLimits:
+        """GET /v1/keys/{id}/limits: trailing-window spend, caps, pause state, privacy, webhook."""
+        return KeyLimits.of(self._c._json("GET", f"/v1/keys/{key_id}/limits", auth="session"))
+
+    def update(self, key_id: str, **patch: Any) -> KeyLimits:
+        """PATCH /v1/keys/{id}: spend_limit_hour_units, spend_limit_day_units, spend_limit_month_units
+        (units, or None to clear), allowed_models (ids or prefixes ending in *; None allows every model),
+        paused, no_logs, private_tier, webhook_url. Unknown fields are refused by the gateway."""
+        body = {k: (str(v) if isinstance(v, int) and not isinstance(v, bool) and k.endswith("_units") else v) for k, v in patch.items()}
+        return KeyLimits.of(self._c._json("PATCH", f"/v1/keys/{key_id}", body, auth="session"))
+
+    def pause(self, key_id: str) -> KeyLimits:
+        return self.update(key_id, paused=True)
+
+    def resume(self, key_id: str) -> KeyLimits:
+        return self.update(key_id, paused=False)
+
+
+class _X402Completions:
+    def __init__(self, x: "X402"):
+        self._x = x
+
+    def create(
+        self,
+        model: str,
+        messages: Sequence[Mapping[str, Any]],
+        *,
+        signer: Optional[Signer] = None,
+        wallet: Any = None,
+        asset: Optional[str] = None,
+        approve: bool = False,
+        rpc_url: Optional[str] = None,
+        max_amount: Union[int, str, None] = None,
+        pay_to: Union[str, Sequence[str], None] = None,
+        stream: bool = False,
+        timeout: Optional[float] = None,
+        **params: Any,
+    ) -> Union[ChatCompletion, ChatCompletionStream]:
+        """Pays for and runs one completion with no account. The payer is ``wallet`` (an eth-account
+        account or a private key) or ``signer``. ``asset`` is "USDF" (Permit2) or "USDG" (EIP-3009); by
+        default USDF when its Permit2 allowance covers the amount, else USDG. The allowance is read through
+        ``rpc_url`` (default USDF_RPC_URL, else the chain's public RPC). ``approve=True`` sends the
+        one-time USDF approval instead. ``max_amount`` (base units; default USDF_MAX_AMOUNT, else 1 USDF)
+        and ``pay_to`` (default USDF_PAY_TO, else the payee the gateway names: ``X402.payees``) bound what is
+        signed: a 402 asking for more, for another payee, on another chain or in another token is refused."""
+        x = self._x
+        if signer is None:
+            if wallet is None:
+                raise USDFError(400, "x402 needs a payer: pass wallet= (an eth-account account) or signer=", "invalid_request_error")
+            signer = wallet_signer(wallet)
+        limits = payment_limits(max_amount, pay_to)
+        body = {"model": model, "messages": list(messages), **params, "stream": stream}
+        required = x.quote(model, messages, **params)["required"]
+        # The payee(s) resolved once for this 402, then held: the accept and the signature both answer to them.
+        limits = x.payees(required, limits)
+        accept = x.choose(required, signer, wallet=wallet, asset=asset, approve=approve, rpc_url=rpc_url, limits=limits)
+        payload = sign_exact_payment(required, accept, signer, limits=limits)
+        headers = {"payment-signature": encode_payment_signature(payload)}
+        if stream:
+            res = x._c._stream("POST", "/x402/v1/chat/completions", body, auth="none", timeout=timeout, extra_headers=headers)
+            return ChatCompletionStream(res, x402=True)
+        res = x._c._request("POST", "/x402/v1/chat/completions", body, auth="none", timeout=timeout, extra_headers=headers)
+        out = ChatCompletion.of(res.json() or {}, x402=True)
+        pr = res.headers.get("payment-response")
+        out.raw["payment_response"] = decode_payment_response(pr) if pr else None
+        return out
+
+
+class X402:
+    """Pay per request with no account. ``quote`` returns the 402 (amount, accepted assets); ``chat``
+    pays and runs. Any object with ``address`` and ``sign_typed_data`` is a signer."""
+
+    def __init__(self, client: "USDF"):
+        self._c = client
+        self.chat = _Chat.__new__(_Chat)
+        self.chat.completions = _X402Completions(self)
+        # eth_chainId per RPC URL, asked once.
+        self._chains: Dict[str, int] = {}
+        # The payee(s) the gateway's GET /v1/config published, and when they were read.
+        self._published: Optional[Any] = None
+
+    def quote(self, model: str, messages: Sequence[Mapping[str, Any]], **params: Any) -> Dict[str, Any]:
+        """The 402 for this request: ``quote`` (amount, accepted), ``x402`` and the decoded ``required``."""
+        body = {"model": model, "messages": list(messages), **params, "stream": False}
+        headers = self._c._headers("none")
+        headers["content-type"] = "application/json"
+        res = self._c._transport.request("POST", f"{self._c.base_url}/x402/v1/chat/completions", headers, json.dumps(body).encode("utf-8"), self._c.timeout)
+        j = res.json()
+        if res.status != 402 or not isinstance(j, dict):
+            raise USDFError.from_response(res.status, j, res.headers)
+        header = res.headers.get("payment-required")
+        j["required"] = decode_payment_required(header) if header else j.get("x402")
+        return j
+
+    def read_rpc(self, rpc_url: Optional[str] = None) -> Optional[str]:
+        """Where the allowance is read: ``rpc_url`` (default USDF_RPC_URL, else the chain's public RPC),
+        refused unless it answers for chain 4663. None when it cannot be reached (the allowance is then
+        unknown)."""
+        url = rpc_url or self._c.rpc_url or _x402.PUBLIC_RPC_URL
+        if url not in self._chains:
+            try:
+                self._chains[url] = rpc_chain_id(url)
+            except Exception:
+                return None
+        if self._chains[url] != CHAIN_ID:
+            raise USDFError(402, f"the RPC at {url} answers for chain {self._chains[url]}, not Robinhood Chain ({CHAIN_ID}); the allowance is read on {CHAIN_ID} only", "payment_refused", "wrong_chain")
+        return url
+
+    def gateway_payees(self) -> List[str]:
+        """The payee(s) the gateway publishes at GATEWAY_CONFIG_URL (never the base URL's: a server there that
+        is not the gateway would vouch for itself), kept PAYEE_TTL_SECONDS; [] when it does not answer."""
+        now = time.monotonic()
+        if self._published is not None and now - self._published[0] <= _x402.PAYEE_TTL_SECONDS:
+            return list(self._published[1])
+        payees: List[str] = []
+        try:
+            res = self._c._transport.request("GET", _x402.GATEWAY_CONFIG_URL, {"accept": "application/json", "user-agent": _UA}, None, 10.0)
+            if 200 <= res.status < 300:
+                payees = _x402.published_payees(res.json())
+        except Exception:
+            payees = []
+        self._published = (now, payees) if payees else None
+        return payees
+
+    def payees(self, required: Dict[str, Any], limits: Optional[PaymentLimits] = None) -> PaymentLimits:
+        """The limits a payment for this 402 is held to. The caller's payees when pinned (``pay_to=``,
+        USDF_PAY_TO). Otherwise the payee the gateway names: a 402 from the gateway itself (GATEWAY_ORIGIN)
+        names it; from any other base URL, a payee in the 402 is taken when GATEWAY_CONFIG_URL publishes it too,
+        or when it is GATEWAY_PAYEE (the last resort, so a 402 naming it reads nothing more). The hot wallet the
+        2026-10-26 rotation retired is paid only while the gateway names it: until the flip."""
+        limits = limits or payment_limits()
+        if limits.pinned:
+            return limits
+        named = _x402.named_payees(required)
+        if _x402.is_gateway_origin(self._c.base_url):
+            return _x402.with_gateway_payees(limits, named)
+        if all(a in limits.pay_to for a in named):
+            return limits
+        return _x402.with_gateway_payees(limits, self.gateway_payees())
+
+    def choose(self, required: Dict[str, Any], signer: Signer, *, wallet: Any = None, asset: Optional[str] = None, approve: bool = False, rpc_url: Optional[str] = None, limits: Optional[PaymentLimits] = None) -> Dict[str, Any]:
+        """The accept this payer pays, after the allowance check (and the approval, when asked for). Every
+        accept is held to ``check_accept`` (under ``payees``) before anything is read, approved or signed."""
+        limits = self.payees(required, limits)
+        exact = [a for a in required.get("accepts") or [] if isinstance(a, dict) and a.get("scheme") == "exact"]
+        usdf = next((a for a in exact if known_asset(a) == "USDF"), None)
+        usdg = next((a for a in exact if known_asset(a) == "USDG"), None)
+        read: Dict[str, Optional[str]] = {}
+
+        def allowance_of(a: Dict[str, Any]) -> Optional[int]:
+            if "url" not in read:
+                read["url"] = self.read_rpc(rpc_url)
+            if read["url"] is None:
+                return None
+            try:
+                return read_permit2_allowance(read["url"], a["asset"], signer.address)
+            except Exception:
+                return None
+
+        if asset:
+            accept = choose_accept(required, asset)
+        elif usdf is not None:
+            check_accept(usdf, limits)
+            allowance = allowance_of(usdf)
+            accept = usdf if allowance is None or allowance >= int(usdf["amount"]) or approve or usdg is None else usdg
+        else:
+            accept = choose_accept(required)
+        check_accept(accept, limits)
+        if known_asset(accept) == "USDF" and approve and wallet is not None:
+            allowance = allowance_of(accept)
+            if allowance is not None and allowance < int(accept["amount"]):
+                approve_permit2(wallet, read["url"], accept["asset"])  # type: ignore[arg-type]
+        return accept
+
+
+# ── Batch tier, embeddings, account, links, zap, agents ──────────────────────
+
+
+def _units(v: Any) -> Any:
+    return None if v is None else str(int(v))
+
+
+def _qs(params: Mapping[str, Any]) -> str:
+    out = {}
+    for k, v in params.items():
+        if v is None or v == "":
+            continue
+        k = k.rstrip("_")  # from_ -> from
+        out[k] = str(int(v)) if k.endswith("_units") else ("true" if v is True else "false" if v is False else str(v))
+    return ("?" + urllib.parse.urlencode(out)) if out else ""
+
+
+def _units_of(d: Mapping[str, Any]) -> Dict[str, Any]:
+    return {k: (_units(v) if k.endswith("_units") else v) for k, v in d.items()}
+
+
+class _Batches:
+    """The batch tier: a request run through the upstream's batch API at its batch rate, billed when the
+    result arrives (models whose price carries batch_input)."""
+
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def create(self, model: str, messages: Sequence[Mapping[str, Any]], *, webhook_url: Optional[str] = None, **params: Any) -> Dict[str, Any]:
+        """Submits the request as a job; returns the job (``id``, ``status``, ``hold``, ``price``)."""
+        body = {"model": model, "messages": list(messages), **params, "batch": True, "stream": False}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        return self._c._json("POST", "/v1/chat/completions", body, auth="key")
+
+    def get(self, job_id: str) -> Dict[str, Any]:
+        return self._c._json("GET", f"/v1/batches/{urllib.parse.quote(job_id, safe='')}", auth="key")
+
+    def result(self, job_id: str) -> ChatCompletion:
+        return ChatCompletion.of(self._c._json("GET", f"/v1/batches/{urllib.parse.quote(job_id, safe='')}/result", auth="key"))
+
+    def wait(self, job_id: str, *, interval: float = 5.0, timeout: float = 25 * 3600.0) -> ChatCompletion:
+        """Polls until the job ends and returns its result; a failed or expired job raises."""
+        deadline = time.time() + timeout
+        while True:
+            job = self.get(job_id)
+            status = job.get("status")
+            if status == "done":
+                return self.result(job_id)
+            if status in ("failed", "expired"):
+                raise USDFError(409, f"batch job {job_id} {status}{': ' + str(job.get('error')) if job.get('error') else ''}; nothing was charged", "invalid_request_error", f"batch_{status}", body=job)
+            if time.time() > deadline:
+                raise USDFError(408, f"batch job {job_id} is still {status}", "timeout", "batch_pending", body=job)
+            time.sleep(interval)
+
+
+class _Embeddings:
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def create(self, model: str, input: Union[str, Sequence[str]], **params: Any) -> Dict[str, Any]:
+        """POST /v1/embeddings: the OpenAI embeddings list with the gateway's receipt."""
+        return self._c._json("POST", "/v1/embeddings", {"model": model, "input": input if isinstance(input, str) else list(input), **params}, auth="key")
+
+
+class _Account:
+    """The signed-in owner's reads and settings (a session)."""
+
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def get(self) -> Account:
+        """GET /v1/account: balance, held, linked wallet, deposit address."""
+        return Account.of(self._c._json("GET", "/v1/account", auth="session"))
+
+    def overview(self) -> Dict[str, Any]:
+        """GET /v1/account/overview: balance, spend today / 7 / 30 days, top models, last deposit and withdrawal, receipt counts."""
+        return self._c._json("GET", "/v1/account/overview", auth="session")
+
+    def activity(self, **filters: Any) -> Dict[str, Any]:
+        """GET /v1/account/activity: the account's requests, newest first. Filters: key, model, status,
+        from_, to, min_cost_units, before, limit."""
+        return self._c._json("GET", "/v1/account/activity" + _qs(filters), auth="session")
+
+    def activity_csv(self, **filters: Any) -> str:
+        return self._c._request("GET", "/v1/account/activity.csv" + _qs(filters), auth="session").body.decode("utf-8")
+
+    def settings(self) -> Dict[str, Any]:
+        return self._c._json("GET", "/v1/account/settings", auth="session")
+
+    def update_settings(self, **patch: Any) -> Dict[str, Any]:
+        """PATCH /v1/account/settings: zdr, data_collection, no_logs_default, private_tier_default, sort,
+        provider_allow, provider_deny, allow_fallbacks, max_price, low_balance_units, low_balance_webhook_url, solana_address."""
+        return self._c._json("PATCH", "/v1/account/settings", _units_of(patch), auth="session")
+
+    def analytics(self, days: Optional[int] = None, key: Optional[str] = None) -> Dict[str, Any]:
+        return self._c._json("GET", "/v1/analytics" + _qs({"days": days, "key": key}), auth="any")
+
+    def withdraw(self, units: int, chain_id: Optional[int] = None) -> Dict[str, Any]:
+        """POST /v1/account/withdrawals: sends available USDF to the linked wallet. ``units`` in USDF base
+        units, at least 100000 (0.10 USDF); ``chain_id`` for another chain the account is served on."""
+        body: Dict[str, Any] = {"units": str(int(units))}
+        if chain_id is not None:
+            body["chain_id"] = int(chain_id)
+        return self._c._json("POST", "/v1/account/withdrawals", body, auth="session")
+
+
+class _Links:
+    """USDF links: an amount set aside behind a claim token, claimed by the first signed-in account to present it."""
+
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def create(self, units: int, memo: Optional[str] = None, expires_in_days: Optional[int] = None) -> Dict[str, Any]:
+        """POST /v1/links (session): at least 10000 units (0.01 USDF); the token is in the answer, once."""
+        body: Dict[str, Any] = {"units": str(int(units))}
+        if memo is not None:
+            body["memo"] = memo
+        if expires_in_days is not None:
+            body["expires_in_days"] = expires_in_days
+        return self._c._json("POST", "/v1/links", body, auth="session")
+
+    def list(self) -> Dict[str, Any]:
+        return self._c._json("GET", "/v1/links", auth="any")
+
+    def get(self, token: str) -> Dict[str, Any]:
+        """The public view of one link: amount, memo, status; never who sent or claimed it."""
+        return self._c._json("GET", f"/v1/links/{urllib.parse.quote(token, safe='')}", auth="none")
+
+    def claim(self, token: str) -> Dict[str, Any]:
+        return self._c._json("POST", f"/v1/links/{urllib.parse.quote(token, safe='')}/claim", {}, auth="session")
+
+    def cancel(self, link_id: str) -> Dict[str, Any]:
+        return self._c._json("POST", f"/v1/links/{urllib.parse.quote(link_id, safe='')}/cancel", {}, auth="session")
+
+
+class _Zap:
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def quote(self, token: str, amount: int, recipient: Optional[str] = None, slippage_bps: Optional[int] = None) -> Dict[str, Any]:
+        """GET /v1/zap/quote: ETH ("eth") or an ERC-20 with a Uniswap pool against USDG, swapped and
+        wrapped into USDF for ``recipient``, with the transactions to send. No key."""
+        return self._c._json("GET", "/v1/zap/quote" + _qs({"token": token, "amount": str(int(amount)), "recipient": recipient, "slippage_bps": slippage_bps}), auth="none")
+
+
+class _Pool:
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def read(self) -> Dict[str, Any]:
+        """GET /v1/pool: the USDF/USDG pool's price, tick, whether it sits in the seeded band, and its
+        liquidity and USDF/USDG reserves while the gateway publishes them (absent otherwise). Public, no key."""
+        return self._c._json("GET", "/v1/pool", auth="none")
+
+
+class _Agents:
+    """Agents with a ledger account of their own: created and funded by the owner, paying each other."""
+
+    def __init__(self, client: "USDF"):
+        self._c = client
+
+    def _read_auth(self) -> str:
+        return "any" if (self._c.session_token or self._c.api_key) else "none"
+
+    def create(self, slug: str, name: str, **policy: Any) -> Dict[str, Any]:
+        return self._c._json("POST", "/v1/agents", _units_of({"slug": slug, "name": name, **policy}), auth="session")
+
+    def list(self) -> Dict[str, Any]:
+        return self._c._json("GET", "/v1/agents?mine=1", auth="session")
+
+    def get(self, slug: str) -> Dict[str, Any]:
+        return self._c._json("GET", f"/v1/agents/{urllib.parse.quote(slug, safe='')}", auth=self._read_auth())
+
+    def update(self, slug: str, **policy: Any) -> Dict[str, Any]:
+        """PATCH /v1/agents/{slug}: allowed_models, allowed_tools, max_request_units, spend_limit_*_units,
+        approval_threshold_units, webhook_url, public_page, identity_opt_in."""
+        return self._c._json("PATCH", f"/v1/agents/{urllib.parse.quote(slug, safe='')}", _units_of(policy), auth="session")
+
+    def fund(self, slug: str, units: int, direction: Optional[str] = None, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"units": str(int(units))}
+        if direction:
+            body["direction"] = direction
+        return self._c._json("POST", f"/v1/agents/{urllib.parse.quote(slug, safe='')}/fund", body, auth="session", extra_headers={"idempotency-key": idempotency_key} if idempotency_key else None)
+
+    def pay(self, slug: str, to: str, units: int, memo: Optional[str] = None, idempotency_key: Optional[str] = None) -> Dict[str, Any]:
+        """The agent pays another agent (by slug) or an account: with the agent's key, or the owner's session."""
+        body: Dict[str, Any] = {"to": to, "units": str(int(units))}
+        if memo is not None:
+            body["memo"] = memo
+        return self._c._json("POST", f"/v1/agents/{urllib.parse.quote(slug, safe='')}/pay", body, auth="any", extra_headers={"idempotency-key": idempotency_key} if idempotency_key else None)
+
+    def payments(self, slug: str) -> Dict[str, Any]:
+        return self._c._json("GET", f"/v1/agents/{urllib.parse.quote(slug, safe='')}/payments", auth=self._read_auth())
+
+    def rotate_key(self, slug: str) -> Dict[str, Any]:
+        return self._c._json("POST", f"/v1/agents/{urllib.parse.quote(slug, safe='')}/key", {}, auth="session")
+
+
+
+def _env(name: str) -> Optional[str]:
+    v = os.environ.get(name)
+    return v if v else None
+
+
+class USDF:
+    """``USDF(api_key=...)`` pays from a prepaid balance; ``USDF(wallet=...)`` pays each request over
+    x402 with no account (an eth-account account or a private key). ``session_token`` is the token of a
+    session signed in on the site (usdf.fi), for the account's own calls: keys, links, agents, the
+    dashboard. Everything a key can do needs only the key. ``base_url`` is the gateway
+    origin without /v1. Unset, ``api_key``, ``base_url``, ``session_token`` and ``rpc_url`` come from
+    USDF_API_KEY (not read when a wallet is given), USDF_BASE_URL, USDF_SESSION_TOKEN and USDF_RPC_URL
+    (else the chain's public RPC). Over x402, ``max_amount`` (base units; USDF_MAX_AMOUNT, else 1 USDF)
+    caps one payment and ``pay_to`` (USDF_PAY_TO, else the gateway's hot wallet) names the payee; a 402
+    asking for more, for another payee, on another chain or in another token is refused before signing."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        wallet: Any = None,
+        session_token: Optional[str] = None,
+        base_url: Optional[str] = None,
+        asset: Optional[str] = None,
+        approve: bool = False,
+        rpc_url: Optional[str] = None,
+        max_amount: Union[int, str, None] = None,
+        pay_to: Union[str, Sequence[str], None] = None,
+        timeout: float = 15 * 60.0,
+        transport: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ):
+        self.base_url = (base_url or _env("USDF_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.wallet = wallet
+        self.api_key = api_key if api_key is not None else (None if wallet is not None else _env("USDF_API_KEY"))
+        self.session_token = session_token if session_token is not None else _env("USDF_SESSION_TOKEN")
+        self.asset = asset
+        self.approve = approve
+        self.rpc_url = rpc_url or _env("USDF_RPC_URL")
+        # Checked (and USDF_MAX_AMOUNT / USDF_PAY_TO read) when a payment is made: x402.payment_limits.
+        self.max_amount = max_amount
+        self.pay_to = pay_to
+        self.timeout = timeout
+        self._extra = dict(headers or {})
+        self._transport = Transport(transport)
+        self.chat = _Chat(self)
+        self.receipts = _Receipts(self)
+        self.models = _Models(self)
+        self.mcp = _Mcp(self)
+        self.auth = _Auth(self)
+        self.keys = _Keys(self)
+        self.x402 = X402(self)
+        self.batches = _Batches(self)
+        self.embeddings = _Embeddings(self)
+        self.account = _Account(self)
+        self.links = _Links(self)
+        self.zap = _Zap(self)
+        self.pool = _Pool(self)
+        self.agents = _Agents(self)
+
+    @property
+    def transport(self) -> str:
+        return self._transport.name
+
+    @property
+    def pays_with(self) -> Optional[str]:
+        """How a request is paid: "key" (prepaid), "wallet" (x402), or None."""
+        return "key" if self.api_key else "wallet" if self.wallet is not None else None
+
+    def _pay_kwargs(self) -> Dict[str, Any]:
+        """What an x402 payment from this client's wallet is made with."""
+        return {"wallet": self.wallet, "asset": self.asset, "approve": self.approve, "rpc_url": self.rpc_url, "max_amount": self.max_amount, "pay_to": self.pay_to}
+
+    # ── The short path ────────────────────────────────────────────────────────
+
+    def run(
+        self,
+        model: str,
+        prompt: Union[str, Sequence[Mapping[str, Any]]],
+        *,
+        max_tokens: Optional[int] = None,
+        system: Optional[str] = None,
+        temperature: Optional[float] = None,
+        provider: Optional[Mapping[str, Any]] = None,
+        on_text: Optional[Callable[[str], None]] = None,
+        **params: Any,
+    ) -> RunResult:
+        """One prompt, one answer: ``.text`` and ``.receipt``. With an API key the request is charged to the
+        prepaid balance; with a wallet it is paid per request over x402. ``prompt`` is the text, or the
+        whole message list. ``on_text`` streams the answer, called with each piece as it arrives."""
+        if isinstance(prompt, str):
+            messages: List[Mapping[str, Any]] = ([{"role": "system", "content": system}] if system else []) + [{"role": "user", "content": prompt}]
+        else:
+            messages = list(prompt)
+        if max_tokens is not None:
+            params["max_tokens"] = max_tokens
+        if temperature is not None:
+            params["temperature"] = temperature
+        if provider is not None:
+            params["provider"] = dict(provider)
+        stream = on_text is not None
+        if self.api_key:
+            out = self.chat.completions.create(model, messages, stream=stream, **params)
+        elif self.wallet is not None:
+            out = self.x402.chat.completions.create(model, messages, stream=stream, **self._pay_kwargs(), **params)
+        else:
+            raise USDFError(401, "run needs an API key (USDF(api_key=...) or USDF_API_KEY) or a wallet to pay per request (USDF(wallet=...))", "authentication_error", "invalid_api_key")
+        if isinstance(out, ChatCompletionStream):
+            pieces: List[str] = []
+            for chunk in out:
+                for c in chunk.get("choices") or []:
+                    d = (c.get("delta") or {}).get("content")
+                    if isinstance(d, str) and d:
+                        pieces.append(d)
+                        on_text(d)  # type: ignore[misc]
+            if out.receipt is None:
+                raise USDFError(502, "the stream ended without a receipt; look it up with receipts.get", "upstream_error", request_id=out.request_id)
+            return RunResult("".join(pieces), out.receipt, out.request_id or out.receipt.request_id, None, out.payment_response)
+        return RunResult(out.content or "", out.receipt, out.id, out, out.raw.get("payment_response"))
+
+    # ── Transport ─────────────────────────────────────────────────────────────
+
+    def _bearer(self, auth: str) -> Optional[str]:
+        if auth == "none":
+            return None
+        if auth == "key":
+            if not self.api_key:
+                raise USDFError(401, "an API key is required for this call (USDF(api_key='sk_...') or USDF_API_KEY)", "authentication_error", "invalid_api_key")
+            return self.api_key
+        if auth == "session":
+            if not self.session_token:
+                raise USDFError(401, "an account session is required for this call: sign in at usdf.fi and pass its session token (USDF(session_token=...) or USDF_SESSION_TOKEN)", "authentication_error", "unauthenticated")
+            return self.session_token
+        return self.api_key or self.session_token
+
+    def _headers(self, auth: str, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+        h = {"accept": "application/json", "user-agent": _UA, **self._extra, **(extra or {})}
+        token = self._bearer(auth)
+        if token:
+            h["authorization"] = f"Bearer {token}"
+        return h
+
+    def _request(self, method: str, path: str, body: Any = None, *, auth: str = "none", timeout: Optional[float] = None, extra_headers: Optional[Mapping[str, str]] = None):
+        headers = self._headers(auth, extra_headers)
+        data = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        res = self._transport.request(method, f"{self.base_url}{path}", headers, data, timeout or self.timeout)
+        if res.status >= 400:
+            raise USDFError.from_response(res.status, res.json(), res.headers)
+        return res
+
+    def _json(self, method: str, path: str, body: Any = None, *, auth: str = "none", timeout: Optional[float] = None, extra_headers: Optional[Mapping[str, str]] = None) -> Any:
+        return self._request(method, path, body, auth=auth, timeout=timeout, extra_headers=extra_headers).json()
+
+    def _stream(self, method: str, path: str, body: Any, *, auth: str, timeout: Optional[float], extra_headers: Optional[Mapping[str, str]] = None):
+        headers = self._headers(auth, extra_headers)
+        headers["accept"] = "text/event-stream"
+        headers["content-type"] = "application/json"
+        # A stream may run for up to an hour; the caller's timeout bounds it.
+        res = self._transport.stream(method, f"{self.base_url}{path}", headers, json.dumps(body).encode("utf-8"), timeout or 60 * 60.0)
+        if res.status >= 400:
+            data = b"".join(res.chunks)
+            try:
+                res.close()
+            except Exception:
+                pass
+            try:
+                j = json.loads(data.decode("utf-8"))
+            except ValueError:
+                j = None
+            raise USDFError.from_response(res.status, j, res.headers)
+        return res
+
+    # ── Public reads ──────────────────────────────────────────────────────────
+
+    def pricing(self) -> Pricing:
+        """GET /v1/pricing: the price sheet in force, with routes and data policy per route."""
+        return Pricing.of(self._json("GET", "/v1/pricing"))
+
+    def tools(self) -> Dict[str, Any]:
+        """GET /v1/tools."""
+        return self._json("GET", "/v1/tools")
+
+    # ── MCP tools ─────────────────────────────────────────────────────────────
+
+    def quote(self, model: str, prompt: Optional[str] = None, messages: Optional[Sequence[Mapping[str, Any]]] = None, max_tokens: Optional[int] = None) -> Quote:
+        """The hold the gateway would place for this request, and the x402 amount. No key needed.
+        Over MCP the output is capped at 4096 tokens; for more, estimate with ``usdf.estimate``."""
+        args: Dict[str, Any] = {"model": model}
+        if prompt is not None:
+            args["prompt"] = prompt
+        if messages:
+            args["messages"] = list(messages)
+        if max_tokens is not None:
+            args["max_tokens"] = max_tokens
+        return Quote.of(self.mcp.call("quote", args, auth="any"))
+
+    def balance(self) -> Balance:
+        """What the key can spend (MCP ``balance``)."""
+        return Balance.of(self.mcp.call("balance", {}, auth="key"))