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

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: oneshot-python
-Version: 0.24.0
-Summary: Core Python SDK for the OneShot API — HTTP client with x402 payment handling — 35 tools
+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
 Requires-Dist: eth-account>=0.13.0

{oneshot_python-0.24.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:
@@ -192,7 +217,7 @@ Every method has an `a*` async mirror (`acompute`, `aget_compute_goal`, …).
 ## Links
 
 - [Documentation](https://docs.oneshotagent.com/sdk/installation#install-via-pip-python)
-- [LangChain integration](https://pypi.org/project/langchain-oneshot/) — 35 tools as LangChain BaseTool
+- [LangChain integration](https://pypi.org/project/langchain-oneshot/) — 43 tools as LangChain BaseTool
 - [GAME plugin](https://pypi.org/project/game-plugin-oneshot/) — Virtuals Protocol integration
 - [TypeScript SDK](https://www.npmjs.com/package/@oneshot-agent/sdk)
 - [MCP Server](https://www.npmjs.com/package/@oneshot-agent/mcp-server)

{oneshot_python-0.24.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.24.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.24.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