polypulse 0.1.0__py3-none-any.whl

polypulse/__init__.py

@@ -0,0 +1,15 @@
+"""polypulse — real-time Polymarket order-book feed."""
+
+from .feed import BookFeed
+from .markets import Market, list_markets, tokens_for_slug
+from .orderbook import OrderBook
+
+__version__ = "0.1.0"
+__all__ = [
+    "BookFeed",
+    "Market",
+    "OrderBook",
+    "list_markets",
+    "tokens_for_slug",
+    "__version__",
+]

polypulse/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

polypulse/benchmark.py

@@ -0,0 +1,107 @@
+"""Latency benchmark: WebSocket push vs REST /book TTFB on a live market."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import statistics
+import time
+from typing import Any
+
+import websockets
+
+from .feed import WS_URL
+from .rest import fetch_book, get_json
+
+GAMMA = (
+    "https://gamma-api.polymarket.com/events"
+    "?tag_slug=weather&limit=80&order=createdAt&ascending=false"
+)
+GAMMA_FALLBACK = (
+    "https://gamma-api.polymarket.com/events"
+    "?limit=80&order=createdAt&ascending=false"
+)
+
+
+def pick_active_market(
+    events: list[dict[str, Any]], min_tokens: int = 4
+) -> tuple[str, list[str]] | None:
+    """From Gamma events, return (slug, [first token per market]) for the first
+    event exposing at least ``min_tokens`` open markets."""
+    for ev in events:
+        slug = ev.get("slug", "")
+        tokens: list[str] = []
+        for m in ev.get("markets", []):
+            if m.get("closed") or m.get("active") is False:
+                continue
+            cti = m.get("clobTokenIds")
+            if isinstance(cti, str):
+                try:
+                    cti = json.loads(cti)
+                except Exception:
+                    continue
+            if cti:
+                tokens.append(str(cti[0]))
+        if len(tokens) >= min_tokens:
+            return slug, tokens
+    return None
+
+
+async def run_benchmark() -> None:
+    print("=== Polymarket CLOB: WebSocket push vs REST poll latency ===\n")
+    picked = pick_active_market(get_json(GAMMA))
+    if not picked:
+        picked = pick_active_market(get_json(GAMMA_FALLBACK))
+    if not picked:
+        print("no active market found")
+        return
+    slug, tokens = picked
+    one = tokens[0]
+    print(f"market: {slug}  ({len(tokens)} tokens)\n")
+
+    rest_ms: list[float] = []
+    for _ in range(8):
+        t0 = time.time()
+        try:
+            fetch_book(one)
+            rest_ms.append((time.time() - t0) * 1000)
+        except Exception as exc:
+            print(f"  REST err: {exc}")
+        await asyncio.sleep(0.3)
+    if rest_ms:
+        print(f"REST /book TTFB: median {statistics.median(rest_ms):.1f}ms  "
+              f"min {min(rest_ms):.1f}  max {max(rest_ms):.1f}  (n={len(rest_ms)})")
+
+    first_book_ms: float | None = None
+    update_count = 0
+    async with websockets.connect(WS_URL, ping_interval=None, open_timeout=10) as ws:
+        sub_msg = json.dumps(
+            {"assets_ids": tokens, "type": "market", "custom_feature_enabled": True}
+        )
+        await ws.send(sub_msg)
+        t_sub = time.time()
+        deadline = t_sub + 30
+        while time.time() < deadline:
+            try:
+                raw = await asyncio.wait_for(ws.recv(), timeout=max(0.1, deadline - time.time()))
+            except asyncio.TimeoutError:
+                break
+            if raw == "PONG":
+                continue
+            data = json.loads(raw)
+            for ev in (data if isinstance(data, list) else [data]):
+                et = ev.get("event_type")
+                if et == "book" and first_book_ms is None:
+                    first_book_ms = (time.time() - t_sub) * 1000
+                if et in ("book", "price_change"):
+                    update_count += 1
+
+    elapsed = time.time() - t_sub
+    if first_book_ms is not None:
+        print(f"\nWS subscribe → first book: {first_book_ms:.1f}ms")
+    rate = update_count / elapsed if elapsed > 0 else 0.0
+    print(f"WS updates in {elapsed:.0f}s: {update_count} ({rate:.1f}/s)")
+    if rest_ms and first_book_ms is not None:
+        print("\n=== verdict ===")
+        print(f"REST pays ~{statistics.median(rest_ms):.0f}ms EVERY read; "
+              f"WS pays {first_book_ms:.0f}ms ONCE, then updates are PUSHED (no per-read latency).")

polypulse/cli.py

@@ -0,0 +1,59 @@
+"""Command-line interface: `polypulse benchmark`, `polypulse watch`, `polypulse markets`."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+
+from .benchmark import run_benchmark
+from .feed import BookFeed
+from .markets import list_markets
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="polypulse", description="Real-time Polymarket order-book feed."
+    )
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("benchmark", help="measure WS push vs REST /book latency on a live market")
+    watch = sub.add_parser("watch", help="stream and print top-of-book for token ids")
+    watch.add_argument("tokens", nargs="+", help="one or more CLOB token ids")
+    mk = sub.add_parser("markets", help="list active Polymarket markets and their token ids")
+    mk.add_argument("--tag", default=None, help="Gamma tag_slug filter, e.g. 'weather'")
+    mk.add_argument("--limit", type=int, default=100, help="max events to fetch")
+    return parser
+
+
+async def _watch(tokens: list[str]) -> None:
+    feed = BookFeed(tokens)
+    task = asyncio.create_task(feed.run())
+    try:
+        while True:
+            await asyncio.sleep(1.0)
+            for t in tokens:
+                print(
+                    f"{t[:10]}…  bid={feed.best_bid(t)}  ask={feed.best_ask(t)}  "
+                    f"mid={feed.mid(t)}  src={feed.source(t)}"
+                )
+    finally:
+        feed.stop()
+        task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "benchmark":
+            asyncio.run(run_benchmark())
+        elif args.command == "watch":
+            asyncio.run(_watch(args.tokens))
+        elif args.command == "markets":
+            for m in list_markets(tag=args.tag, limit=args.limit):
+                print(f"{m.slug}\n  q: {m.question}\n  tokens: {m.token_ids}")
+        else:
+            parser.print_help()
+    except KeyboardInterrupt:
+        pass
+    return 0

polypulse/feed.py

@@ -0,0 +1,284 @@
+"""Real-time Polymarket order-book feed over WebSocket."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+import websockets
+
+from .orderbook import OrderBook
+from .rest import fetch_book
+
+WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"
+
+UpdateCallback = Callable[[str, dict[str, Any]], Any]
+
+
+class BookFeed:
+    """Maintains a live in-memory order book for a fixed set of token ids.
+
+    Reads (:meth:`best_bid`, :meth:`mid`, …) are synchronous and never touch
+    the network. Call :meth:`run` (a coroutine) to keep the book fresh.
+    """
+
+    def __init__(
+        self,
+        token_ids: list[str],
+        on_update: UpdateCallback | None = None,
+        *,
+        ping_interval: float = 10.0,
+        watchdog_timeout: float = 30.0,
+        rest_fallback: bool = True,
+        max_backoff: float = 30.0,
+        rest_poll_interval: float = 1.0,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        self.token_ids = [str(t) for t in token_ids]
+        self.on_update = on_update
+        self.ping_interval = ping_interval
+        self.watchdog_timeout = watchdog_timeout
+        self.rest_fallback = rest_fallback
+        self.max_backoff = max_backoff
+        self.rest_poll_interval = rest_poll_interval
+        self.logger = logger or logging.getLogger("polypulse")
+
+        self.books: dict[str, OrderBook] = {}
+        self._stop = False
+        self._wake = asyncio.Event()
+        self._connected = False
+        self._last_frame_ts = 0.0
+        self._ws: Any = None
+        self._pending: set[asyncio.Task[Any]] = set()
+
+    # ----- reads (sync, no network) -----
+
+    def _ob(self, token_id: str) -> OrderBook | None:
+        return self.books.get(str(token_id))
+
+    def best_bid(self, token_id: str) -> float | None:
+        ob = self._ob(token_id)
+        return ob.best_bid() if ob else None
+
+    def best_ask(self, token_id: str) -> float | None:
+        ob = self._ob(token_id)
+        return ob.best_ask() if ob else None
+
+    def mid(self, token_id: str) -> float | None:
+        ob = self._ob(token_id)
+        return ob.mid() if ob else None
+
+    def spread(self, token_id: str) -> float | None:
+        ob = self._ob(token_id)
+        return ob.spread() if ob else None
+
+    def book(self, token_id: str) -> OrderBook | None:
+        ob = self._ob(token_id)
+        return ob.snapshot() if ob else None
+
+    def staleness(self, token_id: str) -> float | None:
+        ob = self._ob(token_id)
+        return (time.time() - ob.ts) if ob else None
+
+    def source(self, token_id: str) -> str | None:
+        ob = self._ob(token_id)
+        return ob.source if ob else None
+
+    # ----- event handling -----
+
+    def _handle(self, raw: str) -> None:
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, UnicodeDecodeError, TypeError):
+            self.logger.debug("polypulse: dropped unparseable frame")
+            return
+        events = data if isinstance(data, list) else [data]
+        now = time.time()
+        for ev in events:
+            if not isinstance(ev, dict):
+                continue
+            try:
+                et = ev.get("event_type")
+                if et == "book":
+                    aid = ev.get("asset_id")
+                    if not aid:
+                        continue
+                    ob = self.books.get(aid)
+                    if ob is None:
+                        ob = OrderBook()
+                    ob.apply_snapshot(ev.get("bids"), ev.get("asks"), now, "ws")
+                    self.books[aid] = ob
+                    self._fire(aid, ev)
+                elif et == "price_change":
+                    affected: set[str] = set()
+                    for pc in ev.get("price_changes") or []:
+                        aid = pc.get("asset_id")
+                        ob = self.books.get(aid) if aid else None
+                        if ob is None:
+                            continue
+                        ob.apply_change(
+                            pc.get("side", ""), pc.get("price", ""),
+                            float(pc.get("size", 0)), now, "ws",
+                        )
+                        affected.add(aid)
+                    for aid in affected:
+                        self._fire(aid, ev)
+                else:
+                    aid = ev.get("asset_id")
+                    if aid:
+                        self._fire(aid, ev)
+            except (ValueError, TypeError, KeyError):
+                self.logger.debug("polypulse: dropped malformed event")
+                continue
+
+    def _fire(self, token_id: str, event: dict[str, Any]) -> None:
+        if self.on_update is None:
+            return
+        try:
+            result = self.on_update(token_id, event)
+        except Exception:
+            self.logger.exception("polypulse: on_update callback raised")
+            return
+        if inspect.isawaitable(result):
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                # No running loop (sync caller): run to completion in a fresh loop.
+                try:
+                    asyncio.run(self._await_cb(result))
+                except Exception:
+                    self.logger.exception("polypulse: async on_update callback raised")
+                return
+            task = loop.create_task(self._await_cb(result))
+            self._pending.add(task)
+            task.add_done_callback(self._pending.discard)
+
+    async def _await_cb(self, awaitable: Any) -> None:
+        try:
+            await awaitable
+        except Exception:
+            self.logger.exception("polypulse: async on_update callback raised")
+
+    # ----- heartbeat & watchdog -----
+
+    async def _heartbeat(self, ws: Any) -> None:
+        try:
+            while True:
+                await asyncio.sleep(self.ping_interval)
+                await ws.send("PING")
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            return  # socket dying during teardown — exit quietly
+
+    async def _watchdog(self, ws: Any) -> None:
+        interval = max(0.005, min(5.0, self.watchdog_timeout / 3))
+        try:
+            while True:
+                await asyncio.sleep(interval)
+                if time.time() - self._last_frame_ts > self.watchdog_timeout:
+                    self.logger.debug("polypulse: watchdog tripped, forcing reconnect")
+                    try:
+                        await ws.close()
+                    except Exception:
+                        pass
+                    return
+        except asyncio.CancelledError:
+            pass
+
+    # ----- REST fallback -----
+
+    def _apply_rest(self, token_id: str, data: dict[str, Any]) -> None:
+        ob = self.books.get(token_id)
+        if ob is None:
+            ob = OrderBook()
+        ob.apply_snapshot(data.get("bids"), data.get("asks"), time.time(), "rest")
+        self.books[token_id] = ob
+
+    async def _rest_fallback_loop(self) -> None:
+        if not self.rest_fallback:
+            return
+        loop = asyncio.get_running_loop()
+        while not self._stop:
+            await asyncio.sleep(self.rest_poll_interval)
+            if self._connected:
+                continue
+            for tid in self.token_ids:
+                try:
+                    data = await loop.run_in_executor(None, fetch_book, tid)
+                    self._apply_rest(tid, data)
+                except Exception as exc:
+                    self.logger.debug("polypulse: rest fallback failed for %s: %s", tid, exc)
+
+    # ----- connection loop -----
+
+    def stop(self) -> None:
+        self._stop = True
+        self._wake.set()
+        ws = self._ws
+        if ws is not None:
+            try:
+                task = asyncio.get_running_loop().create_task(ws.close())
+            except RuntimeError:
+                return  # no running loop; loop already stopped, close is moot
+            self._pending.add(task)
+            task.add_done_callback(self._pending.discard)
+
+    def _subscribe_msg(self) -> str:
+        return json.dumps({
+            "assets_ids": self.token_ids,
+            "type": "market",
+            "custom_feature_enabled": True,
+        })
+
+    async def run(self) -> None:
+        """Maintain the connection until :meth:`stop`, reconnecting with
+        exponential backoff and resubscribing each time. While the socket is
+        down, the optional REST fallback keeps books warm. :meth:`stop` closes
+        the active connection for prompt shutdown."""
+        rest_task = asyncio.create_task(self._rest_fallback_loop())
+        try:
+            backoff = 0.5
+            while not self._stop:
+                try:
+                    async with websockets.connect(
+                        WS_URL, ping_interval=None, open_timeout=10, close_timeout=5
+                    ) as ws:
+                        await ws.send(self._subscribe_msg())
+                        self._connected = True
+                        self._ws = ws
+                        self._last_frame_ts = time.time()
+                        backoff = 0.5
+                        hb = asyncio.create_task(self._heartbeat(ws))
+                        wd = asyncio.create_task(self._watchdog(ws))
+                        try:
+                            async for raw in ws:
+                                self._last_frame_ts = time.time()
+                                msg = (
+                                    raw if isinstance(raw, str)
+                                    else raw.decode("utf-8", "replace")
+                                )
+                                if msg == "PONG":
+                                    continue
+                                self._handle(msg)
+                        finally:
+                            hb.cancel()
+                            wd.cancel()
+                            self._connected = False
+                            self._ws = None
+                except Exception as exc:
+                    self.logger.debug("polypulse: ws error, will reconnect: %s", exc)
+                if self._stop:
+                    break
+                try:
+                    await asyncio.wait_for(self._wake.wait(), timeout=backoff)
+                except asyncio.TimeoutError:
+                    pass
+                backoff = min(backoff * 2, self.max_backoff)
+        finally:
+            rest_task.cancel()

polypulse/markets.py

@@ -0,0 +1,97 @@
+"""Market discovery via the Polymarket Gamma API."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+from .rest import get_json
+
+GAMMA_EVENTS = "https://gamma-api.polymarket.com/events"
+
+
+@dataclass
+class Market:
+    slug: str
+    question: str
+    condition_id: str
+    token_ids: list[str]
+    outcomes: list[str]
+    end_date: str | None = None
+    volume_24h: float | None = None
+
+
+def _as_list(value: Any) -> list[Any]:
+    """Gamma sometimes returns list-ish fields as JSON-encoded strings."""
+    if isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except Exception:
+            return []
+    return value if isinstance(value, list) else []
+
+
+def _to_float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def list_markets(
+    tag: str | None = None,
+    *,
+    closed: bool = False,
+    limit: int = 100,
+    timeout: float = 20.0,
+) -> list[Market]:
+    """Fetch markets from the Polymarket Gamma events API.
+
+    Args:
+        tag: optional Gamma ``tag_slug`` filter (e.g. ``"weather"``).
+        closed: include closed/inactive markets too (default: only open).
+        limit: max events to request.
+
+    Returns a flat list of :class:`Market`. Markets without parseable token ids are
+    skipped. Raises ``urllib.error.URLError`` on network failure.
+    """
+    url = f"{GAMMA_EVENTS}?limit={int(limit)}&order=createdAt&ascending=false"
+    if tag:
+        url += f"&tag_slug={quote(tag, safe='')}"
+    events = get_json(url, timeout=timeout)
+    out: list[Market] = []
+    for ev in events if isinstance(events, list) else []:
+        if not isinstance(ev, dict):
+            continue
+        ev_slug = str(ev.get("slug", ""))
+        for m in ev.get("markets") or []:
+            if not isinstance(m, dict):
+                continue
+            if not closed and (m.get("closed") or m.get("active") is False):
+                continue
+            token_ids = [str(t) for t in _as_list(m.get("clobTokenIds"))]
+            if not token_ids:
+                continue
+            ed = m.get("endDate") or ev.get("endDate")
+            out.append(
+                Market(
+                    slug=str(m.get("slug") or ev_slug),
+                    question=str(m.get("question") or ev.get("title") or ""),
+                    condition_id=str(m.get("conditionId") or ""),
+                    token_ids=token_ids,
+                    outcomes=[str(o) for o in _as_list(m.get("outcomes"))],
+                    end_date=str(ed) if ed is not None else None,
+                    volume_24h=_to_float(m.get("volume24hr")),
+                )
+            )
+    return out
+
+
+def tokens_for_slug(markets: list[Market], slug: str) -> list[str]:
+    """Return the token ids of the first market whose slug equals ``slug`` (else [])."""
+    for m in markets:
+        if m.slug == slug:
+            return list(m.token_ids)
+    return []

polypulse/orderbook.py

@@ -0,0 +1,99 @@
+"""Pure in-memory order-book model. No IO."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class OrderBook:
+    """One market's order book. Prices are kept as strings (exchange-native),
+    sizes as floats. Best bid/ask are cached on mutation for O(1) reads."""
+
+    bids: dict[str, float] = field(default_factory=dict)
+    asks: dict[str, float] = field(default_factory=dict)
+    ts: float = 0.0
+    source: str = "ws"  # "ws" | "rest"
+    _best_bid: float | None = field(default=None, init=False, repr=False)
+    _best_ask: float | None = field(default=None, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._recompute()
+
+    def apply_snapshot(
+        self,
+        bids: list[dict[str, Any]] | None,
+        asks: list[dict[str, Any]] | None,
+        ts: float,
+        source: str = "ws",
+    ) -> None:
+        self.bids = self._build_side(bids)
+        self.asks = self._build_side(asks)
+        self.ts = ts
+        self.source = source
+        self._recompute()
+
+    @staticmethod
+    def _build_side(levels: list[dict[str, Any]] | None) -> dict[str, float]:
+        out: dict[str, float] = {}
+        for lvl in levels or []:
+            try:
+                price = str(lvl["price"])
+                size = float(lvl["size"])
+                float(price)  # ensure the price key is numeric so _recompute can't choke
+            except (KeyError, TypeError, ValueError):
+                continue
+            if size > 0:
+                out[price] = size
+        return out
+
+    def apply_change(
+        self, side: str, price: str, size: float, ts: float, source: str = "ws"
+    ) -> None:
+        if side == "BUY":
+            book = self.bids
+        elif side == "SELL":
+            book = self.asks
+        else:
+            return  # unknown side: ignore rather than corrupt a side
+        try:
+            float(price)
+        except (TypeError, ValueError):
+            return  # unparseable price: skip rather than poison the book
+        if size <= 0:
+            book.pop(price, None)
+        else:
+            book[price] = size
+        self.ts = ts
+        self.source = source
+        self._recompute()
+
+    def _recompute(self) -> None:
+        self._best_bid = max((float(p) for p in self.bids), default=None)
+        self._best_ask = min((float(p) for p in self.asks), default=None)
+
+    def best_bid(self) -> float | None:
+        return self._best_bid
+
+    def best_ask(self) -> float | None:
+        return self._best_ask
+
+    def mid(self) -> float | None:
+        if self._best_bid is None or self._best_ask is None:
+            return None
+        return round((self._best_bid + self._best_ask) / 2, 10)
+
+    def spread(self) -> float | None:
+        if self._best_bid is None or self._best_ask is None:
+            return None
+        return self._best_ask - self._best_bid
+
+    def bid_levels(self) -> list[tuple[float, float]]:
+        return sorted(((float(p), s) for p, s in self.bids.items()), reverse=True)
+
+    def ask_levels(self) -> list[tuple[float, float]]:
+        return sorted((float(p), s) for p, s in self.asks.items())
+
+    def snapshot(self) -> OrderBook:
+        return OrderBook(bids=dict(self.bids), asks=dict(self.asks), ts=self.ts, source=self.source)

polypulse/rest.py

@@ -0,0 +1,33 @@
+"""Tiny stdlib REST helper for Polymarket CLOB /book (fallback + benchmark)."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from typing import Any
+from urllib.parse import quote
+
+REST_BOOK = "https://clob.polymarket.com/book?token_id="
+
+
+def get_json(url: str, timeout: float = 20.0) -> Any:
+    """Blocking GET returning parsed JSON. Raises ``urllib.error.URLError`` (or its
+    ``HTTPError`` subclass) on network/HTTP failure."""
+    req = urllib.request.Request(url, headers={"User-Agent": "polypulse"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (trusted host)
+        return json.load(resp)
+
+
+def fetch_book(token_id: str, timeout: float = 10.0) -> dict[str, Any]:
+    """Blocking GET of the order book for one token. Returns the parsed JSON
+    (keys include ``bids`` and ``asks``, each a list of ``{"price","size"}``).
+
+    Raises ``urllib.error.URLError`` (or its ``HTTPError`` subclass) on
+    network failures or non-success HTTP status codes."""
+    req = urllib.request.Request(
+        REST_BOOK + quote(token_id, safe=""),
+        headers={"User-Agent": "polypulse"},
+    )
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (trusted host)
+        data: dict[str, Any] = json.load(resp)
+    return data

polypulse-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: polypulse
+Version: 0.1.0
+Summary: Real-time pulse of Polymarket — an order book feed that never freezes.
+Project-URL: Homepage, https://github.com/Gavr625/polypulse
+Project-URL: Issues, https://github.com/Gavr625/polypulse/issues
+Author: Gavr625
+License: MIT
+License-File: LICENSE
+Keywords: asyncio,clob,low-latency,orderbook,polymarket,prediction-markets,trading,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# polypulse
+
+[![PyPI](https://img.shields.io/pypi/v/polypulse.svg)](https://pypi.org/project/polypulse/)
+[![CI](https://github.com/Gavr625/polypulse/actions/workflows/ci.yml/badge.svg)](https://github.com/Gavr625/polypulse/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Real-time pulse of Polymarket — an order book feed that never freezes.**
+
+`polypulse` keeps a live, in-memory Polymarket order book over WebSocket, so reading
+the best bid/ask is instant — with no per-read network round-trip. REST `/book` polling
+pays its latency on **every** read (≈185 ms from a typical host, ≈19 ms warm when
+colocated); `polypulse` pays a one-time subscribe, then updates are pushed.
+It adds the production reliability the official tooling lacks: heartbeat, a
+PONG-aware watchdog that detects the silent WS freeze ([issue #292](https://github.com/Polymarket/py-clob-client/issues/292)),
+exponential-backoff reconnect, and an optional REST fallback.
+
+## Install
+
+```bash
+pip install polypulse
+```
+
+## Quickstart
+
+```python
+import asyncio
+from polypulse import BookFeed
+
+async def main():
+    feed = BookFeed(["<token_id>"])
+    asyncio.create_task(feed.run())   # connects, reconnects, self-heals
+    await asyncio.sleep(2)
+    print(feed.best_bid("<token_id>"), feed.mid("<token_id>"))  # 0 ms, in-memory
+    feed.stop()
+
+asyncio.run(main())
+```
+
+## Discover markets
+
+No `token_id` yet? Find active markets and their tokens via the Gamma API:
+
+```python
+from polypulse import list_markets, tokens_for_slug, BookFeed
+
+markets = list_markets(tag="weather")              # active markets (tag is optional)
+tokens = tokens_for_slug(markets, markets[0].slug) # the token ids for one market
+feed = BookFeed(tokens)                             # ...now stream them
+```
+
+Or from the terminal:
+
+```bash
+polypulse markets --tag weather
+```
+
+## Why
+
+REST `/book` polling pays per-read latency and serves a book that is ~1 s stale.
+Polymarket's WebSocket can also **silently freeze** — the connection stays open but
+events stop. `polypulse` pushes updates as the book changes (no per-read latency) and
+guarantees liveness with a watchdog that reconnects the moment the socket goes quiet.
+
+## API
+
+`BookFeed(token_ids, on_update=None, *, ping_interval=10, watchdog_timeout=30, rest_fallback=True, max_backoff=30, rest_poll_interval=1.0, logger=None)`
+
+- `best_bid / best_ask / mid / spread (token_id)` — sync, no network
+- `book(token_id)` — full-depth `OrderBook` snapshot
+- `staleness(token_id)`, `source(token_id)` — freshness introspection
+- `await run()` / `stop()`
+
+### Behavior notes
+
+- **Reads are synchronous and never hit the network** — they return whatever the
+  background `run()` task has most recently applied.
+- **`source(token_id)`** is `"ws"` when the latest update came from the live socket,
+  or `"rest"` when it came from the REST fallback (used only while the WS is down).
+  `staleness(token_id)` is seconds since that token last updated.
+- **`on_update` fires on WebSocket events only.** While the socket is down, the REST
+  fallback keeps the book fresh for readers (`best_bid` etc.) but does not invoke the
+  callback; on reconnect you get a fresh `book` snapshot (which does fire it).
+- **`stop()`** signals shutdown and closes the active connection so `run()` returns
+  promptly.
+
+## Benchmark
+
+```bash
+python -m polypulse benchmark
+```
+
+It picks a live market and compares REST `/book` time-to-first-byte against the
+WebSocket feed. Example run (from a non-colocated host — your absolute numbers depend
+on where you run it):
+
+```
+market: highest-temperature-in-karachi-on-june-29-2026  (11 tokens)
+REST /book TTFB: median 184.5ms  min 124.4  max 238.3  (n=8)
+WS subscribe → first book: 220.6ms
+WS updates in 30s: 130 (4.3/s)
+
+=== verdict ===
+REST pays ~185ms EVERY read; WS pays 221ms ONCE, then updates are PUSHED (no per-read latency).
+```
+
+Absolute latency drops sharply when colocated (a eu-west-2 host measured ~19 ms warm
+REST GETs), but the structural win holds everywhere: REST pays its round-trip on every
+read; the WS feed pays once.
+
+## Watch a live book
+
+```bash
+polypulse watch <token_id>
+```
+
+Prints top-of-book once a second — a quick sanity check that the feed is live:
+
+```
+3414098972...  bid=0.012  ask=0.024  mid=0.018  src=ws
+3414098972...  bid=0.012  ask=0.024  mid=0.018  src=ws
+```
+
+Values tick as the market moves; `src` shows `ws` or `rest` (REST fallback). An
+animated GIF reads even better here — record one to drop in.
+
+## Honest note
+
+`polypulse` was extracted from a live Polymarket trading bot. The trading edge didn't
+pan out, but the low-latency feed is solid and battle-tested — so here it is. Out of
+scope (for now): generic multi-CLOB support, book integrity hashing, indicators.
+
+## License
+
+MIT.

polypulse-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+polypulse/__init__.py,sha256=cY0R0ppHEamU0M9Gy47Pf7a04VVpZ0VMWdZGxWf-b7Y,324
+polypulse/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+polypulse/benchmark.py,sha256=v6tKSVPeNAhSJxBxIb7nxCiDJtBevurOuAdaxB9Pkr8,3733
+polypulse/cli.py,sha256=jOANoCWQwq-t1Sg8Cpar2b5Up4-rHAeoxGxgJiXqlIs,2113
+polypulse/feed.py,sha256=5tH6NMdba-bU4h6vL3-GknATTECvyQzjRYM3GXLikgM,10494
+polypulse/markets.py,sha256=s2ZcMDMNnpIDvJzo71Ta3X1xRK441j__0cupi23EUKs,3033
+polypulse/orderbook.py,sha256=wQkwnfxlBYzNvkvmsjh9gC5IryK3efTbJPDCaHkiHMI,3306
+polypulse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+polypulse/rest.py,sha256=pXofDxMUcs6-frkpyt4OSSLkLU5cb9xFOGfEJwc2700,1304
+polypulse-0.1.0.dist-info/METADATA,sha256=AoFIfN4U2lq0nh1tWOT3yOYuJ1cfrP_i6JtSGdWWPT4,5949
+polypulse-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+polypulse-0.1.0.dist-info/entry_points.txt,sha256=CVMptO7VoI5eICkgFyycFTQmw3R9dhxb0V7xS_QqmMw,49
+polypulse-0.1.0.dist-info/licenses/LICENSE,sha256=59_EiXd42QgW3WnfBghxrMuXP7ZYGz8yJz3QRlosey0,1064
+polypulse-0.1.0.dist-info/RECORD,,

polypulse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

polypulse-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+polypulse = polypulse.cli:main

polypulse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavr625
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.