Upload polymarket.py

services/polymarket.py

@@ -0,0 +1,963 @@
+"""Read-only Polymarket market-data service.
+
+The service uses the newer Gamma keyset endpoints for event/market discovery,
+Gamma search and tag endpoints for navigation, and the CLOB API for live
+prices, order books, and price history. It returns the normalized models from
+``schemas.predictions`` and is shared by the REST router and the agent tools.
+
+Configuration (all optional):
+    POLYMARKET_GAMMA_URL: Gamma base URL
+    POLYMARKET_CLOB_URL:  CLOB base URL
+    POLYMARKET_TIMEOUT:   request timeout in seconds (default 15)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from schemas.predictions import (
+    EventDetail,
+    EventPage,
+    EventSummary,
+    MarketBooks,
+    MarketDetail,
+    MarketPage,
+    MarketSummary,
+    OrderBook,
+    OrderBookLevel,
+    OrderSide,
+    OutcomeOut,
+    PredictionSort,
+    PriceHistory,
+    PriceInterval,
+    PricePoint,
+    SearchPagination,
+    SearchResult,
+    TagOut,
+    TokenPrice,
+)
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(os.getenv(name, str(default)))
+    except ValueError:
+        return default
+
+
+GAMMA_BASE_URL = os.getenv(
+    "POLYMARKET_GAMMA_URL", "https://gamma-api.polymarket.com"
+).rstrip("/")
+CLOB_BASE_URL = os.getenv(
+    "POLYMARKET_CLOB_URL", "https://clob.polymarket.com"
+).rstrip("/")
+DEFAULT_TIMEOUT = _env_float("POLYMARKET_TIMEOUT", 15.0)
+
+_CACHE_MAX_ENTRIES = 128
+
+
+class PolymarketError(Exception):
+    """Base class for Polymarket service failures."""
+
+
+class PolymarketNotFound(PolymarketError):
+    """The requested event, market, or token does not exist."""
+
+
+class PolymarketTimeout(PolymarketError):
+    """The upstream request timed out."""
+
+
+class PolymarketUpstreamError(PolymarketError):
+    """The upstream API returned an error or an unusable response."""
+
+
+_EVENT_SORT: dict[PredictionSort, tuple[str, bool]] = {
+    "volume_24h": ("volume24hr", False),
+    "volume": ("volume", False),
+    "liquidity": ("liquidity", False),
+    "newest": ("startDate", False),
+    "ending_soon": ("endDate", True),
+}
+_MARKET_SORT: dict[PredictionSort, tuple[str, bool]] = {
+    "volume_24h": ("volume24hr", False),
+    "volume": ("volumeNum", False),
+    "liquidity": ("liquidityNum", False),
+    "newest": ("startDate", False),
+    "ending_soon": ("endDate", True),
+}
+
+
+def _params(values: Mapping[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def _bool_param(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _as_list(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _as_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _as_float(value: Any) -> float | None:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_int(value: Any) -> int | None:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_bool(value: Any) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"true", "1", "yes"}:
+            return True
+        if lowered in {"false", "0", "no"}:
+            return False
+        return None
+    if isinstance(value, (int, float)):
+        return bool(value)
+    return None
+
+
+def _as_datetime(value: Any) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+    if isinstance(value, (int, float)):
+        number = float(value)
+        if number > 1_000_000_000_000:
+            number /= 1000
+        return datetime.fromtimestamp(number, tz=timezone.utc)
+
+    text = str(value).strip()
+    if not text:
+        return None
+    if text.isdigit() and len(text) >= 10:
+        number = float(text)
+        if len(text) >= 13:
+            number /= 1000
+        return datetime.fromtimestamp(number, tz=timezone.utc)
+
+    text = text.replace("Z", "+00:00")
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        try:
+            parsed = datetime.fromisoformat(text.replace(" ", "T", 1))
+        except ValueError:
+            return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def _first_float(*values: Any) -> float | None:
+    for value in values:
+        parsed = _as_float(value)
+        if parsed is not None:
+            return parsed
+    return None
+
+
+def _first_str(*values: Any) -> str | None:
+    for value in values:
+        parsed = _as_str(value)
+        if parsed is not None:
+            return parsed
+    return None
+
+
+def _json_list(value: Any) -> list[Any]:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError:
+            return []
+        return parsed if isinstance(parsed, list) else []
+    return []
+
+
+def _retry_delay(value: str | None) -> float:
+    try:
+        delay = float(value) if value is not None else 0.25
+    except ValueError:
+        delay = 0.25
+    return max(0.0, min(delay, 2.0))
+
+
+def _error_message(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+    if isinstance(payload, Mapping):
+        message = payload.get("error") or payload.get("detail") or payload.get("message")
+        if message:
+            return str(message)[:300]
+    text = response.text.strip().replace("\n", " ")
+    return (text or response.reason_phrase)[:300]
+
+
+def _to_tag(raw: Mapping[str, Any]) -> TagOut:
+    event_count = raw.get("eventCount")
+    if event_count is None:
+        event_count = raw.get("event_count")
+    return TagOut(
+        id=_as_str(raw.get("id")) or "",
+        label=_as_str(raw.get("label")),
+        slug=_as_str(raw.get("slug")),
+        event_count=_as_int(event_count),
+    )
+
+
+def _to_tags(raw: Mapping[str, Any]) -> list[TagOut]:
+    return [
+        _to_tag(tag)
+        for tag in _as_list(raw.get("tags"))
+        if isinstance(tag, Mapping)
+    ]
+
+
+def _to_outcomes(raw: Mapping[str, Any]) -> list[OutcomeOut]:
+    names = _json_list(raw.get("outcomes"))
+    prices = _json_list(raw.get("outcomePrices"))
+    token_ids = _json_list(raw.get("clobTokenIds"))
+
+    outcomes: list[OutcomeOut] = []
+    for index, name in enumerate(names):
+        outcomes.append(
+            OutcomeOut(
+                name=str(name),
+                price=_as_float(prices[index]) if index < len(prices) else None,
+                token_id=(
+                    _as_str(token_ids[index]) if index < len(token_ids) else None
+                ),
+            )
+        )
+    return outcomes
+
+
+def _event_context(
+    raw: Mapping[str, Any], event: Mapping[str, Any] | None
+) -> Mapping[str, Any] | None:
+    if event is not None:
+        return event
+    events = _as_list(raw.get("events"))
+    if events and isinstance(events[0], Mapping):
+        return events[0]
+    return None
+
+
+def _market_url(event_slug: str | None, market_slug: str | None) -> str | None:
+    if event_slug:
+        return f"https://polymarket.com/event/{event_slug}"
+    if market_slug:
+        return f"https://polymarket.com/market/{market_slug}"
+    return None
+
+
+def _to_market_summary(
+    raw: Mapping[str, Any], *, event: Mapping[str, Any] | None = None
+) -> MarketSummary:
+    context = _event_context(raw, event)
+    event_slug = _as_str(context.get("slug")) if context else None
+    market_slug = _as_str(raw.get("slug"))
+
+    return MarketSummary(
+        id=_as_str(raw.get("id")) or "",
+        question=_as_str(raw.get("question")),
+        slug=market_slug,
+        condition_id=_as_str(raw.get("conditionId")),
+        event_id=_as_str(context.get("id")) if context else None,
+        event_title=_as_str(context.get("title")) if context else None,
+        event_slug=event_slug,
+        outcomes=_to_outcomes(raw),
+        volume=_first_float(raw.get("volume"), raw.get("volumeNum"), raw.get("volumeClob")),
+        volume_24h=_first_float(raw.get("volume24hr"), raw.get("volume24hrClob")),
+        liquidity=_first_float(
+            raw.get("liquidity"), raw.get("liquidityNum"), raw.get("liquidityClob")
+        ),
+        open_interest=_first_float(
+            raw.get("openInterest"), context.get("openInterest") if context else None
+        ),
+        start_date=_as_datetime(raw.get("startDate")),
+        end_date=_as_datetime(raw.get("endDate")),
+        active=_as_bool(raw.get("active")),
+        closed=_as_bool(raw.get("closed")),
+        accepting_orders=_as_bool(raw.get("acceptingOrders")),
+        best_bid=_as_float(raw.get("bestBid")),
+        best_ask=_as_float(raw.get("bestAsk")),
+        last_trade_price=_as_float(raw.get("lastTradePrice")),
+        spread=_as_float(raw.get("spread")),
+        image=_first_str(raw.get("image"), raw.get("icon")),
+        url=_market_url(event_slug, market_slug),
+    )
+
+
+def _to_market_detail(raw: Mapping[str, Any]) -> MarketDetail:
+    summary = _to_market_summary(raw)
+    return MarketDetail(
+        **summary.model_dump(),
+        description=_as_str(raw.get("description")),
+        resolution_source=_as_str(raw.get("resolutionSource")),
+        tags=_to_tags(raw),
+    )
+
+
+def _to_event_summary(raw: Mapping[str, Any]) -> EventSummary:
+    slug = _as_str(raw.get("slug"))
+    markets = [
+        _to_market_summary(market, event=raw)
+        for market in _as_list(raw.get("markets"))
+        if isinstance(market, Mapping)
+    ]
+
+    return EventSummary(
+        id=_as_str(raw.get("id")) or "",
+        slug=slug,
+        title=_as_str(raw.get("title")),
+        subtitle=_as_str(raw.get("subtitle")),
+        active=_as_bool(raw.get("active")),
+        closed=_as_bool(raw.get("closed")),
+        volume=_as_float(raw.get("volume")),
+        volume_24h=_as_float(raw.get("volume24hr")),
+        liquidity=_as_float(raw.get("liquidity")),
+        open_interest=_as_float(raw.get("openInterest")),
+        start_date=_as_datetime(raw.get("startDate")),
+        end_date=_as_datetime(raw.get("endDate")),
+        image=_first_str(raw.get("image"), raw.get("icon")),
+        url=f"https://polymarket.com/event/{slug}" if slug else None,
+        tags=_to_tags(raw),
+        markets=markets,
+    )
+
+
+def _to_event_detail(raw: Mapping[str, Any]) -> EventDetail:
+    summary = _to_event_summary(raw)
+    return EventDetail(
+        **summary.model_dump(),
+        description=_as_str(raw.get("description")),
+        resolution_source=_as_str(raw.get("resolutionSource")),
+    )
+
+
+def _to_search_pagination(raw: Mapping[str, Any] | None) -> SearchPagination | None:
+    if not raw:
+        return None
+    has_more = raw.get("hasMore")
+    if has_more is None:
+        has_more = raw.get("has_more")
+    total_results = raw.get("totalResults")
+    if total_results is None:
+        total_results = raw.get("total_results")
+    return SearchPagination(
+        has_more=_as_bool(has_more),
+        total_results=_as_int(total_results),
+    )
+
+
+def _to_order_book(raw: Mapping[str, Any], token_id: str, depth: int) -> OrderBook:
+    depth = max(1, min(depth, 100))
+    bids = [
+        OrderBookLevel(
+            price=float(level.get("price")),
+            size=float(level.get("size")),
+        )
+        for level in _as_list(raw.get("bids"))
+        if isinstance(level, Mapping)
+        and _as_float(level.get("price")) is not None
+        and _as_float(level.get("size")) is not None
+    ]
+    asks = [
+        OrderBookLevel(
+            price=float(level.get("price")),
+            size=float(level.get("size")),
+        )
+        for level in _as_list(raw.get("asks"))
+        if isinstance(level, Mapping)
+        and _as_float(level.get("price")) is not None
+        and _as_float(level.get("size")) is not None
+    ]
+
+    bids.sort(key=lambda level: level.price, reverse=True)
+    asks.sort(key=lambda level: level.price)
+
+    best_bid = bids[0].price if bids else None
+    best_ask = asks[0].price if asks else None
+    midpoint = (
+        round((best_bid + best_ask) / 2, 6)
+        if best_bid is not None and best_ask is not None
+        else None
+    )
+    spread = (
+        round(best_ask - best_bid, 6)
+        if best_bid is not None and best_ask is not None
+        else None
+    )
+
+    return OrderBook(
+        token_id=token_id,
+        condition_id=_as_str(raw.get("market")),
+        fetched_at=_as_datetime(raw.get("timestamp")) or datetime.now(timezone.utc),
+        bids=bids[:depth],
+        asks=asks[:depth],
+        best_bid=best_bid,
+        best_ask=best_ask,
+        midpoint=midpoint,
+        spread=spread,
+        last_trade_price=_as_float(raw.get("last_trade_price")),
+        tick_size=_as_float(raw.get("tick_size")),
+        min_order_size=_as_float(raw.get("min_order_size")),
+        neg_risk=_as_bool(raw.get("neg_risk")),
+    )
+
+
+class PolymarketClient:
+    """Async read-only client for Polymarket's public APIs."""
+
+    def __init__(
+        self,
+        *,
+        gamma_url: str = GAMMA_BASE_URL,
+        clob_url: str = CLOB_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._gamma_url = gamma_url.rstrip("/")
+        self._clob_url = clob_url.rstrip("/")
+        self._timeout = timeout
+        self._transport = transport
+        self._client: httpx.AsyncClient | None = None
+        self._client_lock = asyncio.Lock()
+        self._cache: dict[str, tuple[float, Any]] = {}
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            async with self._client_lock:
+                if self._client is None:
+                    self._client = httpx.AsyncClient(
+                        timeout=httpx.Timeout(self._timeout),
+                        headers={
+                            "Accept": "application/json",
+                            "User-Agent": "stx-polymarket/1.0",
+                        },
+                        transport=self._transport,
+                    )
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+        self._cache.clear()
+
+    async def _request(
+        self,
+        base_url: str,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> Any:
+        client = await self._get_client()
+        url = f"{base_url}{path}"
+
+        for attempt in range(2):
+            try:
+                response = await client.get(url, params=params)
+            except httpx.TimeoutException as exc:
+                if attempt == 0:
+                    await asyncio.sleep(0.25)
+                    continue
+                raise PolymarketTimeout(
+                    f"Polymarket request timed out: {path}"
+                ) from exc
+            except httpx.RequestError as exc:
+                if attempt == 0:
+                    await asyncio.sleep(0.25)
+                    continue
+                raise PolymarketUpstreamError(
+                    f"Polymarket request failed: {exc}"
+                ) from exc
+
+            if response.status_code == 404:
+                raise PolymarketNotFound(f"Polymarket resource not found: {path}")
+
+            if response.status_code in {429, 500, 502, 503, 504} and attempt == 0:
+                await asyncio.sleep(
+                    _retry_delay(response.headers.get("Retry-After"))
+                )
+                continue
+
+            if response.status_code >= 400:
+                raise PolymarketUpstreamError(
+                    f"Polymarket API returned {response.status_code}: "
+                    f"{_error_message(response)}"
+                )
+
+            content_type = response.headers.get("content-type", "")
+            if content_type and "json" not in content_type.lower():
+                snippet = response.text.strip().replace("\n", " ")[:200]
+                raise PolymarketUpstreamError(
+                    "Polymarket returned a non-JSON response "
+                    f"({response.status_code}): {snippet}"
+                )
+
+            try:
+                return response.json()
+            except ValueError as exc:
+                raise PolymarketUpstreamError(
+                    "Polymarket returned invalid JSON."
+                ) from exc
+
+        raise PolymarketUpstreamError(f"Polymarket request failed: {path}")
+
+    async def _get_json(
+        self,
+        base_url: str,
+        path: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        ttl: float,
+    ) -> Any:
+        cache_key = json.dumps(
+            {"base": base_url, "path": path, "params": dict(params or {})},
+            sort_keys=True,
+            default=str,
+        )
+        now = time.monotonic()
+        cached = self._cache.get(cache_key)
+        if cached is not None and cached[0] > now:
+            return cached[1]
+
+        data = await self._request(base_url, path, params)
+        if len(self._cache) >= _CACHE_MAX_ENTRIES:
+            oldest_key = min(self._cache, key=lambda key: self._cache[key][0])
+            self._cache.pop(oldest_key, None)
+        self._cache[cache_key] = (now + ttl, data)
+        return data
+
+    async def list_events(
+        self,
+        *,
+        tag_id: int | None = None,
+        tag_slug: str | None = None,
+        closed: bool = False,
+        sort: PredictionSort = "volume_24h",
+        limit: int = 10,
+        after_cursor: str | None = None,
+    ) -> EventPage:
+        order, ascending = _EVENT_SORT.get(
+            sort, _EVENT_SORT["volume_24h"]
+        )
+        params = _params(
+            {
+                "limit": max(1, min(int(limit), 100)),
+                "closed": _bool_param(closed),
+                "order": order,
+                "ascending": _bool_param(ascending),
+                "tag_id": tag_id,
+                "tag_slug": tag_slug,
+                "after_cursor": after_cursor,
+            }
+        )
+        data = await self._get_json(
+            self._gamma_url, "/events/keyset", params, ttl=30.0
+        )
+        payload = _as_dict(data)
+        return EventPage(
+            items=[
+                _to_event_summary(event)
+                for event in _as_list(payload.get("events"))
+                if isinstance(event, Mapping)
+            ],
+            next_cursor=_as_str(payload.get("next_cursor")),
+        )
+
+    async def get_event(self, identifier: str) -> EventDetail:
+        identifier = identifier.strip()
+        if not identifier:
+            raise PolymarketNotFound("An event id or slug is required.")
+        safe_identifier = quote(identifier, safe="")
+        path = (
+            f"/events/{safe_identifier}"
+            if identifier.isdigit()
+            else f"/events/slug/{safe_identifier}"
+        )
+        data = await self._get_json(self._gamma_url, path, ttl=30.0)
+        payload = _as_dict(data)
+        if not payload:
+            raise PolymarketUpstreamError("Polymarket returned an empty event.")
+        return _to_event_detail(payload)
+
+    async def list_markets(
+        self,
+        *,
+        tag_id: int | None = None,
+        tag_slug: str | None = None,
+        closed: bool = False,
+        sort: PredictionSort = "volume_24h",
+        limit: int = 10,
+        after_cursor: str | None = None,
+    ) -> MarketPage:
+        if tag_id is None and tag_slug:
+            tag = await self.get_tag(tag_slug)
+            try:
+                tag_id = int(tag.id)
+            except ValueError as exc:
+                raise PolymarketUpstreamError(
+                    f"Polymarket returned a non-numeric tag id for '{tag_slug}'."
+                ) from exc
+
+        order, ascending = _MARKET_SORT.get(
+            sort, _MARKET_SORT["volume_24h"]
+        )
+        params = _params(
+            {
+                "limit": max(1, min(int(limit), 100)),
+                "closed": _bool_param(closed),
+                "order": order,
+                "ascending": _bool_param(ascending),
+                "tag_id": tag_id,
+                "after_cursor": after_cursor,
+            }
+        )
+        data = await self._get_json(
+            self._gamma_url, "/markets/keyset", params, ttl=30.0
+        )
+        payload = _as_dict(data)
+        return MarketPage(
+            items=[
+                _to_market_summary(market)
+                for market in _as_list(payload.get("markets"))
+                if isinstance(market, Mapping)
+            ],
+            next_cursor=_as_str(payload.get("next_cursor")),
+        )
+
+    async def get_market(self, identifier: str) -> MarketDetail:
+        identifier = identifier.strip()
+        if not identifier:
+            raise PolymarketNotFound("A market id or slug is required.")
+        safe_identifier = quote(identifier, safe="")
+        path = (
+            f"/markets/{safe_identifier}"
+            if identifier.isdigit()
+            else f"/markets/slug/{safe_identifier}"
+        )
+        data = await self._get_json(
+            self._gamma_url, path, {"include_tag": "true"}, ttl=30.0
+        )
+        payload = _as_dict(data)
+        if not payload:
+            raise PolymarketUpstreamError("Polymarket returned an empty market.")
+        return _to_market_detail(payload)
+
+    async def search(
+        self,
+        query: str,
+        *,
+        limit_per_type: int = 5,
+        include_tags: bool = True,
+    ) -> SearchResult:
+        query = query.strip()
+        if not query:
+            raise PolymarketNotFound("A search query is required.")
+        params = _params(
+            {
+                "q": query,
+                "limit_per_type": max(1, min(int(limit_per_type), 50)),
+                "search_profiles": "false",
+                "search_tags": _bool_param(include_tags),
+            }
+        )
+        data = await self._get_json(
+            self._gamma_url, "/public-search", params, ttl=60.0
+        )
+        payload = _as_dict(data)
+        return SearchResult(
+            query=query,
+            events=[
+                _to_event_summary(event)
+                for event in _as_list(payload.get("events"))
+                if isinstance(event, Mapping)
+            ],
+            tags=[
+                _to_tag(tag)
+                for tag in _as_list(payload.get("tags"))
+                if isinstance(tag, Mapping)
+            ],
+            pagination=_to_search_pagination(
+                _as_dict(payload.get("pagination")) or None
+            ),
+        )
+
+    async def list_tags(self, *, limit: int = 100, offset: int = 0) -> list[TagOut]:
+        params = _params(
+            {
+                "limit": max(1, min(int(limit), 500)),
+                "offset": max(0, int(offset)),
+            }
+        )
+        data = await self._get_json(self._gamma_url, "/tags", params, ttl=300.0)
+        raw_tags = (
+            data
+            if isinstance(data, list)
+            else _as_list(_as_dict(data).get("tags"))
+        )
+        return [
+            _to_tag(tag)
+            for tag in raw_tags
+            if isinstance(tag, Mapping)
+        ]
+
+    async def get_tag(self, slug: str) -> TagOut:
+        slug = slug.strip()
+        if not slug:
+            raise PolymarketNotFound("A tag slug is required.")
+        data = await self._get_json(
+            self._gamma_url, f"/tags/slug/{quote(slug, safe='')}", ttl=300.0
+        )
+        payload = _as_dict(data)
+        if not payload:
+            raise PolymarketNotFound(f"Polymarket tag '{slug}' was not found.")
+        return _to_tag(payload)
+
+    async def get_order_book(self, token_id: str, *, depth: int = 10) -> OrderBook:
+        token_id = token_id.strip()
+        if not token_id:
+            raise PolymarketNotFound("A token id is required.")
+        data = await self._get_json(
+            self._clob_url,
+            "/book",
+            {"token_id": token_id},
+            ttl=5.0,
+        )
+        payload = _as_dict(data)
+        if not payload:
+            raise PolymarketUpstreamError("Polymarket returned an empty order book.")
+        return _to_order_book(payload, token_id, depth)
+
+    async def get_token_price(
+        self, token_id: str, *, side: OrderSide = "BUY"
+    ) -> TokenPrice:
+        token_id = token_id.strip()
+        if not token_id:
+            raise PolymarketNotFound("A token id is required.")
+        data = await self._get_json(
+            self._clob_url,
+            "/price",
+            {"token_id": token_id, "side": side},
+            ttl=5.0,
+        )
+        payload = _as_dict(data)
+        price = _as_float(payload.get("price"))
+        if price is None:
+            raise PolymarketUpstreamError(
+                "Polymarket returned an invalid token price."
+            )
+        return TokenPrice(token_id=token_id, side=side, price=price)
+
+    async def get_price_history(
+        self,
+        token_id: str,
+        *,
+        interval: PriceInterval = "1d",
+        fidelity: int | None = None,
+    ) -> PriceHistory:
+        token_id = token_id.strip()
+        if not token_id:
+            raise PolymarketNotFound("A token id is required.")
+        params = _params(
+            {
+                "market": token_id,
+                "interval": interval,
+                "fidelity": fidelity,
+            }
+        )
+        data = await self._get_json(
+            self._clob_url, "/prices-history", params, ttl=60.0
+        )
+        payload = _as_dict(data)
+
+        points: list[PricePoint] = []
+        for item in _as_list(payload.get("history")):
+            if not isinstance(item, Mapping):
+                continue
+            timestamp = _as_int(item.get("t"))
+            price = _as_float(item.get("p"))
+            point_time = _as_datetime(timestamp)
+            if timestamp is None or price is None or point_time is None:
+                continue
+            points.append(
+                PricePoint(timestamp=timestamp, time=point_time, price=price)
+            )
+
+        return PriceHistory(token_id=token_id, interval=interval, points=points)
+
+    async def get_market_books(
+        self, identifier: str, *, depth: int = 10
+    ) -> MarketBooks:
+        market = await self.get_market(identifier)
+        token_ids = list(
+            dict.fromkeys(
+                outcome.token_id
+                for outcome in market.outcomes
+                if outcome.token_id
+            )
+        )
+        books = await asyncio.gather(
+            *(self.get_order_book(token_id, depth=depth) for token_id in token_ids)
+        )
+        return MarketBooks(
+            market_id=market.id,
+            question=market.question,
+            books=list(books),
+        )
+
+
+_default_client: PolymarketClient | None = None
+
+
+def get_polymarket_client() -> PolymarketClient:
+    """Return the process-wide client, creating it lazily."""
+    global _default_client
+    if _default_client is None:
+        _default_client = PolymarketClient()
+    return _default_client
+
+
+async def close_polymarket_client() -> None:
+    """Close the process-wide client. Safe to call more than once."""
+    global _default_client
+    client = _default_client
+    _default_client = None
+    if client is not None:
+        await client.aclose()
+
+
+async def list_events(
+    *,
+    tag_id: int | None = None,
+    tag_slug: str | None = None,
+    closed: bool = False,
+    sort: PredictionSort = "volume_24h",
+    limit: int = 10,
+    after_cursor: str | None = None,
+) -> EventPage:
+    return await get_polymarket_client().list_events(
+        tag_id=tag_id,
+        tag_slug=tag_slug,
+        closed=closed,
+        sort=sort,
+        limit=limit,
+        after_cursor=after_cursor,
+    )
+
+
+async def get_event(identifier: str) -> EventDetail:
+    return await get_polymarket_client().get_event(identifier)
+
+
+async def list_markets(
+    *,
+    tag_id: int | None = None,
+    tag_slug: str | None = None,
+    closed: bool = False,
+    sort: PredictionSort = "volume_24h",
+    limit: int = 10,
+    after_cursor: str | None = None,
+) -> MarketPage:
+    return await get_polymarket_client().list_markets(
+        tag_id=tag_id,
+        tag_slug=tag_slug,
+        closed=closed,
+        sort=sort,
+        limit=limit,
+        after_cursor=after_cursor,
+    )
+
+
+async def get_market(identifier: str) -> MarketDetail:
+    return await get_polymarket_client().get_market(identifier)
+
+
+async def search(
+    query: str,
+    *,
+    limit_per_type: int = 5,
+    include_tags: bool = True,
+) -> SearchResult:
+    return await get_polymarket_client().search(
+        query,
+        limit_per_type=limit_per_type,
+        include_tags=include_tags,
+    )
+
+
+async def list_tags(*, limit: int = 100, offset: int = 0) -> list[TagOut]:
+    return await get_polymarket_client().list_tags(limit=limit, offset=offset)
+
+
+async def get_tag(slug: str) -> TagOut:
+    return await get_polymarket_client().get_tag(slug)
+
+
+async def get_order_book(token_id: str, *, depth: int = 10) -> OrderBook:
+    return await get_polymarket_client().get_order_book(token_id, depth=depth)
+
+
+async def get_token_price(
+    token_id: str, *, side: OrderSide = "BUY"
+) -> TokenPrice:
+    return await get_polymarket_client().get_token_price(token_id, side=side)
+
+
+async def get_price_history(
+    token_id: str,
+    *,
+    interval: PriceInterval = "1d",
+    fidelity: int | None = None,
+) -> PriceHistory:
+    return await get_polymarket_client().get_price_history(
+        token_id,
+        interval=interval,
+        fidelity=fidelity,
+    )
+
+
+async def get_market_books(identifier: str, *, depth: int = 10) -> MarketBooks:
+    return await get_polymarket_client().get_market_books(identifier, depth=depth)