polyws 0.2.0__tar.gz

polyws-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

polyws-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/

polyws-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David
+
+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.

polyws-0.2.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: polyws
+Version: 0.2.0
+Summary: Real-time Polymarket CLOB WebSocket streaming for Python
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: orjson>=3.10
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# polyws
+
+Real-time Polymarket data streaming for Python. Built for trading bots, data pipelines, and AI agents.
+
+```bash
+pip install polyws
+```
+
+```bash
+polyws stream --markets 10
+```
+
+```python
+from polyws import WSSubscriptionManager, WebSocketHandlers
+
+stream = WSSubscriptionManager(WebSocketHandlers(
+    on_polymarket_price_update=lambda events: [
+        print(f"{e.asset_id[:16]}… {float(e.price)*100:.1f}%") for e in events
+    ]
+))
+await stream.add_subscriptions(["<asset-id>"])
+```
+
+---
+
+## Why polyws?
+
+Polymarket has two APIs, no official Python streaming library, and a multi-step lookup just to get real-time prices. polyws solves all of that.
+
+### The problem
+
+To stream live Polymarket data in Python today, you need to:
+
+1. Query the **Gamma API** to discover markets and extract `clobTokenIds`
+2. Connect to the **CLOB WebSocket** with a handshake protocol
+3. Manage subscriptions, reconnections, and ping/pong keepalive
+4. Maintain an order book cache to compute display prices
+5. Implement Polymarket's [price calculation logic](https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated#future-price) (midpoint when spread ≤ $0.10, last trade price otherwise)
+
+That's ~500 lines of async boilerplate before you write a single line of business logic.
+
+### What polyws gives you
+
+```python
+stream = WSSubscriptionManager(handlers)
+await stream.add_subscriptions(asset_ids)
+# Done. Events flow to your handlers.
+```
+
+- Automatic WebSocket connection, reconnection, and keepalive
+- Subscription batching with event-driven flush (no polling)
+- Order book cache with sorted bid/ask levels
+- Derived display prices matching the Polymarket UI
+- CLI for discovery and streaming without writing code
+- JSON Lines output for piping into other tools and agents
+
+### How it compares
+
+|  | polyws | [poly-websockets](https://github.com/nevuamarkets/poly-websockets) (TS) | [py-clob-client](https://github.com/Polymarket/py-clob-client) (official) | [polymarket-cli](https://github.com/polymarket/polymarket-cli) (Rust) |
+|--|--------|-------------------|----------------|-----------------|
+| Language | Python | TypeScript | Python | Rust |
+| Real-time streaming | WebSocket | WebSocket | REST only | REST only |
+| Auto-reconnect | Event-driven | Polling (5s interval) | N/A | N/A |
+| Subscription flush | Instant (`asyncio.Event`) | Polling (100ms interval) | N/A | N/A |
+| Display price logic | Built-in | Built-in | Manual | Manual |
+| Order book cache | `bisect.insort` | Full re-sort | None | None |
+| CLI | `polyws markets/stream` | None | None | Full trading CLI |
+| Agent-friendly output | JSON Lines (auto-detect) | None | None | `--output json` |
+| Trading / orders | No | No | Yes | Yes |
+| Runtime deps | 2 | 5 | 8+ | N/A (binary) |
+| Install | `pip install` | `npm install` | `pip install` | `brew install` |
+
+**polyws is not a trading client.** It does one thing — real-time data streaming — and does it well. Use it alongside `py-clob-client` for a complete Python trading stack.
+
+---
+
+## CLI
+
+### Browse markets
+
+```bash
+# Top 20 markets by volume
+polyws markets
+
+# Search
+polyws markets --search "bitcoin" --limit 5
+
+# Sort options: volume (default), liquidity, newest
+polyws markets --sort liquidity --limit 10
+```
+
+### Stream real-time data
+
+```bash
+# Stream top 10 markets
+polyws stream --markets 10
+
+# Stream specific assets
+polyws stream --asset-id 4655345557056451798919...
+
+# Search and stream
+polyws stream --search "election"
+```
+
+### Output format
+
+polyws auto-detects the output context:
+
+- **Terminal (TTY):** Human-readable, formatted, colored
+- **Piped / redirected:** JSON Lines — one JSON object per line
+
+```bash
+# Human output
+polyws markets --limit 3
+
+#  99.7%  $58.7M  Will there be no change in Fed rates...  [10255981...]
+#   0.2%  $53.5M  Will the Fed decrease rates by 25...     [62938043...]
+#   0.1%  $48.3M  Will the Fed decrease rates by 50+...    [46553455...]
+
+# Machine output (piped)
+polyws markets --limit 1 | jq .
+# {"asset_id": "102559...", "question": "Will there be...", "volume": 58739675, "price": "0.9965"}
+```
+
+This makes polyws natively usable by AI agents — pipe the output, parse the JSON, act on it.
+
+---
+
+## Library API
+
+### WSSubscriptionManager
+
+```python
+from polyws import WSSubscriptionManager, WebSocketHandlers
+
+handlers = WebSocketHandlers(
+    on_book=my_book_handler,
+    on_price_change=my_change_handler,
+    on_last_trade_price=my_trade_handler,
+    on_tick_size_change=my_tick_handler,
+    on_polymarket_price_update=my_price_handler,  # Derived display price
+    on_error=my_error_handler,
+    on_ws_open=my_open_handler,
+    on_ws_close=my_close_handler,
+)
+
+manager = WSSubscriptionManager(handlers, reconnect_interval_s=5.0)
+```
+
+All handlers are `async`, optional, and receive a list of typed events.
+
+| Method | Description |
+|--------|-------------|
+| `await add_subscriptions(ids)` | Subscribe to assets. Connects automatically. |
+| `await remove_subscriptions(ids)` | Unsubscribe from assets. |
+| `get_asset_ids()` | List all monitored assets. |
+| `get_statistics()` | Connection stats (`open_websockets`, `asset_ids`, `pending_subscribe`, `pending_unsubscribe`). |
+| `await clear_state()` | Full teardown. Manager is reusable after. |
+
+### Market Discovery
+
+```python
+from polyws import fetch_markets, extract_asset_ids
+
+markets = fetch_markets(limit=10, sort="volume", search="crypto")
+assets = extract_asset_ids(markets)  # {asset_id: question, ...}
+```
+
+### Event Types
+
+| Event | When | Key Fields |
+|-------|------|------------|
+| `BookEvent` | Full order book snapshot on subscribe | `bids`, `asks`, `asset_id` |
+| `PriceChangeEvent` | Order book level added/removed/updated | `price_changes[].side`, `price`, `size` |
+| `LastTradePriceEvent` | A trade executes | `price`, `side`, `size` |
+| `TickSizeChangeEvent` | Tick size changes | `old_tick_size`, `new_tick_size` |
+| `PolymarketPriceUpdateEvent` | Derived display price changes | `price`, `midpoint`, `spread`, `triggering_event` |
+
+### How display prices work
+
+Polymarket doesn't show raw bid/ask prices. It shows a **derived price**:
+
+- If bid-ask spread ≤ $0.10 → display the **midpoint**
+- If bid-ask spread > $0.10 → display the **last trade price**
+
+`on_polymarket_price_update` fires whenever this derived price changes. This matches what you see on polymarket.com.
+
+---
+
+## For AI Agents
+
+polyws is designed as a tool for AI agents that need real-time market intelligence.
+
+**As a CLI tool:**
+```bash
+# Agent discovers markets about a topic
+polyws markets --search "AI" --limit 5 | jq -r '.question'
+
+# Agent monitors prices and acts on thresholds
+polyws stream --search "bitcoin" | while read line; do
+  price=$(echo "$line" | jq -r 'select(.event=="price_update") | .price')
+  # ... agent logic ...
+done
+```
+
+**As a Python library:**
+```python
+# Agent builds a real-time market monitor
+from polyws import WSSubscriptionManager, WebSocketHandlers, fetch_markets, extract_asset_ids
+
+markets = fetch_markets(search="election", limit=20)
+assets = extract_asset_ids(markets)
+
+async def on_update(events):
+    for e in events:
+        if float(e.price) > 0.9:
+            await alert(f"High confidence: {assets[e.asset_id]} at {e.price}")
+
+mgr = WSSubscriptionManager(WebSocketHandlers(on_polymarket_price_update=on_update))
+await mgr.add_subscriptions(list(assets.keys()))
+```
+
+**Why agents prefer polyws over alternatives:**
+- JSON Lines output — no parsing HTML or tables
+- Zero config — no API keys needed for read-only streaming
+- Predictable schema — every event is typed and documented
+- Instant — WebSocket, not polling REST endpoints
+- Composable — pipe into `jq`, `grep`, other tools, or import as a library
+
+---
+
+## Architecture
+
+```
+polyws/
+├── src/polyws/
+│   ├── types.py        # Typed dataclasses for all events
+│   ├── order_book.py   # Sorted order book cache (bisect.insort)
+│   ├── manager.py      # WebSocket lifecycle, reconnect, flush
+│   ├── gamma.py        # Gamma API market discovery
+│   ├── cli.py          # CLI entry point (argparse)
+│   └── logger.py       # stdlib logging
+├── tests/              # 53 unit + integration tests
+└── examples/           # Ready-to-run scripts
+```
+
+**Runtime dependencies:** `websockets`, `orjson`. That's it.
+
+**Python:** >= 3.11
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/<org>/polyws.git
+cd polyws
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run live integration test (requires network)
+pytest -m live
+```
+
+---
+
+## Inspired by
+
+[poly-websockets](https://github.com/nevuamarkets/poly-websockets) by Nevua Markets — the TypeScript library that pioneered this approach. polyws is a Python rewrite with performance improvements (event-driven flush, bisect-based order book) and a CLI layer for agents and humans.
+
+## License
+
+MIT
+
+## Disclaimer
+
+This software is provided "as is", without warranty of any kind. The authors are not responsible for any financial losses, trading decisions, or system failures. Polymarket data is provided by Polymarket's public APIs. Use at your own risk.

polyws-0.2.0/README.md

@@ -0,0 +1,280 @@
+# polyws
+
+Real-time Polymarket data streaming for Python. Built for trading bots, data pipelines, and AI agents.
+
+```bash
+pip install polyws
+```
+
+```bash
+polyws stream --markets 10
+```
+
+```python
+from polyws import WSSubscriptionManager, WebSocketHandlers
+
+stream = WSSubscriptionManager(WebSocketHandlers(
+    on_polymarket_price_update=lambda events: [
+        print(f"{e.asset_id[:16]}… {float(e.price)*100:.1f}%") for e in events
+    ]
+))
+await stream.add_subscriptions(["<asset-id>"])
+```
+
+---
+
+## Why polyws?
+
+Polymarket has two APIs, no official Python streaming library, and a multi-step lookup just to get real-time prices. polyws solves all of that.
+
+### The problem
+
+To stream live Polymarket data in Python today, you need to:
+
+1. Query the **Gamma API** to discover markets and extract `clobTokenIds`
+2. Connect to the **CLOB WebSocket** with a handshake protocol
+3. Manage subscriptions, reconnections, and ping/pong keepalive
+4. Maintain an order book cache to compute display prices
+5. Implement Polymarket's [price calculation logic](https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated#future-price) (midpoint when spread ≤ $0.10, last trade price otherwise)
+
+That's ~500 lines of async boilerplate before you write a single line of business logic.
+
+### What polyws gives you
+
+```python
+stream = WSSubscriptionManager(handlers)
+await stream.add_subscriptions(asset_ids)
+# Done. Events flow to your handlers.
+```
+
+- Automatic WebSocket connection, reconnection, and keepalive
+- Subscription batching with event-driven flush (no polling)
+- Order book cache with sorted bid/ask levels
+- Derived display prices matching the Polymarket UI
+- CLI for discovery and streaming without writing code
+- JSON Lines output for piping into other tools and agents
+
+### How it compares
+
+|  | polyws | [poly-websockets](https://github.com/nevuamarkets/poly-websockets) (TS) | [py-clob-client](https://github.com/Polymarket/py-clob-client) (official) | [polymarket-cli](https://github.com/polymarket/polymarket-cli) (Rust) |
+|--|--------|-------------------|----------------|-----------------|
+| Language | Python | TypeScript | Python | Rust |
+| Real-time streaming | WebSocket | WebSocket | REST only | REST only |
+| Auto-reconnect | Event-driven | Polling (5s interval) | N/A | N/A |
+| Subscription flush | Instant (`asyncio.Event`) | Polling (100ms interval) | N/A | N/A |
+| Display price logic | Built-in | Built-in | Manual | Manual |
+| Order book cache | `bisect.insort` | Full re-sort | None | None |
+| CLI | `polyws markets/stream` | None | None | Full trading CLI |
+| Agent-friendly output | JSON Lines (auto-detect) | None | None | `--output json` |
+| Trading / orders | No | No | Yes | Yes |
+| Runtime deps | 2 | 5 | 8+ | N/A (binary) |
+| Install | `pip install` | `npm install` | `pip install` | `brew install` |
+
+**polyws is not a trading client.** It does one thing — real-time data streaming — and does it well. Use it alongside `py-clob-client` for a complete Python trading stack.
+
+---
+
+## CLI
+
+### Browse markets
+
+```bash
+# Top 20 markets by volume
+polyws markets
+
+# Search
+polyws markets --search "bitcoin" --limit 5
+
+# Sort options: volume (default), liquidity, newest
+polyws markets --sort liquidity --limit 10
+```
+
+### Stream real-time data
+
+```bash
+# Stream top 10 markets
+polyws stream --markets 10
+
+# Stream specific assets
+polyws stream --asset-id 4655345557056451798919...
+
+# Search and stream
+polyws stream --search "election"
+```
+
+### Output format
+
+polyws auto-detects the output context:
+
+- **Terminal (TTY):** Human-readable, formatted, colored
+- **Piped / redirected:** JSON Lines — one JSON object per line
+
+```bash
+# Human output
+polyws markets --limit 3
+
+#  99.7%  $58.7M  Will there be no change in Fed rates...  [10255981...]
+#   0.2%  $53.5M  Will the Fed decrease rates by 25...     [62938043...]
+#   0.1%  $48.3M  Will the Fed decrease rates by 50+...    [46553455...]
+
+# Machine output (piped)
+polyws markets --limit 1 | jq .
+# {"asset_id": "102559...", "question": "Will there be...", "volume": 58739675, "price": "0.9965"}
+```
+
+This makes polyws natively usable by AI agents — pipe the output, parse the JSON, act on it.
+
+---
+
+## Library API
+
+### WSSubscriptionManager
+
+```python
+from polyws import WSSubscriptionManager, WebSocketHandlers
+
+handlers = WebSocketHandlers(
+    on_book=my_book_handler,
+    on_price_change=my_change_handler,
+    on_last_trade_price=my_trade_handler,
+    on_tick_size_change=my_tick_handler,
+    on_polymarket_price_update=my_price_handler,  # Derived display price
+    on_error=my_error_handler,
+    on_ws_open=my_open_handler,
+    on_ws_close=my_close_handler,
+)
+
+manager = WSSubscriptionManager(handlers, reconnect_interval_s=5.0)
+```
+
+All handlers are `async`, optional, and receive a list of typed events.
+
+| Method | Description |
+|--------|-------------|
+| `await add_subscriptions(ids)` | Subscribe to assets. Connects automatically. |
+| `await remove_subscriptions(ids)` | Unsubscribe from assets. |
+| `get_asset_ids()` | List all monitored assets. |
+| `get_statistics()` | Connection stats (`open_websockets`, `asset_ids`, `pending_subscribe`, `pending_unsubscribe`). |
+| `await clear_state()` | Full teardown. Manager is reusable after. |
+
+### Market Discovery
+
+```python
+from polyws import fetch_markets, extract_asset_ids
+
+markets = fetch_markets(limit=10, sort="volume", search="crypto")
+assets = extract_asset_ids(markets)  # {asset_id: question, ...}
+```
+
+### Event Types
+
+| Event | When | Key Fields |
+|-------|------|------------|
+| `BookEvent` | Full order book snapshot on subscribe | `bids`, `asks`, `asset_id` |
+| `PriceChangeEvent` | Order book level added/removed/updated | `price_changes[].side`, `price`, `size` |
+| `LastTradePriceEvent` | A trade executes | `price`, `side`, `size` |
+| `TickSizeChangeEvent` | Tick size changes | `old_tick_size`, `new_tick_size` |
+| `PolymarketPriceUpdateEvent` | Derived display price changes | `price`, `midpoint`, `spread`, `triggering_event` |
+
+### How display prices work
+
+Polymarket doesn't show raw bid/ask prices. It shows a **derived price**:
+
+- If bid-ask spread ≤ $0.10 → display the **midpoint**
+- If bid-ask spread > $0.10 → display the **last trade price**
+
+`on_polymarket_price_update` fires whenever this derived price changes. This matches what you see on polymarket.com.
+
+---
+
+## For AI Agents
+
+polyws is designed as a tool for AI agents that need real-time market intelligence.
+
+**As a CLI tool:**
+```bash
+# Agent discovers markets about a topic
+polyws markets --search "AI" --limit 5 | jq -r '.question'
+
+# Agent monitors prices and acts on thresholds
+polyws stream --search "bitcoin" | while read line; do
+  price=$(echo "$line" | jq -r 'select(.event=="price_update") | .price')
+  # ... agent logic ...
+done
+```
+
+**As a Python library:**
+```python
+# Agent builds a real-time market monitor
+from polyws import WSSubscriptionManager, WebSocketHandlers, fetch_markets, extract_asset_ids
+
+markets = fetch_markets(search="election", limit=20)
+assets = extract_asset_ids(markets)
+
+async def on_update(events):
+    for e in events:
+        if float(e.price) > 0.9:
+            await alert(f"High confidence: {assets[e.asset_id]} at {e.price}")
+
+mgr = WSSubscriptionManager(WebSocketHandlers(on_polymarket_price_update=on_update))
+await mgr.add_subscriptions(list(assets.keys()))
+```
+
+**Why agents prefer polyws over alternatives:**
+- JSON Lines output — no parsing HTML or tables
+- Zero config — no API keys needed for read-only streaming
+- Predictable schema — every event is typed and documented
+- Instant — WebSocket, not polling REST endpoints
+- Composable — pipe into `jq`, `grep`, other tools, or import as a library
+
+---
+
+## Architecture
+
+```
+polyws/
+├── src/polyws/
+│   ├── types.py        # Typed dataclasses for all events
+│   ├── order_book.py   # Sorted order book cache (bisect.insort)
+│   ├── manager.py      # WebSocket lifecycle, reconnect, flush
+│   ├── gamma.py        # Gamma API market discovery
+│   ├── cli.py          # CLI entry point (argparse)
+│   └── logger.py       # stdlib logging
+├── tests/              # 53 unit + integration tests
+└── examples/           # Ready-to-run scripts
+```
+
+**Runtime dependencies:** `websockets`, `orjson`. That's it.
+
+**Python:** >= 3.11
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/<org>/polyws.git
+cd polyws
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run live integration test (requires network)
+pytest -m live
+```
+
+---
+
+## Inspired by
+
+[poly-websockets](https://github.com/nevuamarkets/poly-websockets) by Nevua Markets — the TypeScript library that pioneered this approach. polyws is a Python rewrite with performance improvements (event-driven flush, bisect-based order book) and a CLI layer for agents and humans.
+
+## License
+
+MIT
+
+## Disclaimer
+
+This software is provided "as is", without warranty of any kind. The authors are not responsible for any financial losses, trading decisions, or system failures. Polymarket data is provided by Polymarket's public APIs. Use at your own risk.