polysurv — Kalshi anomaly monitor (read-only)

This repo is a minimal, production-minded "market integrity / anomaly alert" monitor:

• polls recent trades,
• listens to WebSocket streams when configured,
• dedupes them,
• computes simple anomaly features,
• alerts to stdout and/or Discord.

It does not place trades.

Quickstart

1) Install

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"

2) Configure

Copy .env.example to .env and set values.

cp .env.example .env

3) Run

polysurv run

Configuration notes

You must set the correct KALSHI_REST_BASE_URL and a valid KALSHI_TRADES_PATH + params. This repo intentionally does not hard-code the Kalshi endpoints because they can change. Check Kalshi docs and then set:

• KALSHI_REST_BASE_URL
• KALSHI_TRADES_PATH (e.g. "/markets/trades")
• KALSHI_MARKET_PARAM (e.g. "ticker")
• KALSHI_LIMIT_PARAM (e.g. "limit")
• KALSHI_SINCE_PARAM (optional; if supported)

What goes in MARKETS?

Use Kalshi market tickers (e.g. the ticker shown on the market page or in the URL). You can also fetch tickers via the Kalshi markets API and copy the "ticker" field. If MARKETS is empty, the REST poller will fetch without a market filter and the WebSocket subscription will omit a market filter (best-effort).

WebSocket ingestion (optional)

If you set KALSHI_WS_URL, the runner will connect to the WebSocket and subscribe to the channels listed in KALSHI_WS_CHANNELS. If the WS stream emits trade-like objects, they are normalized and scored the same way as REST trades.

If your WS endpoint requires auth headers, fill KALSHI_ACCESS_KEY, KALSHI_ACCESS_SIGNATURE, and KALSHI_ACCESS_TIMESTAMP in .env.

When a WS message includes a market ticker (market_ticker or ticker), the runner will call GET /markets/{ticker} once and cache the market metadata.

If you see proxy-related WS errors, set KALSHI_WS_DISABLE_PROXY=true to bypass proxy env vars.

For WS signing, set KALSHI_ACCESS_KEY plus either:

• KALSHI_PRIVATE_KEY_PATH (recommended), or
• KALSHI_PRIVATE_KEY (with literal \n line breaks).

You can test the WS handshake with:

polysurv ws-test --timeout 10

Cached market metadata is persisted to STATE_DIR/TICKER_CACHE_FILE as JSON.

Common workflow

Start with 1–3 markets you care about (MARKETS=...) and validate that the poller sees trades.

Once ingestion is correct, tune thresholds:

• BIG_TRADE_USD
• SCORE_THRESHOLD
• BURST_WINDOW_SEC
• BASELINE_WINDOW_TRADES

Market-level alerts are based on repeated suspicious trades in a short window:

• MARKET_ALERT_WINDOW_SEC
• MARKET_ALERT_MIN_ALERTS
• MARKET_ALERT_COOLDOWN_SEC

Email alerts (optional)

Set these in .env to enable email notifications:

• SMTP_HOST
• SMTP_PORT
• SMTP_USERNAME
• SMTP_PASSWORD
• SMTP_USE_TLS
• SMTP_USE_SSL
• SMTP_FROM
• SMTP_TO (comma-separated list)

Finding tickers

Use the built-in CLI to list markets and grab tickers:

polysurv markets --status open --limit 20

To fetch a single market by ticker:

polysurv market KXHIGHNY-24NOV

Legal / ethical

This is framed as anomaly detection / integrity monitoring. If you use it for trading decisions, do your own compliance and risk review.