polynode 0.5.5__py3-none-any.whl

polynode/__init__.py

@@ -0,0 +1,41 @@
+"""PolyNode Python SDK — real-time prediction market data and trading."""
+
+from ._version import __version__
+from .client import AsyncPolyNode, PolyNode
+from .engine import EngineView, OrderbookEngine
+from .errors import ApiError, PolyNodeError, WsError
+from .orderbook import OrderbookWS
+from .orderbook_state import LocalOrderbook
+from .redemption_watcher import RedeemableAlert, RedemptionWatcher, TrackedPosition
+from .short_form import ShortFormStream
+from .subscription import Subscription, SubscriptionBuilder
+from .testing import get_active_test_wallet, get_active_test_wallets
+from .ws import PolyNodeWS
+
+__all__ = [
+    "__version__",
+    # Clients
+    "PolyNode",
+    "AsyncPolyNode",
+    # WebSocket
+    "PolyNodeWS",
+    "SubscriptionBuilder",
+    "Subscription",
+    # Orderbook
+    "OrderbookWS",
+    "LocalOrderbook",
+    "OrderbookEngine",
+    "EngineView",
+    # Streams
+    "ShortFormStream",
+    "RedemptionWatcher",
+    "RedeemableAlert",
+    "TrackedPosition",
+    # Testing
+    "get_active_test_wallet",
+    "get_active_test_wallets",
+    # Errors
+    "PolyNodeError",
+    "ApiError",
+    "WsError",
+]

polynode/_version.py

@@ -0,0 +1 @@
+__version__ = "0.5.5"

polynode/cache/__init__.py

@@ -0,0 +1,11 @@
+"""Cache module placeholder — local SQLite-backed trade/position history.
+
+This module will be implemented in a future release.
+The cache/ directory structure matches the TypeScript SDK:
+- sqlite_backend.py — SQLite storage (settlements, trades, positions)
+- watchlist.py — JSON watchlist file management
+- backfill.py — Rate-limited REST backfill orchestrator
+- query_builder.py — Fluent query builder
+- views.py — Analytical views (wallet_dashboard, leaderboard, etc.)
+- export.py — CSV/JSON export
+"""

polynode/client.py

@@ -0,0 +1,635 @@
+"""Sync and async REST clients for the PolyNode API."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from .errors import ApiError, PolyNodeError
+from .types.rest import (
+    ActivityResponse,
+    ApiKeyResponse,
+    CandlesResponse,
+    EventDetailResponse,
+    EventSearchResponse,
+    LeaderboardResponse,
+    MarketsByCategoryResponse,
+    MarketsListResponse,
+    MarketsResponse,
+    MidpointResponse,
+    MoversResponse,
+    OrderbookResponse,
+    SearchResponse,
+    SettlementsResponse,
+    SpreadResponse,
+    StatusResponse,
+    TraderPnlResponse,
+    TraderProfile,
+    TrendingResponse,
+    WalletResponse,
+)
+from .types.enums import CandleResolution, MarketSortField
+
+
+class PolyNode:
+    """Synchronous PolyNode REST client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.polynode.dev",
+        ws_url: str = "wss://ws.polynode.dev/ws",
+        ob_url: str = "wss://ob.polynode.dev/ws",
+        rpc_url: str = "https://rpc.polynode.dev",
+        timeout: float = 10.0,
+    ) -> None:
+        if not api_key:
+            raise PolyNodeError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.ws_url = ws_url.rstrip("/")
+        self.ob_url = ob_url.rstrip("/")
+        self.rpc_url = rpc_url.rstrip("/")
+        self._timeout = timeout
+        self._http = httpx.Client(timeout=timeout)
+        self._ws = None
+        self._orderbook = None
+
+    def __enter__(self) -> PolyNode:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    @property
+    def ws(self):
+        """Lazy-initialized WebSocket client."""
+        if self._ws is None:
+            from .ws import PolyNodeWS
+            self._ws = PolyNodeWS(self.api_key, self.ws_url)
+        return self._ws
+
+    @property
+    def orderbook(self):
+        """Lazy-initialized orderbook WebSocket client."""
+        if self._orderbook is None:
+            from .orderbook import OrderbookWS
+            self._orderbook = OrderbookWS(self.api_key, self.ob_url)
+        return self._orderbook
+
+    # ── Internal ──
+
+    def _fetch(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: dict | None = None,
+        auth: bool = True,
+        query: dict[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        params = {}
+        if query:
+            params = {k: str(v) for k, v in query.items() if v is not None}
+
+        headers = {}
+        if auth:
+            headers["x-api-key"] = self.api_key
+
+        resp = self._http.request(
+            method,
+            url,
+            params=params or None,
+            headers=headers,
+            json=body,
+        )
+
+        if resp.status_code >= 400:
+            msg = f"HTTP {resp.status_code}"
+            try:
+                err_body = resp.json()
+                msg = err_body.get("error") or err_body.get("message") or msg
+            except Exception:
+                pass
+            raise ApiError(msg, resp.status_code)
+
+        content_type = resp.headers.get("content-type", "")
+        if "application/json" in content_type:
+            return resp.json()
+        return resp.text
+
+    # ── System ──
+
+    def healthz(self) -> str:
+        return self._fetch("/healthz", auth=False)
+
+    def readyz(self) -> Any:
+        return self._fetch("/readyz", auth=False)
+
+    def status(self) -> StatusResponse:
+        return StatusResponse.model_validate(self._fetch("/v1/status"))
+
+    def create_key(self, name: str = "unnamed") -> ApiKeyResponse:
+        return ApiKeyResponse.model_validate(
+            self._fetch("/v1/keys", method="POST", body={"name": name}, auth=False)
+        )
+
+    # ── Markets ──
+
+    def markets(self, *, count: int | None = None) -> MarketsResponse:
+        return MarketsResponse.model_validate(
+            self._fetch("/v1/markets", query={"count": count})
+        )
+
+    def market(self, token_id: str) -> dict:
+        return self._fetch(f"/v1/markets/{quote(token_id, safe='')}")
+
+    def market_by_slug(self, slug: str) -> dict:
+        return self._fetch(f"/v1/markets/slug/{quote(slug, safe='')}")
+
+    def market_by_condition(self, condition_id: str) -> dict:
+        return self._fetch(f"/v1/markets/condition/{quote(condition_id, safe='')}")
+
+    def markets_list(
+        self,
+        *,
+        count: int | None = None,
+        sort: MarketSortField | None = None,
+        category: str | None = None,
+        min_volume: float | None = None,
+        active_only: bool | None = None,
+        cursor: int | None = None,
+    ) -> MarketsListResponse:
+        return MarketsListResponse.model_validate(
+            self._fetch(
+                "/v1/markets/list",
+                query={
+                    "count": count,
+                    "sort": sort,
+                    "category": category,
+                    "min_volume": min_volume,
+                    "active_only": active_only,
+                    "cursor": cursor,
+                },
+            )
+        )
+
+    def search(
+        self, query: str, *, limit: int | None = None, include_inactive: bool | None = None
+    ) -> SearchResponse:
+        return SearchResponse.model_validate(
+            self._fetch("/v1/search", query={"q": query, "limit": limit, "include_inactive": include_inactive})
+        )
+
+    # ── Pricing ──
+
+    def candles(
+        self,
+        token_id: str,
+        *,
+        resolution: CandleResolution | None = None,
+        limit: int | None = None,
+    ) -> CandlesResponse:
+        return CandlesResponse.model_validate(
+            self._fetch(
+                f"/v1/candles/{quote(token_id, safe='')}",
+                query={"resolution": resolution, "limit": limit},
+            )
+        )
+
+    def stats(self, token_id: str) -> dict:
+        return self._fetch(f"/v1/stats/{quote(token_id, safe='')}")
+
+    # ── Settlements ──
+
+    def recent_settlements(self, *, count: int | None = None) -> SettlementsResponse:
+        return SettlementsResponse.model_validate(
+            self._fetch("/v1/settlements/recent", query={"count": count})
+        )
+
+    def token_settlements(self, token_id: str, *, count: int | None = None) -> SettlementsResponse:
+        return SettlementsResponse.model_validate(
+            self._fetch(f"/v1/settlements/token/{quote(token_id, safe='')}", query={"count": count})
+        )
+
+    def wallet_settlements(self, address: str, *, count: int | None = None) -> SettlementsResponse:
+        return SettlementsResponse.model_validate(
+            self._fetch(f"/v1/settlements/wallet/{quote(address, safe='')}", query={"count": count})
+        )
+
+    # ── Wallets ──
+
+    def wallet(self, address: str) -> WalletResponse:
+        return WalletResponse.model_validate(
+            self._fetch(f"/v1/wallets/{quote(address, safe='')}")
+        )
+
+    def wallet_trades(self, address: str, *, limit: int | None = None, offset: int | None = None) -> dict:
+        return self._fetch(
+            f"/v1/wallets/{quote(address, safe='')}/trades",
+            query={"limit": limit, "offset": offset},
+        )
+
+    def market_trades(
+        self,
+        id: str,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        side: str | None = None,
+        user: str | None = None,
+    ) -> dict:
+        return self._fetch(
+            f"/v1/markets/{quote(id, safe='')}/trades",
+            query={"limit": limit, "offset": offset, "side": side, "user": user},
+        )
+
+    def wallet_positions(self, address: str, *, limit: int | None = None, offset: int | None = None) -> dict:
+        return self._fetch(
+            f"/v1/wallets/{quote(address, safe='')}/positions",
+            query={"limit": limit, "offset": offset},
+        )
+
+    def wallet_onchain_positions(self, address: str) -> dict:
+        return self._fetch(f"/v2/wallets/{quote(address, safe='')}/positions/onchain")
+
+    # ── Orderbook (REST) ──
+
+    def orderbook_rest(self, token_id: str) -> OrderbookResponse:
+        return OrderbookResponse.model_validate(
+            self._fetch(f"/v1/orderbook/{quote(token_id, safe='')}")
+        )
+
+    def midpoint(self, token_id: str) -> MidpointResponse:
+        return MidpointResponse.model_validate(
+            self._fetch(f"/v1/midpoint/{quote(token_id, safe='')}")
+        )
+
+    def spread(self, token_id: str) -> SpreadResponse:
+        return SpreadResponse.model_validate(
+            self._fetch(f"/v1/spread/{quote(token_id, safe='')}")
+        )
+
+    # ── Enriched Data ──
+
+    def leaderboard(self, *, period: str | None = None, sort: str | None = None) -> LeaderboardResponse:
+        return LeaderboardResponse.model_validate(
+            self._fetch("/v1/leaderboard", query={"period": period, "sort": sort})
+        )
+
+    def trending(self) -> TrendingResponse:
+        return TrendingResponse.model_validate(self._fetch("/v1/trending"))
+
+    def activity(self) -> ActivityResponse:
+        return ActivityResponse.model_validate(self._fetch("/v1/activity"))
+
+    def movers(self) -> MoversResponse:
+        return MoversResponse.model_validate(self._fetch("/v1/movers"))
+
+    def trader_profile(self, wallet: str) -> TraderProfile:
+        return TraderProfile.model_validate(
+            self._fetch(f"/v1/trader/{quote(wallet, safe='')}")
+        )
+
+    def trader_pnl(self, wallet: str, *, period: str | None = None) -> TraderPnlResponse:
+        return TraderPnlResponse.model_validate(
+            self._fetch(f"/v1/trader/{quote(wallet, safe='')}/pnl", query={"period": period})
+        )
+
+    def event(self, slug: str) -> EventDetailResponse:
+        return EventDetailResponse.model_validate(
+            self._fetch(f"/v1/event/{quote(slug, safe='')}")
+        )
+
+    def search_events(self, query: str, *, limit: int | None = None) -> EventSearchResponse:
+        return EventSearchResponse.model_validate(
+            self._fetch("/v1/events/search", query={"q": query, "limit": limit})
+        )
+
+    def markets_by_category(self, category: str) -> MarketsByCategoryResponse:
+        return MarketsByCategoryResponse.model_validate(
+            self._fetch(f"/v1/markets/{quote(category, safe='')}")
+        )
+
+    # ── RPC ──
+
+    def rpc(self, method: str, params: list | None = None) -> Any:
+        resp = self._http.post(
+            self.rpc_url,
+            headers={"Content-Type": "application/json", "x-api-key": self.api_key},
+            json={"jsonrpc": "2.0", "method": method, "params": params or [], "id": 1},
+        )
+        if resp.status_code >= 400:
+            raise ApiError(f"RPC HTTP {resp.status_code}", resp.status_code)
+        data = resp.json()
+        if data.get("error"):
+            raise ApiError(data["error"]["message"], data["error"]["code"])
+        return data.get("result")
+
+
+class AsyncPolyNode:
+    """Asynchronous PolyNode REST client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.polynode.dev",
+        ws_url: str = "wss://ws.polynode.dev/ws",
+        ob_url: str = "wss://ob.polynode.dev/ws",
+        rpc_url: str = "https://rpc.polynode.dev",
+        timeout: float = 10.0,
+    ) -> None:
+        if not api_key:
+            raise PolyNodeError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.ws_url = ws_url.rstrip("/")
+        self.ob_url = ob_url.rstrip("/")
+        self.rpc_url = rpc_url.rstrip("/")
+        self._timeout = timeout
+        self._http = httpx.AsyncClient(timeout=timeout)
+        self._ws = None
+        self._orderbook = None
+
+    async def __aenter__(self) -> AsyncPolyNode:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+        if self._ws:
+            self._ws.disconnect()
+
+    @property
+    def ws(self):
+        if self._ws is None:
+            from .ws import PolyNodeWS
+            self._ws = PolyNodeWS(self.api_key, self.ws_url)
+        return self._ws
+
+    @property
+    def orderbook(self):
+        if self._orderbook is None:
+            from .orderbook import OrderbookWS
+            self._orderbook = OrderbookWS(self.api_key, self.ob_url)
+        return self._orderbook
+
+    # ── Internal ──
+
+    async def _fetch(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        body: dict | None = None,
+        auth: bool = True,
+        query: dict[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        params = {}
+        if query:
+            params = {k: str(v) for k, v in query.items() if v is not None}
+
+        headers = {}
+        if auth:
+            headers["x-api-key"] = self.api_key
+
+        resp = await self._http.request(
+            method,
+            url,
+            params=params or None,
+            headers=headers,
+            json=body,
+        )
+
+        if resp.status_code >= 400:
+            msg = f"HTTP {resp.status_code}"
+            try:
+                err_body = resp.json()
+                msg = err_body.get("error") or err_body.get("message") or msg
+            except Exception:
+                pass
+            raise ApiError(msg, resp.status_code)
+
+        content_type = resp.headers.get("content-type", "")
+        if "application/json" in content_type:
+            return resp.json()
+        return resp.text
+
+    # ── System ──
+
+    async def healthz(self) -> str:
+        return await self._fetch("/healthz", auth=False)
+
+    async def readyz(self) -> Any:
+        return await self._fetch("/readyz", auth=False)
+
+    async def status(self) -> StatusResponse:
+        return StatusResponse.model_validate(await self._fetch("/v1/status"))
+
+    async def create_key(self, name: str = "unnamed") -> ApiKeyResponse:
+        return ApiKeyResponse.model_validate(
+            await self._fetch("/v1/keys", method="POST", body={"name": name}, auth=False)
+        )
+
+    # ── Markets ──
+
+    async def markets(self, *, count: int | None = None) -> MarketsResponse:
+        return MarketsResponse.model_validate(
+            await self._fetch("/v1/markets", query={"count": count})
+        )
+
+    async def market(self, token_id: str) -> dict:
+        return await self._fetch(f"/v1/markets/{quote(token_id, safe='')}")
+
+    async def market_by_slug(self, slug: str) -> dict:
+        return await self._fetch(f"/v1/markets/slug/{quote(slug, safe='')}")
+
+    async def market_by_condition(self, condition_id: str) -> dict:
+        return await self._fetch(f"/v1/markets/condition/{quote(condition_id, safe='')}")
+
+    async def markets_list(
+        self,
+        *,
+        count: int | None = None,
+        sort: MarketSortField | None = None,
+        category: str | None = None,
+        min_volume: float | None = None,
+        active_only: bool | None = None,
+        cursor: int | None = None,
+    ) -> MarketsListResponse:
+        return MarketsListResponse.model_validate(
+            await self._fetch(
+                "/v1/markets/list",
+                query={
+                    "count": count,
+                    "sort": sort,
+                    "category": category,
+                    "min_volume": min_volume,
+                    "active_only": active_only,
+                    "cursor": cursor,
+                },
+            )
+        )
+
+    async def search(
+        self, query: str, *, limit: int | None = None, include_inactive: bool | None = None
+    ) -> SearchResponse:
+        return SearchResponse.model_validate(
+            await self._fetch("/v1/search", query={"q": query, "limit": limit, "include_inactive": include_inactive})
+        )
+
+    # ── Pricing ──
+
+    async def candles(
+        self,
+        token_id: str,
+        *,
+        resolution: CandleResolution | None = None,
+        limit: int | None = None,
+    ) -> CandlesResponse:
+        return CandlesResponse.model_validate(
+            await self._fetch(
+                f"/v1/candles/{quote(token_id, safe='')}",
+                query={"resolution": resolution, "limit": limit},
+            )
+        )
+
+    async def stats(self, token_id: str) -> dict:
+        return await self._fetch(f"/v1/stats/{quote(token_id, safe='')}")
+
+    # ── Settlements ──
+
+    async def recent_settlements(self, *, count: int | None = None) -> SettlementsResponse:
+        return SettlementsResponse.model_validate(
+            await self._fetch("/v1/settlements/recent", query={"count": count})
+        )
+
+    async def token_settlements(self, token_id: str, *, count: int | None = None) -> SettlementsResponse:
+        return SettlementsResponse.model_validate(
+            await self._fetch(f"/v1/settlements/token/{quote(token_id, safe='')}", query={"count": count})
+        )
+
+    async def wallet_settlements(self, address: str, *, count: int | None = None) -> SettlementsResponse:
+        return SettlementsResponse.model_validate(
+            await self._fetch(f"/v1/settlements/wallet/{quote(address, safe='')}", query={"count": count})
+        )
+
+    # ── Wallets ──
+
+    async def wallet(self, address: str) -> WalletResponse:
+        return WalletResponse.model_validate(
+            await self._fetch(f"/v1/wallets/{quote(address, safe='')}")
+        )
+
+    async def wallet_trades(self, address: str, *, limit: int | None = None, offset: int | None = None) -> dict:
+        return await self._fetch(
+            f"/v1/wallets/{quote(address, safe='')}/trades",
+            query={"limit": limit, "offset": offset},
+        )
+
+    async def market_trades(
+        self,
+        id: str,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        side: str | None = None,
+        user: str | None = None,
+    ) -> dict:
+        return await self._fetch(
+            f"/v1/markets/{quote(id, safe='')}/trades",
+            query={"limit": limit, "offset": offset, "side": side, "user": user},
+        )
+
+    async def wallet_positions(self, address: str, *, limit: int | None = None, offset: int | None = None) -> dict:
+        return await self._fetch(
+            f"/v1/wallets/{quote(address, safe='')}/positions",
+            query={"limit": limit, "offset": offset},
+        )
+
+    async def wallet_onchain_positions(self, address: str) -> dict:
+        return await self._fetch(f"/v2/wallets/{quote(address, safe='')}/positions/onchain")
+
+    # ── Orderbook (REST) ──
+
+    async def orderbook_rest(self, token_id: str) -> OrderbookResponse:
+        return OrderbookResponse.model_validate(
+            await self._fetch(f"/v1/orderbook/{quote(token_id, safe='')}")
+        )
+
+    async def midpoint(self, token_id: str) -> MidpointResponse:
+        return MidpointResponse.model_validate(
+            await self._fetch(f"/v1/midpoint/{quote(token_id, safe='')}")
+        )
+
+    async def spread(self, token_id: str) -> SpreadResponse:
+        return SpreadResponse.model_validate(
+            await self._fetch(f"/v1/spread/{quote(token_id, safe='')}")
+        )
+
+    # ── Enriched Data ──
+
+    async def leaderboard(self, *, period: str | None = None, sort: str | None = None) -> LeaderboardResponse:
+        return LeaderboardResponse.model_validate(
+            await self._fetch("/v1/leaderboard", query={"period": period, "sort": sort})
+        )
+
+    async def trending(self) -> TrendingResponse:
+        return TrendingResponse.model_validate(await self._fetch("/v1/trending"))
+
+    async def activity(self) -> ActivityResponse:
+        return ActivityResponse.model_validate(await self._fetch("/v1/activity"))
+
+    async def movers(self) -> MoversResponse:
+        return MoversResponse.model_validate(await self._fetch("/v1/movers"))
+
+    async def trader_profile(self, wallet: str) -> TraderProfile:
+        return TraderProfile.model_validate(
+            await self._fetch(f"/v1/trader/{quote(wallet, safe='')}")
+        )
+
+    async def trader_pnl(self, wallet: str, *, period: str | None = None) -> TraderPnlResponse:
+        return TraderPnlResponse.model_validate(
+            await self._fetch(f"/v1/trader/{quote(wallet, safe='')}/pnl", query={"period": period})
+        )
+
+    async def event(self, slug: str) -> EventDetailResponse:
+        return EventDetailResponse.model_validate(
+            await self._fetch(f"/v1/event/{quote(slug, safe='')}")
+        )
+
+    async def search_events(self, query: str, *, limit: int | None = None) -> EventSearchResponse:
+        return EventSearchResponse.model_validate(
+            await self._fetch("/v1/events/search", query={"q": query, "limit": limit})
+        )
+
+    async def markets_by_category(self, category: str) -> MarketsByCategoryResponse:
+        return MarketsByCategoryResponse.model_validate(
+            await self._fetch(f"/v1/markets/{quote(category, safe='')}")
+        )
+
+    # ── RPC ──
+
+    async def rpc(self, method: str, params: list | None = None) -> Any:
+        resp = await self._http.post(
+            self.rpc_url,
+            headers={"Content-Type": "application/json", "x-api-key": self.api_key},
+            json={"jsonrpc": "2.0", "method": method, "params": params or [], "id": 1},
+        )
+        if resp.status_code >= 400:
+            raise ApiError(f"RPC HTTP {resp.status_code}", resp.status_code)
+        data = resp.json()
+        if data.get("error"):
+            raise ApiError(data["error"]["message"], data["error"]["code"])
+        return data.get("result")