polypulse 0.1.0__tar.gz

polypulse-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check polypulse tests
+      - run: mypy polypulse
+      - run: pytest -q

polypulse-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

polypulse-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

polypulse-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 — 2026-06-27
+- Initial release: `BookFeed` real-time Polymarket order book over WebSocket.
+- Heartbeat, PONG-aware watchdog, exponential-backoff reconnect, REST fallback.
+- `OrderBook` model with best bid/ask, mid, spread, depth.
+- Market discovery: `list_markets` / `tokens_for_slug`.
+- CLI: `polypulse benchmark`, `polypulse watch`, `polypulse markets`.

polypulse-0.1.0/LAUNCH.md

@@ -0,0 +1,43 @@
+# Launch checklist — polypulse
+
+## Pre-flight (must all be true before announcing)
+- [ ] `pip install polypulse` works from a clean venv
+- [ ] README hook shows REAL benchmark numbers from `python -m polypulse benchmark`
+- [ ] A short GIF/asciinema of `polypulse watch <token>` is embedded in the README
+- [ ] CI is green on 3.10/3.11/3.12
+- [ ] Published to PyPI (version 0.1.0)
+- [ ] GitHub repo description + topics set:
+      polymarket, prediction-markets, orderbook, websocket, clob, low-latency, asyncio, trading, python
+
+## Announce (in order of signal)
+- [ ] Polymarket Discord — builders/dev channel
+- [ ] X/Twitter thread (draft below)
+- [ ] Show HN (draft below) — post a weekday morning US time
+- [ ] Reddit: r/algotrading, r/Polymarket, r/Python (show-and-tell)
+- [ ] PRs to awesome lists: awesome-quant, awesome-asyncio, awesome-polymarket (if it exists)
+
+## After
+- [ ] Respond to every issue/PR within ~24h for the first 2 weeks
+- [ ] Pin 1-2 "good first issue"s
+- [ ] Optional: dev.to/Medium write-up of the latency findings, linked from README
+
+---
+
+## Show HN draft
+**Title:** Show HN: polypulse - a never-freezing real-time order book for Polymarket
+
+I built this for a Polymarket trading bot. The trading edge didn't survive contact
+with reality, but the infrastructure did: a low-latency in-memory order book over
+WebSocket that reconnects itself when Polymarket's socket silently freezes (a real,
+documented failure mode). Reads are 0 ms (in-memory) vs ~19-80 ms per REST poll.
+MIT, pip-installable, tested. Happy to answer questions about the latency work.
+
+## X/Twitter thread draft
+1/ I open-sourced polypulse - a real-time Polymarket order book that never freezes.
+   pip install polypulse. Here's why it exists.
+2/ Reading the book via REST /book costs ~19-80 ms per call and is ~1 s stale.
+   Over WebSocket you get pushes ~sub-2 ms from the matching engine.
+3/ But Polymarket's WS can silently freeze - open connection, no events. polypulse
+   ships a PONG-aware watchdog + auto-reconnect + REST fallback so the book stays live.
+4/ Built it for a trading bot; the edge didn't pan out, the infra did. Take it.
+   MIT, typed, tested, CI. Star it: github.com/Gavr625/polypulse

polypulse-0.1.0/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.

polypulse-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,134 @@
+# 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/examples/print_top_of_book.py

@@ -0,0 +1,18 @@
+"""Print top-of-book for one token once the feed warms up."""
+
+import asyncio
+
+from polypulse import BookFeed
+
+TOKEN = "REPLACE_WITH_A_CLOB_TOKEN_ID"
+
+
+async def main() -> None:
+    feed = BookFeed([TOKEN])
+    asyncio.create_task(feed.run())
+    await asyncio.sleep(2)
+    print("bid", feed.best_bid(TOKEN), "ask", feed.best_ask(TOKEN), "mid", feed.mid(TOKEN))
+    feed.stop()
+
+
+asyncio.run(main())

polypulse-0.1.0/examples/react_to_updates.py

@@ -0,0 +1,19 @@
+"""React to every book update via a callback."""
+
+import asyncio
+
+from polypulse import BookFeed
+
+TOKEN = "REPLACE_WITH_A_CLOB_TOKEN_ID"
+
+
+def on_update(token_id: str, event: dict) -> None:
+    print(event["event_type"], token_id)
+
+
+async def main() -> None:
+    feed = BookFeed([TOKEN], on_update=on_update)
+    await asyncio.gather(feed.run())
+
+
+asyncio.run(main())

polypulse-0.1.0/examples/run_benchmark.py

@@ -0,0 +1,7 @@
+"""Run the latency benchmark (equivalent to `python -m polypulse benchmark`)."""
+
+import asyncio
+
+from polypulse.benchmark import run_benchmark
+
+asyncio.run(run_benchmark())

polypulse-0.1.0/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-0.1.0/polypulse/__main__.py

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

polypulse-0.1.0/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-0.1.0/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