oneshot-python 0.25.0__tar.gz → 0.26.0__tar.gz

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.25.0
+Version: 0.26.0
 Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 43 tools
 License-Expression: MIT
 Requires-Python: >=3.10

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/README.md

@@ -66,6 +66,31 @@ Read endpoints (inbox, SMS inbox, notifications, balance, browser profiles) retu
 
 This is automatic — no extra code beyond `private_key`. **Requires `oneshot-python >= 0.17.0`.** Older versions keep working until the API enables enforcement, after which they must send a valid `x-agent-proof`.
 
+## Access tokens (credits-only sessions)
+
+Some code can't hold your wallet key — a hosted MCP client such as Grok Bot, a cloud
+runner, a third-party agent platform. Mint an **access token** from a wallet session and
+hand that over instead:
+
+```python
+# From a wallet session (once):
+created = client.create_access_token(name="grok-bot")   # created["token"] is shown once
+
+# In the hosted environment:
+hosted = OneShotClient.create(access_token=created["token"])  # resolves the wallet address
+hosted.call_tool("/v1/tools/search", {"query": "…"})           # billed to the agent's credits
+```
+
+An access-token session identifies the agent with the token (no `x-agent-proof`), **pays
+every call from the agent's prepaid credit balance**, and never signs x402. When credits
+can't cover a call it raises `InsufficientCreditsError` (`required`, `balance`,
+`shortfall`) — top up and retry. Budgets set on the agent still apply, with credit-funded
+spend counted; they are **read-only** from a token session (`get_budgets()` works, passing
+`budgets`/`alert_email` raises). A token cannot mint, list, or revoke tokens; do that from
+the wallet session (`list_access_tokens()`, `revoke_access_token(id)`). `access_token` is
+exclusive with `private_key`. Pass `address=` to skip the lookup, and use `acreate` /
+`acreate_access_token` inside `asyncio` programs. **Requires `oneshot-python >= 0.26.0`.**
+
 ## Spend Budgets
 
 Cap what the agent can spend so a runaway loop can't drain the wallet overnight:

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/oneshot/__init__.py

@@ -7,6 +7,7 @@ from oneshot._errors import (
     BudgetSyncError,
     ContentBlockedError,
     EmergencyNumberError,
+    InsufficientCreditsError,
     JobError,
     JobTimeoutError,
     OneShotError,
@@ -15,6 +16,8 @@ from oneshot._errors import (
     ValidationError,
 )
 from oneshot._types import (
+    AccessTokenCreated,
+    AccessTokenInfo,
     AgentBudgetConfig,
     AgentBudgetStatus,
     ComputeBudgetStatus,
@@ -48,7 +51,10 @@ __all__ = [
     "ValidationError",
     "ContentBlockedError",
     "EmergencyNumberError",
+    "InsufficientCreditsError",
     "sign_payment_authorization",
+    "AccessTokenCreated",
+    "AccessTokenInfo",
     "AgentBudgetConfig",
     "AgentBudgetStatus",
     "ComputeSchedule",

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/oneshot/_errors.py

@@ -115,6 +115,28 @@ class BudgetExceededError(OneShotError):
         self.resets_at = resets_at
 
 
+class InsufficientCreditsError(OneShotError):
+    """An access-token (credits-only) session asked for a paid call the agent's
+    prepaid credit balance cannot cover. Nothing was charged; top up credits
+    and retry, or use a wallet session. ``required``, ``balance`` and
+    ``shortfall`` are USDC amounts when the API reported them.
+
+    Mirrors ``InsufficientCreditsError`` in ``libs/agent-sdk/src/errors.ts``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        required: float | None = None,
+        balance: float | None = None,
+        shortfall: float | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.required = required
+        self.balance = balance
+        self.shortfall = shortfall
+
+
 class BudgetSyncError(OneShotError):
     """The configured spend budget could not be confirmed with the server, so
     the paid call was NOT made.

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/oneshot/_types.py

@@ -267,3 +267,27 @@ class AgentBudgetStatus(TypedDict):
     remaining_usdc: Optional[str]
     pct_used: Optional[float]
     resets_at: str
+
+
+class AccessTokenCreated(TypedDict):
+    """Response of ``POST /v1/agents/me/access-tokens``. Mirrors ``AccessTokenCreated`` in TS.
+    ``token`` is shown exactly once and never stored server-side."""
+
+    id: str
+    token: str
+    token_prefix: str
+    name: Optional[str]
+    created_at: str
+
+
+class AccessTokenInfo(TypedDict):
+    """One row of ``GET /v1/agents/me/access-tokens``. Mirrors ``AccessTokenInfo`` in TS."""
+
+    id: str
+    token_prefix: str
+    name: Optional[str]
+    source: str
+    last_used_at: Optional[str]
+    created_at: str
+    revoked_at: Optional[str]
+    spent_today_usdc: str

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/oneshot/client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import asyncio
 import math
 import json
+import re
 import time
 from decimal import Decimal
 from typing import Any, Optional
@@ -17,12 +18,14 @@ from urllib.parse import quote
 
 import httpx
 from eth_account import Account
+from eth_utils import to_checksum_address
 
 from oneshot._errors import (
     BudgetExceededError,
     BudgetSyncError,
     ContentBlockedError,
     EmergencyNumberError,
+    InsufficientCreditsError,
     JobError,
     JobTimeoutError,
     OneShotError,
@@ -31,6 +34,8 @@ from oneshot._errors import (
     ValidationError,
 )
 from oneshot._types import (
+    AccessTokenCreated,
+    AccessTokenInfo,
     AgentBudgetConfig,
     AgentBudgetStatus,
     DomainPoolListResult,
@@ -51,13 +56,15 @@ try:
 
     SDK_VERSION = _pkg_version("oneshot-python")
 except Exception:  # pragma: no cover - editable/source runs without dist metadata
-    SDK_VERSION = "0.25.0"
+    SDK_VERSION = "0.26.0"
 
 # ---------------------------------------------------------------------------
 # Environment configuration
 # ---------------------------------------------------------------------------
 
 _BASE_URL = "https://win.oneshotagent.com"
+# Agent access token (credits-only session), see OneShotClient(access_token=...).
+_ACCESS_TOKEN_RE = re.compile(r"^oneshot_[0-9a-f]{64}$")
 _CHAIN_ID = 8453
 _USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
 
@@ -161,6 +168,36 @@ def _parse_budget_rejection(resp: Any) -> Optional[BudgetExceededError]:
     )
 
 
+def _parse_insufficient_credits(resp: Any) -> Optional[InsufficientCreditsError]:
+    """Map a 402 ``insufficient_credits`` body onto :class:`InsufficientCreditsError`.
+
+    Access-token sessions pay from the agent's prepaid credits and never sign
+    x402, so a shortfall is a distinct, actionable failure ("top up") rather
+    than a payment rejection. Returns None for any other response.
+    """
+    if resp.status_code != 402:
+        return None
+    try:
+        data = resp.json()
+    except Exception:  # noqa: BLE001 - non-JSON body
+        return None
+    if not isinstance(data, dict) or data.get("error") != "insufficient_credits":
+        return None
+
+    def _num(v: Any) -> float | None:
+        try:
+            return float(v) if v is not None else None
+        except (TypeError, ValueError):
+            return None
+
+    return InsufficientCreditsError(
+        data.get("message") or "Credit balance does not cover this call",
+        required=_num(data.get("required_usdc")),
+        balance=_num(data.get("credits_balance")),
+        shortfall=_num(data.get("shortfall_usdc")),
+    )
+
+
 def _parse_payment_rejection(resp: Any) -> Optional[PaymentError]:
     """Build a ``PaymentError`` from a 402 that names its own cause.
 
@@ -284,13 +321,28 @@ class OneShotClient:
 
     def __init__(
         self,
-        private_key: str,
+        private_key: Optional[str] = None,
         *,
+        access_token: Optional[str] = None,
+        address: Optional[str] = None,
         base_url: Optional[str] = None,
         debug: bool = False,
         budgets: Optional[AgentBudgetConfig] = None,
         alert_email: Optional[str] = None,
     ) -> None:
+        """Two session kinds, mirroring the TypeScript SDK:
+
+        * **Wallet session** — ``private_key``: signs x402 payments and read
+          proofs; may set budgets and mint access tokens.
+        * **Access-token session** — ``access_token`` (``oneshot_<64 hex>``) plus
+          the agent's ``address`` (or use :meth:`create` / :meth:`acreate` to
+          resolve it from the API): identifies the agent with the token, pays
+          every call from the agent's prepaid credit balance, never signs; a
+          shortfall raises :class:`InsufficientCreditsError`. Budgets and alerts
+          are read-only in this mode, and a token cannot mint, list or revoke
+          tokens. Meant for agents that run in someone else's cloud (hosted MCP,
+          Grok Bot, runners) where a wallet key must never live.
+        """
         self.base_url = base_url or _BASE_URL
         self.chain_id: int = _CHAIN_ID
         self.usdc_address: str = _USDC_ADDRESS
@@ -304,9 +356,120 @@ class OneShotClient:
         self._budget_synced = False
         self._budget_sync_lock: Optional[asyncio.Lock] = None
 
+        self._access_token: Optional[str] = None
+        if access_token is not None:
+            if not _ACCESS_TOKEN_RE.match(access_token):
+                raise ValidationError("access_token must be oneshot_<64 lowercase hex characters>", "access_token")
+            if private_key:
+                raise ValidationError("access_token cannot be combined with private_key", "access_token")
+            if budgets or alert_email:
+                raise ValidationError(
+                    "budgets and alerts are read-only for access-token sessions; set them from a wallet session or the API",
+                    "budgets",
+                )
+            if not address:
+                raise ValidationError(
+                    "address is required with access_token in the constructor; use OneShotClient.create() to resolve it",
+                    "address",
+                )
+            try:
+                checksummed = to_checksum_address(address)
+            except Exception:  # noqa: BLE001
+                raise ValidationError("address must be a valid Ethereum address", "address") from None
+            self._access_token = access_token
+            self._private_key: Optional[str] = None
+            self.address: str = checksummed
+            return
+        if not private_key:
+            raise ValidationError("private_key is required (or pass access_token for a credits-only session)", "private_key")
         self._private_key = private_key
         acct = Account.from_key(private_key)
-        self.address: str = acct.address
+        self.address = acct.address
+
+    @property
+    def is_access_token_session(self) -> bool:
+        """True when this session authenticates with an agent access token (credits-only)."""
+        return self._access_token is not None
+
+    @classmethod
+    async def acreate(
+        cls,
+        *,
+        access_token: str,
+        address: Optional[str] = None,
+        base_url: Optional[str] = None,
+        debug: bool = False,
+    ) -> "OneShotClient":
+        """Build an access-token session, resolving the agent's wallet address
+        from ``GET /v1/agents/me`` when it is not supplied (the API keys job
+        status on ``X-Agent-ID``, so the session needs the address even though
+        it never signs with it)."""
+        if address:
+            return cls(access_token=access_token, address=address, base_url=base_url, debug=debug)
+        if not _ACCESS_TOKEN_RE.match(access_token or ""):
+            raise ValidationError("access_token must be oneshot_<64 lowercase hex characters>", "access_token")
+        url = f"{base_url or _BASE_URL}/v1/agents/me"
+        headers = {"Authorization": f"Bearer {access_token}", "X-OneShot-SDK-Version": SDK_VERSION}
+        try:
+            async with httpx.AsyncClient(timeout=httpx.Timeout(10.0)) as client:
+                resp = await client.get(url, headers=headers)
+        except Exception as e:  # noqa: BLE001
+            raise ToolError("Could not resolve the access token's agent", 0, str(e)) from e
+        if resp.status_code != 200:
+            raise ToolError("Could not resolve the access token's agent", resp.status_code, resp.text)
+        body = resp.json() if resp.text else {}
+        data = body.get("data") if isinstance(body, dict) else None
+        wallet = (data or {}).get("wallet_address") if isinstance(data, dict) else None
+        if not isinstance(wallet, str) or not wallet:
+            raise ToolError("Access token lookup returned no wallet address", resp.status_code, resp.text)
+        return cls(access_token=access_token, address=wallet, base_url=base_url, debug=debug)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        access_token: str,
+        address: Optional[str] = None,
+        base_url: Optional[str] = None,
+        debug: bool = False,
+    ) -> "OneShotClient":
+        """Blocking wrapper for :meth:`acreate`."""
+        return asyncio.get_event_loop().run_until_complete(
+            cls.acreate(access_token=access_token, address=address, base_url=base_url, debug=debug)
+        )
+
+    def _assert_wallet_session(self, action: str) -> None:
+        if self._access_token is not None:
+            raise ValidationError(f"Access tokens cannot {action}; use a wallet session", "access_token")
+
+    # ------------------------------------------------------------------
+    # Access tokens (wallet sessions only)
+    # ------------------------------------------------------------------
+
+    async def acreate_access_token(self, name: Optional[str] = None) -> AccessTokenCreated:
+        """Mint a delegated, revocable credential for a hosted/cloud agent.
+        The token is returned once and never stored server-side."""
+        self._assert_wallet_session("mint access tokens")
+        return self._unwrap_data(await self.acall_free_post("/v1/agents/me/access-tokens", {"name": name} if name else {}, scope="write"))
+
+    def create_access_token(self, name: Optional[str] = None) -> AccessTokenCreated:
+        return asyncio.get_event_loop().run_until_complete(self.acreate_access_token(name))
+
+    async def alist_access_tokens(self, *, active_only: bool = False) -> list[AccessTokenInfo]:
+        self._assert_wallet_session("list access tokens")
+        path = "/v1/agents/me/access-tokens" + ("?active=true" if active_only else "")
+        data = self._unwrap_data(await self.acall_free_get(path))
+        return data.get("tokens", data) if isinstance(data, dict) else data
+
+    def list_access_tokens(self, *, active_only: bool = False) -> list[AccessTokenInfo]:
+        return asyncio.get_event_loop().run_until_complete(self.alist_access_tokens(active_only=active_only))
+
+    async def arevoke_access_token(self, token_id: str) -> None:
+        self._assert_wallet_session("revoke access tokens")
+        await self.acall_free_delete(f"/v1/agents/me/access-tokens/{quote(token_id, safe='')}", scope="write")
+
+    def revoke_access_token(self, token_id: str) -> None:
+        asyncio.get_event_loop().run_until_complete(self.arevoke_access_token(token_id))
 
     # ------------------------------------------------------------------
     # Headers
@@ -328,6 +491,10 @@ class OneShotClient:
         # in depth.
         if max_cost is not None and max_cost > 0:
             headers["X-Max-Cost-USDC"] = str(max_cost)
+        # Access-token session: the bearer binds the request to the agent (and
+        # is revocable); the API accepts it in place of the signed proof.
+        if self._access_token:
+            headers["Authorization"] = f"Bearer {self._access_token}"
         return headers
 
     @property
@@ -344,6 +511,8 @@ class OneShotClient:
         server runs log-only until read-proof enforcement is enabled).
         Free MUTATION routes (e.g. LinkedIn connect/revoke) require scope="write"."""
         headers = self._headers()
+        if self._access_token:
+            return headers
         try:
             headers["x-agent-proof"] = sign_read_proof(self._private_key, self.address, scope=scope)
         except Exception as e:  # noqa: BLE001
@@ -356,6 +525,8 @@ class OneShotClient:
         those routes outright — there is no log-only fallback — so a signing
         failure here is surfaced rather than swallowed."""
         headers = self._headers()
+        if self._access_token:
+            return headers
         headers["x-agent-proof"] = sign_read_proof(self._private_key, self.address, scope="write")
         return headers
 
@@ -622,6 +793,12 @@ class OneShotClient:
                 return result.get("data", result)
 
             # Step 2 — Parse 402 response
+            if self._access_token:
+                # A credits-only session may get a bare insufficient_credits
+                # 402 with no quote attached; that is final, nothing to parse.
+                shortfall = _parse_insufficient_credits(resp)
+                if shortfall is not None:
+                    raise shortfall
             # Parse x402 v2 PaymentRequired from PAYMENT-REQUIRED header
             parsed_req = parse_payment_required(
                 resp.headers.get("payment-required")
@@ -647,6 +824,37 @@ class OneShotClient:
 
             self._log(f"Payment required: {payment_request['amount']} USDC")
 
+            if self._access_token:
+                # Credits-only session: never sign. Let the server settle the
+                # quote from credits on one retry (no payment-signature).
+                if not quote_id:
+                    amount_str = payment_request.get("amount")
+                    raise InsufficientCreditsError(
+                        f"Credits do not cover ${amount_str}; top up credits or use a wallet session"
+                        if amount_str else "Credits do not cover this call; top up credits or use a wallet session",
+                        required=float(amount_str) if amount_str else None,
+                    )
+                headers = self._headers(max_cost=max_cost, idempotency_key=idempotency_key)
+                headers["x-quote-id"] = quote_id
+                resp2 = await client.post(url, headers=headers, json=payload)
+                if resp2.status_code not in (200, 201, 202):
+                    shortfall = _parse_insufficient_credits(resp2)
+                    if shortfall is not None:
+                        raise shortfall
+                    budget_rejection = _parse_budget_rejection(resp2)
+                    if budget_rejection is not None:
+                        raise budget_rejection
+                    raise ToolError("Credits do not cover this call", resp2.status_code, resp2.text)
+                result = resp2.json()
+                if isinstance(result, dict) and result.get("request_id") and result.get("status") in ("pending", "processing"):
+                    if not wait:
+                        return {"request_id": result["request_id"], "status": result["status"]}
+                    return await self._poll_job(
+                        client, result["request_id"], timeout_sec,
+                        wait_for_phones=wait_for_phones, phone_timeout_sec=phone_timeout_sec,
+                    )
+                return result.get("data", result)
+
             # Step 3 — Sign x402 payment (zero-cost auth if credits cover full cost)
             charge = _resolve_charge_amount(accepted, payment_request)
             self._assert_within_budget(charge)
@@ -695,6 +903,9 @@ class OneShotClient:
                 # A 402 here means the facilitator refused the signature — not
                 # the ordinary quote-pay 402 handled above. The API names the
                 # cause, so raise the specific error rather than a generic one.
+                shortfall = _parse_insufficient_credits(resp2)
+                if shortfall is not None:
+                    raise shortfall
                 rejection = _parse_payment_rejection(resp2)
                 if rejection is not None:
                     raise rejection
@@ -1058,6 +1269,26 @@ class OneShotClient:
             f"/v1/compute/{goal_id}/fund", {"amount": amount}
         )
 
+    # ------------------------------------------------------------------
+    # Credits
+    # ------------------------------------------------------------------
+
+    async def atop_up_credits(self, amount: float) -> Any:
+        """Add prepaid credits by paying the same amount in USDC via x402
+        (``POST /v1/credits/top-up``). Wallet sessions only: credits are what
+        access-token sessions spend from, so a token session raises before any
+        request. Returns ``{"topped_up", "credits_balance", "transaction_id",
+        "settlement_tx", "already_credited"}``."""
+        if getattr(self, "_access_token", None):
+            raise ValidationError("Access tokens cannot top up credits; use a wallet session", "access_token")
+        if isinstance(amount, bool) or not isinstance(amount, (int, float)) or not math.isfinite(amount) or amount <= 0:
+            raise ValidationError("amount must be a positive number", "amount")
+        return await self.acall_tool("/v1/credits/top-up", {"amount": amount, "memo": "credit top-up"})
+
+    def top_up_credits(self, amount: float) -> Any:
+        """Blocking wrapper for :meth:`atop_up_credits`."""
+        return asyncio.get_event_loop().run_until_complete(self.atop_up_credits(amount))
+
     # ------------------------------------------------------------------
     # Browser
     # ------------------------------------------------------------------

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/oneshot/physical_mail.py

@@ -55,7 +55,8 @@ class PhysicalMail:
         scope = 'read' if method == 'GET' else 'submit' if path == '/send' else 'write'
         def headers() -> dict[str, str]:
             h = c._headers(max_cost=max_cost)
-            h['x-agent-proof'] = sign_read_proof(c._private_key, c.address, scope=scope)
+            if not getattr(c, '_access_token', None):
+                h['x-agent-proof'] = sign_read_proof(c._private_key, c.address, scope=scope)
             if key:
                 h['Idempotency-Key'] = key
             if mime:
@@ -67,7 +68,19 @@ class PhysicalMail:
             kwargs = {'content': body} if mime else {'json': body}
             url = f'{c.base_url}/v1/tools/physical-mail{path}'
             response = await transport.request(method, url, headers=headers(), **kwargs)
-            if response.status_code == 402 and path == '/send':
+            if response.status_code == 402 and path == '/send' and getattr(c, '_access_token', None):
+                # Credits-only session: never sign. The quote is on the order,
+                # so one retry lets the server settle it from credits.
+                from oneshot.client import _parse_insufficient_credits
+                shortfall = _parse_insufficient_credits(response)
+                if shortfall is not None:
+                    raise shortfall
+                response = await transport.post(url, headers=headers(), json=body)
+                if response.status_code == 402:
+                    shortfall = _parse_insufficient_credits(response)
+                    if shortfall is not None:
+                        raise shortfall
+            elif response.status_code == 402 and path == '/send':
                 parsed = parse_payment_required(response.headers.get('payment-required'))
                 accepted = parsed['accepted']
                 payment = response.json()['payment_request']

{oneshot_python-0.25.0 → oneshot_python-0.26.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oneshot-python"
-version = "0.25.0"
+version = "0.26.0"
 description = "Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 43 tools"
 readme = {text = "Core Python SDK for the OneShot API", content-type = "text/plain"}
 license = "MIT"

oneshot_python-0.26.0/tests/test_access_token.py

@@ -0,0 +1,298 @@
+"""Access-token (credits-only) sessions — parity with
+``tests/unit/sdk-access-token-mode.test.ts`` in the TypeScript SDK.
+
+A token session identifies the agent with ``Authorization: Bearer oneshot_…``,
+sends no ``x-agent-proof``, never signs x402, raises ``InsufficientCreditsError``
+on a shortfall, keeps budgets read-only, and cannot mint/list/revoke tokens.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+
+from oneshot import (
+    BudgetExceededError,
+    InsufficientCreditsError,
+    OneShotClient,
+    ToolError,
+    ValidationError,
+)
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+TOKEN = "oneshot_" + "ab" * 32
+WALLET = "0x1234567890123456789012345678901234567890"
+BASE = "http://test.local"
+
+
+@pytest.fixture(autouse=True)
+def _fresh_event_loop():
+    """Sync wrappers use ``get_event_loop().run_until_complete``; pytest-asyncio
+    closes loops between async tests, so give every test a fresh one."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    yield
+    loop.close()
+    # Leave an OPEN loop behind: this module sorts first, and later modules'
+    # sync wrappers call get_event_loop().run_until_complete on the current one.
+    asyncio.set_event_loop(asyncio.new_event_loop())
+
+
+class _Resp:
+    def __init__(self, status_code: int, body: Any = None, headers: dict[str, str] | None = None) -> None:
+        self.status_code = status_code
+        self._body = body if body is not None else {}
+        self.headers = headers or {}
+        self.text = json.dumps(self._body)
+        self.is_success = 200 <= status_code < 300
+
+    def json(self) -> Any:
+        return self._body
+
+    def raise_for_status(self) -> None:
+        if not self.is_success:
+            raise ToolError("http error", self.status_code, self.text)
+
+
+class _FakeAsyncClient:
+    """An httpx.AsyncClient stand-in that records every request and replays
+    the queued responses in order."""
+
+    def __init__(self, responses: list[_Resp]) -> None:
+        self.calls: list[dict[str, Any]] = []
+        self._queue = list(responses)
+
+    async def _send(self, method: str, url: str, **kw: Any) -> _Resp:
+        self.calls.append({"method": method, "url": url, "headers": {k.lower(): v for k, v in (kw.get("headers") or {}).items()}, "json": kw.get("json")})
+        return self._queue.pop(0)
+
+    async def post(self, url: str, **kw: Any) -> _Resp:
+        return await self._send("POST", url, **kw)
+
+    async def get(self, url: str, **kw: Any) -> _Resp:
+        return await self._send("GET", url, **kw)
+
+    async def delete(self, url: str, **kw: Any) -> _Resp:
+        return await self._send("DELETE", url, **kw)
+
+    async def __aenter__(self) -> "_FakeAsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        return None
+
+
+def _client_mock(responses: list[_Resp]):
+    client = _FakeAsyncClient(responses)
+    return client, client.calls
+
+
+def _token_client(**kw: Any) -> OneShotClient:
+    return OneShotClient(access_token=TOKEN, address=WALLET, base_url=BASE, **kw)
+
+
+# ---------------------------------------------------------------- constructor
+
+def test_rejects_malformed_token():
+    with pytest.raises(ValidationError, match="oneshot_<64 lowercase hex"):
+        OneShotClient(access_token="oneshot_nothex", address=WALLET)
+
+
+def test_token_is_exclusive_with_private_key():
+    with pytest.raises(ValidationError, match="cannot be combined with private_key"):
+        OneShotClient(TEST_PRIVATE_KEY, access_token=TOKEN, address=WALLET)
+
+
+def test_budgets_and_alerts_are_read_only():
+    with pytest.raises(ValidationError, match="read-only"):
+        OneShotClient(access_token=TOKEN, address=WALLET, budgets={"daily": 5})
+    with pytest.raises(ValidationError, match="read-only"):
+        OneShotClient(access_token=TOKEN, address=WALLET, alert_email="a@b.c")
+
+
+def test_address_required_and_validated():
+    with pytest.raises(ValidationError, match="address is required"):
+        OneShotClient(access_token=TOKEN)
+    with pytest.raises(ValidationError, match="valid Ethereum address"):
+        OneShotClient(access_token=TOKEN, address="0xnope")
+
+
+def test_valid_token_session_and_wallet_session_flags():
+    c = _token_client()
+    assert c.address.lower() == WALLET.lower()
+    assert c.is_access_token_session is True
+    w = OneShotClient(TEST_PRIVATE_KEY)
+    assert w.is_access_token_session is False
+
+
+def test_private_key_still_required_for_wallet_sessions():
+    with pytest.raises(ValidationError, match="private_key is required"):
+        OneShotClient()
+
+
+# ---------------------------------------------------------------- create()
+
+@pytest.mark.asyncio
+async def test_acreate_resolves_wallet_from_agents_me():
+    client, calls = _client_mock([_Resp(200, {"success": True, "data": {"agent_id": "x", "wallet_address": WALLET, "auth_mode": "access_token"}})])
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        c = await OneShotClient.acreate(access_token=TOKEN, base_url=BASE)
+    assert c.address.lower() == WALLET.lower()
+    assert calls[0]["method"] == "GET" and calls[0]["url"] == f"{BASE}/v1/agents/me"
+    assert calls[0]["headers"]["authorization"] == f"Bearer {TOKEN}"
+
+
+@pytest.mark.asyncio
+async def test_acreate_skips_lookup_when_address_given():
+    client, calls = _client_mock([])
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        c = await OneShotClient.acreate(access_token=TOKEN, address=WALLET, base_url=BASE)
+    assert c.is_access_token_session and calls == []
+
+
+@pytest.mark.asyncio
+async def test_acreate_surfaces_revoked_token():
+    client, _ = _client_mock([_Resp(401, {"error": "access_token_revoked"})])
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        with pytest.raises(ToolError) as ei:
+            await OneShotClient.acreate(access_token=TOKEN, base_url=BASE)
+    assert ei.value.status_code == 401
+
+
+def test_create_sync_wrapper():
+    client, _ = _client_mock([_Resp(200, {"data": {"wallet_address": WALLET}})])
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        c = OneShotClient.create(access_token=TOKEN, base_url=BASE)
+    assert c.address.lower() == WALLET.lower()
+
+
+# ---------------------------------------------------------------- headers
+
+def test_headers_carry_bearer_and_no_proof():
+    c = _token_client()
+    h = c._headers()
+    assert h["Authorization"] == f"Bearer {TOKEN}"
+    assert h["X-Agent-ID"].lower() == WALLET.lower()
+    assert "x-agent-proof" not in c._read_headers()
+    assert "x-agent-proof" not in c._write_headers()
+    assert c._read_headers()["Authorization"] == f"Bearer {TOKEN}"
+
+
+def test_wallet_session_headers_unchanged():
+    w = OneShotClient(TEST_PRIVATE_KEY)
+    assert "Authorization" not in w._headers()
+    assert "x-agent-proof" in w._write_headers()
+
+
+# ---------------------------------------------------------------- paid calls
+
+@pytest.mark.asyncio
+async def test_covered_fixed_price_call_is_a_single_unsigned_post():
+    client, calls = _client_mock([_Resp(200, {"data": {"results": []}})])
+    c = _token_client()
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        out = await c.acall_tool("/v1/tools/search", {"query": "x", "memo": "t"})
+    assert out == {"results": []}
+    assert len(calls) == 1
+    assert "payment-signature" not in calls[0]["headers"]
+    assert calls[0]["headers"]["authorization"] == f"Bearer {TOKEN}"
+
+
+@pytest.mark.asyncio
+async def test_insufficient_credits_is_typed_and_never_retried():
+    body = {"error": "insufficient_credits", "message": "short", "required_usdc": "0.010000", "credits_balance": "0.002500", "shortfall_usdc": "0.007500"}
+    client, calls = _client_mock([_Resp(402, body, {"payment-required": ""})])
+    c = _token_client()
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client), patch("oneshot.client.parse_payment_required", return_value={"accepted": {}}):
+        with pytest.raises(InsufficientCreditsError) as ei:
+            await c.acall_tool("/v1/tools/search", {"query": "x", "memo": "t"})
+    assert (ei.value.required, ei.value.balance, ei.value.shortfall) == (0.01, 0.0025, 0.0075)
+    assert len(calls) == 1
+
+
+@pytest.mark.asyncio
+async def test_quote_flow_retries_once_with_quote_id_and_no_signature():
+    quote_402 = _Resp(402, {"payment_request": {"amount": "5", "recipient": "0x0", "token_address": "0x0", "chain_id": 8453}, "context": {"quote_id": "q-1"}}, {"payment-required": ""})
+    client, calls = _client_mock([quote_402, _Resp(200, {"data": {"funded": True}})])
+    c = _token_client()
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client), patch("oneshot.client.parse_payment_required", return_value={"accepted": {}}):
+        out = await c.acall_tool("/v1/compute/g1/fund", {"amount": 5, "memo": "t"})
+    assert out == {"funded": True}
+    assert len(calls) == 2
+    assert "x-quote-id" not in calls[0]["headers"]
+    assert calls[1]["headers"]["x-quote-id"] == "q-1"
+    assert "payment-signature" not in calls[1]["headers"]
+    assert calls[1]["headers"]["authorization"] == f"Bearer {TOKEN}"
+
+
+@pytest.mark.asyncio
+async def test_quote_retry_shortfall_is_typed():
+    quote_402 = _Resp(402, {"payment_request": {"amount": "5"}, "context": {"quote_id": "q-1"}}, {"payment-required": ""})
+    short = _Resp(402, {"error": "insufficient_credits", "required_usdc": "5", "credits_balance": "1", "shortfall_usdc": "4"})
+    client, calls = _client_mock([quote_402, short])
+    c = _token_client()
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client), patch("oneshot.client.parse_payment_required", return_value={"accepted": {}}):
+        with pytest.raises(InsufficientCreditsError) as ei:
+            await c.acall_tool("/v1/compute/g1/fund", {"amount": 5, "memo": "t"})
+    assert (ei.value.required, ei.value.balance) == (5.0, 1.0)
+    assert len(calls) == 2
+
+
+@pytest.mark.asyncio
+async def test_402_without_quote_id_is_a_shortfall_not_a_signature():
+    quote_402 = _Resp(402, {"payment_request": {"amount": "0.01"}, "context": {}}, {"payment-required": ""})
+    client, calls = _client_mock([quote_402])
+    c = _token_client()
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client), patch("oneshot.client.parse_payment_required", return_value={"accepted": {}}):
+        with pytest.raises(InsufficientCreditsError) as ei:
+            await c.acall_tool("/v1/tools/search", {"query": "x", "memo": "t"})
+    assert ei.value.required == 0.01
+    assert len(calls) == 1
+
+
+@pytest.mark.asyncio
+async def test_budget_exceeded_on_quote_leg_still_typed():
+    client, _ = _client_mock([_Resp(403, {"error": "budget_exceeded", "message": "cap", "budget": {"reason": "daily", "cap": "1", "spent": "1", "charge": "0.5"}})])
+    c = _token_client()
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        with pytest.raises(BudgetExceededError) as ei:
+            await c.acall_tool("/v1/tools/search", {"query": "x", "memo": "t"})
+    assert ei.value.reason == "daily"
+
+
+# ---------------------------------------------------------------- token management
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("enveloped", [False, True])
+async def test_wallet_session_mints_lists_and_revokes(enveloped):
+    w = OneShotClient(TEST_PRIVATE_KEY, base_url=BASE)
+    wrap = lambda data: {"success": True, "data": data} if enveloped else data
+    client, calls = _client_mock([
+        _Resp(201, wrap({"id": "t1", "token": TOKEN, "token_prefix": TOKEN[:16], "name": "grok", "created_at": "x"})),
+        _Resp(200, wrap({"tokens": [{"id": "t1"}]})),
+        _Resp(204, {}),
+    ])
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        created = await w.acreate_access_token("grok")
+        listed = await w.alist_access_tokens(active_only=True)
+        await w.arevoke_access_token("t1")
+    assert created["id"] == "t1" and listed == [{"id": "t1"}]
+    assert calls[0]["url"] == f"{BASE}/v1/agents/me/access-tokens" and calls[0]["json"] == {"name": "grok"}
+    assert "x-agent-proof" in calls[0]["headers"]
+    assert calls[1]["url"].endswith("/v1/agents/me/access-tokens?active=true")
+    assert calls[2]["method"] == "DELETE" and calls[2]["url"].endswith("/v1/agents/me/access-tokens/t1")
+
+
+@pytest.mark.asyncio
+async def test_token_session_refuses_token_management_before_any_request():
+    c = _token_client()
+    client, calls = _client_mock([])
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        for coro in (c.acreate_access_token("x"), c.alist_access_tokens(), c.arevoke_access_token("t1")):
+            with pytest.raises(ValidationError, match="Access tokens cannot"):
+                await coro
+    assert calls == []

oneshot_python-0.26.0/tests/test_top_up_credits.py

@@ -0,0 +1,87 @@
+"""top_up_credits — parity with the TS SDK's topUpCredits (POST /v1/credits/top-up).
+
+A wallet session runs the ordinary quote-then-pay dance through ``acall_tool``;
+inputs are validated before any request; a session that carries an access
+token is refused before any request (credits cannot be bought with credits).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+
+from oneshot import OneShotClient, ValidationError
+
+TEST_PRIVATE_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
+
+
+@pytest.fixture(autouse=True)
+def _fresh_event_loop():
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    yield
+    loop.close()
+    asyncio.set_event_loop(asyncio.new_event_loop())
+
+
+class _Resp:
+    def __init__(self, status_code: int, body: Any) -> None:
+        self.status_code = status_code
+        self._body = body
+        self.headers: dict[str, str] = {}
+        self.text = "{}"
+        self.is_success = 200 <= status_code < 300
+
+    def json(self) -> Any:
+        return self._body
+
+    def raise_for_status(self) -> None:
+        return None
+
+
+class _FakeAsyncClient:
+    def __init__(self, responses: list[_Resp]) -> None:
+        self.calls: list[dict[str, Any]] = []
+        self._queue = list(responses)
+
+    async def post(self, url: str, **kw: Any) -> _Resp:
+        self.calls.append({"url": url, "json": kw.get("json"), "headers": kw.get("headers") or {}})
+        return self._queue.pop(0)
+
+    async def __aenter__(self) -> "_FakeAsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        return None
+
+
+def test_validates_amount_before_any_request():
+    c = OneShotClient(TEST_PRIVATE_KEY)
+    for bad in (0, -5, None, True, float("nan"), float("inf"), "25"):
+        with pytest.raises(ValidationError, match="amount must be a positive number"):
+            c.top_up_credits(bad)  # type: ignore[arg-type]
+
+
+@pytest.mark.asyncio
+async def test_wallet_session_posts_the_amount_to_the_top_up_route():
+    client = _FakeAsyncClient([_Resp(200, {"data": {"topped_up": "25.000000", "credits_balance": "25.000000"}})])
+    c = OneShotClient(TEST_PRIVATE_KEY, base_url="http://test.local")
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        out = await c.atop_up_credits(25)
+    assert out["credits_balance"] == "25.000000"
+    assert client.calls[0]["url"] == "http://test.local/v1/credits/top-up"
+    assert client.calls[0]["json"]["amount"] == 25
+
+
+@pytest.mark.asyncio
+async def test_access_token_session_is_refused_before_any_request():
+    client = _FakeAsyncClient([])
+    c = OneShotClient(TEST_PRIVATE_KEY, base_url="http://test.local")
+    c._access_token = "oneshot_" + "ab" * 32  # what the access-token constructor sets
+    with patch("oneshot.client.httpx.AsyncClient", return_value=client):
+        with pytest.raises(ValidationError, match="Access tokens cannot top up credits"):
+            await c.atop_up_credits(25)
+    assert client.calls == []