Real-time order book streaming and liquidity metrics for Polymarket, built on CSP (Composable Stream Processing).
Supports both US Exchange (regulated, requires auth) and DeFi Exchange (international, no auth).
websocket → parse_market_data → compute_spread → print_row / display_book / display_trading
→ compute_mid →
→ compute_liq_density →
Each metric is an independent reactive CSP node. The graph runs in CSP's real-time engine with C++ performance for event scheduling.
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt| Exchange | Flag | Auth Required | Market ID |
|---|---|---|---|
| DeFi (polymarket.com) | --defi (default) |
No | Token ID |
| US (polymarket.us) | --us |
Yes (Ed25519) | Market Slug |
Add your Polymarket US API credentials to config.json:
{
"api_key": "your-api-key-uuid",
"private_key": "your-base64-ed25519-private-key"
}Generate keys at polymarket.us/developer (requires KYC).
# DeFi Exchange (default, no auth required)
python orderbook_streaming.py --open # Pick from open markets
python orderbook_streaming.py --search "bitcoin" # Search markets
python orderbook_streaming.py <token_id> # Direct token ID
# US Exchange (requires config.json)
python orderbook_streaming.py --us --open # Pick from open markets
python orderbook_streaming.py --us --search "nba" # Search markets
python orderbook_streaming.py --us <slug> # Direct market slug# Metrics mode (default): one row per update
python orderbook_streaming.py --defi --open
# Order book view: live depth + liquidity metrics
python orderbook_streaming.py --book --open
# Trading dashboard: price, liquidity, flow metrics
python orderbook_streaming.py --trading --search "trump"# Find open markets (active=true, closed=false)
python orderbook_streaming.py [--us|--defi] --open
# Search only open markets by keyword
python orderbook_streaming.py [--us|--defi] --open --search "query"
# Search all markets by keyword
python orderbook_streaming.py [--us|--defi] --search "query"
# Browse recent markets
python orderbook_streaming.py [--us|--defi] --browse# Print CSP graph topology as ASCII
python orderbook_streaming.py --graph --open
python orderbook_streaming.py --graph --book --search "bitcoin"Real-time liquidity snapshot across all open markets via a single WebSocket connection. Subscribes to all markets at once, redraws on every incoming update, sorted by total qty depth.
# Full table: one row per market, sorted by bid+ask depth
python orderbook_streaming.py --us --overview-ws
# Summary view: grouped by sport + top 15 markets
python orderbook_streaming.py --us --overview-ws --summaryFull table (--overview-ws):
POLYMARKET US — LIVE WS OVERVIEW UTC 15:32:18 EST 10:32:18 │ update #142 │ 12/279 markets populated
avg spread: 0.0420 │ total bid qty: 45.2K │ total ask qty: 38.1K │ 267 awaiting data │ Ctrl+C to exit
────────────────────────────────────────────────────────────────────────────────────────────────────────
# SLUG QUESTION BID ASK SPREAD B.LVL A.LVL BID QTY ASK QTY LAST
────────────────────────────────────────────────────────────────────────────────────────────────────────
1 aec-nba-bos-lal-2026-02-22 Boston vs. Los Angeles L 0.4800 0.5200 0.0400 5 4 12,450 10,230 0.4900
2 aec-nba-phi-min-2026-02-22 Philadelphia vs. Minnesota 0.3200 0.3600 0.0400 3 3 8,920 7,450 0.3400
...
| Column | Description |
|---|---|
| B.LVL / A.LVL | Number of price levels on each side |
| BID QTY / ASK QTY | Total qty (contracts) resting on each side |
Summary view (--overview-ws --summary):
POLYMARKET US — LIVE SUMMARY UTC 15:32:18 EST 10:32:18 │ update #142 │ Ctrl+C to exit
──────────────────────────────────────────────────────────────────────────────
OVERALL
Markets: 279 total │ 12 with orders │ 267 awaiting snapshot
Bid depth: 45,230 │ Ask depth: 38,120
Avg spread: 0.0420 │ Range: 0.0100 – 0.1500
──────────────────────────────────────────────────────────────────────────────
SPORT MARKETS W/ORDERS BID QTY ASK QTY AVG SPREAD DEPTH RATIO
──────────────────────────────────────────────────────────────────────────────
NBA 42 5 12,450 10,230 0.0380 1.22x
NHL 118 3 8,920 7,450 0.0520 1.20x
CBB 80 2 5,210 4,890 0.0610 1.07x
MLS 6 2 3,420 2,980 0.0450 1.15x
──────────────────────────────────────────────────────────────────────────────
TOP 15 MARKETS BY DEPTH
...
| Column | Description |
|---|---|
| W/ORDERS | Markets with at least one resting bid or ask |
| DEPTH RATIO | bid_qty / ask_qty — above 1.0 means more buy-side pressure |
# Fire 5000 concurrent requests (default)
python orderbook_streaming.py --us --dump
# Custom request count
python orderbook_streaming.py --us --dump 50000| Metric | Description |
|---|---|
| BID / ASK | Best bid and ask prices |
| BID_Q / ASK_Q | Top-of-book size |
| SPREAD | ask - bid |
| MID | (bid + ask) / 2 |
| BID_SZ / ASK_SZ | Total order book depth |
| BID_L10% / ASK_L10% | Liquidity within 10% of best price |
| TRADE | Last trade price |
Live-refreshing terminal display with liquidity metrics and adverse selection scoring:
market-slug-or-token | UTC 20:32:18.686 EST 15:32:18.686
BID QTY BID PX │ ASK PX ASK QTY │ LIQUIDITY METRICS
──────────── ────────── │ ────────── ──────────── │ ──────────────────────────────
27.00 0.1980 │ 0.1990 945.00 │ Spread: 0.0010 ( 50.4 bps)
5426.00 0.1920 │ 0.2020 13000.00 │ Mid: 0.1985
8000.00 0.1880 │ 0.2070 2794.00 │ Microprice: 0.1980 ( -23.8 bps)
... │
│ Book Imbal: +17.3% BID heavy
│ Top Imbal: -94.4% (near-term)
│
│ ── DEPTH BY LEVEL ──────────
│ 1%: 27 │ 945 (0.03x)
│ 5%: 5453 │ 16739 (0.33x)
│ 10%: 22714 │ 26520
│
│ ── ADVERSE SELECTION ───────
│ Score: 61.6 (0=safe, 100=toxic)
──────────── ────────── │ ────────── ──────────── │
407989 TOTAL │ TOTAL 287820 │
| Metric | Description |
|---|---|
| Microprice | Size-weighted mid: shifts toward thin side (directional signal) |
| Book Imbal | (bid_depth - ask_depth) / total: positive = more bids |
| Top Imbal | Same calc for top-of-book only: near-term pressure signal |
| Depth @ X% | Liquidity within X% of mid price on each side |
| Adverse Selection | Composite score (0-100): spread width + top thinness + imbalance |
Live trading metrics for decision support:
┌──────────────────────────────────────────────────────────────────────┐
│ TRADING VIEW: market-id │
│ UTC 17:35:59 EST 12:35:59 │
├──────────────────────────────────────────────────────────────────────┤
│ PRICE │
│ Mid: 0.5125 Last: 0.5060 Change: +0.00% │
│ Bid: 0.5060 Ask: 0.5190 Spread: 253.7 bps │
│ High: 0.5125 Low: 0.5125 Vol: 0.0000 │
├──────────────────────────────────────────────────────────────────────┤
│ LIQUIDITY │
│ Bid Depth: 395716 Ask Depth: 395866 Imbal: -0.0% │
│ Slippage (buy): 100→0.00% 500→0.04% 1000→0.11% │
│ Slippage (sell): 100→0.00% 500→0.00% 1000→0.00% │
├──────────────────────────────────────────────────────────────────────┤
│ TRADE FLOW │
│ Trades: 0 VWAP: 0.5125 │
│ Buy Vol: 0 Sell Vol: 0 Net: +0 │
├──────────────────────────────────────────────────────────────────────┤
│ RECENT TRADES │
│ 12:30:15 BUY 0.5100 150.00 │
│ 12:30:12 SELL 0.5050 75.00 │
└──────────────────────────────────────────────────────────────────────┘
| Metric | Description |
|---|---|
| Spread (bps) | Spread in basis points relative to mid |
| Change % | Price change since session start |
| Vol | Rolling volatility (std dev of mid prices) |
| Imbal | Order book imbalance: (bid_depth - ask_depth) / total |
| Slippage | Estimated cost to fill 100/500/1000 contracts |
| VWAP | Volume-weighted average price of trades |
| Net | Buy volume minus sell volume |
- csp - Point72's stream processing framework (C++ engine, Python API)
- tornado - WebSocket transport
- cryptography - Ed25519 authentication (US exchange only)
- python-rapidjson - JSON parsing for CSP adapters
- pytz - Timezone handling (UTC/EST)