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

.