polymarket-monitor

Polymarket Monitor

Monitor live Polymarket prediction markets for price changes, volume spikes, and spread movements. Outputs structured JSON alerts when thresholds are crossed. All endpoints are read-only and require no API keys.

Prerequisite: This skill uses token IDs from the polymarket-scanner skill. Run scan_markets.py first to discover markets and obtain token IDs.

Quick Start

All scripts require the Python venv at /home/verticalclaw/.venv.

Monitor Multiple Markets for Price Alerts

source /home/verticalclaw/.venv/bin/activate && python polymarket-monitor/scripts/monitor_prices.py \
  --token-id "<TOKEN_ID_1>" \
  --token-id "<TOKEN_ID_2>" \
  --interval 30 \
  --threshold 5.0

This polls every 30 seconds and prints a JSON alert whenever a token's midpoint moves more than 5% from its baseline.

Watch a Single Market Live

source /home/verticalclaw/.venv/bin/activate && python polymarket-monitor/scripts/watch_market.py \
  --token-id "<TOKEN_ID>" \
  --interval 15

Prints a JSON snapshot every 15 seconds with price, spread, and order book depth.

Scripts

monitor_prices.py

Polls multiple tokens at a set interval and emits JSON alerts when price changes exceed a threshold.

Arguments:

• --token-id ID — CLOB token ID to monitor (repeatable, at least one required)
• --interval N — Polling interval in seconds (default: 30, minimum: 5)
• --threshold N — Percentage change to trigger an alert (default: 5.0)
• --max-polls N — Stop after N polls (default: unlimited, use for non-interactive runs)
• --baseline-window N — Number of recent prices to average for baseline (default: 1, meaning compare to last poll)

Output: One JSON object per line for each alert:

{
  "type": "price_alert",
  "token_id": "...",
  "timestamp": "2026-02-26T12:00:00Z",
  "current_price": 0.65,
  "baseline_price": 0.60,
  "change_pct": 8.33,
  "direction": "up",
  "spread": 0.02,
  "poll_number": 5
}

Non-alert polls print a status line to stderr so the agent knows monitoring is active.

watch_market.py

Continuously monitors a single market, printing a JSON snapshot each interval with price, spread, volume, and order book summary.

Arguments:

• --token-id ID — CLOB token ID to watch (required)
• --interval N — Snapshot interval in seconds (default: 15, minimum: 5)
• --max-polls N — Stop after N snapshots (default: unlimited)

Output: One JSON object per line per snapshot:

{
  "type": "market_snapshot",
  "token_id": "...",
  "timestamp": "2026-02-26T12:00:00Z",
  "midpoint": 0.55,
  "best_bid": 0.54,
  "best_ask": 0.56,
  "spread": 0.02,
  "bid_depth": 15000.0,
  "ask_depth": 12000.0,
  "last_trade_price": 0.55,
  "last_trade_side": "BUY",
  "poll_number": 1
}

Data Flow

1. Run polymarket-scanner/scripts/scan_markets.py to find markets and get token IDs
2. Pass token IDs to monitor_prices.py for multi-market alerting
3. Or pass a single token ID to watch_market.py for detailed single-market tracking

Monitoring Guide

For recommended thresholds by market type and advanced monitoring strategies, see references/monitoring-guide.md.