polymarket-insider-tracker/docs/skill-tracking-prediction-market-flow.md

Skill: tracking-prediction-market-flow

Use when analyzing prediction market activity for informed-flow signals, insider trading patterns, or suspicious wallet behavior on Polymarket.

What This Tool Does

polymarket-insider-tracker streams real-time trades from Polymarket's WebSocket feed, profiles trader wallets on the Polygon blockchain, and scores each trade for informed-flow risk using multiple detection signals:

• Fresh wallet detection: New wallets (age < 48h, nonce <= 5) making large trades (> $1k). Insiders create disposable wallets per trade.
• Size anomaly detection: Trades consuming > 2% of 24h volume or > 5% of visible order book depth. Informed traders bet bigger when they have edge.
• Niche market scoring: Low-volume markets (< $50k daily) get a 1.5x risk multiplier. Easier to have inside information on obscure events.
• Funding chain analysis: Traces wallet funding sources on-chain to link seemingly separate wallets to the same entity or exchange.
• Sniper cluster detection: DBSCAN clustering identifies wallets that consistently enter markets within minutes of creation.

Composite risk scoring combines signals with configurable weights (default alert threshold: 0.6). Multi-signal bonuses: 2 signals +20%, 3+ signals +30%.

Installation

git clone https://github.com/pselamy/polymarket-insider-tracker.git
cd polymarket-insider-tracker
uv sync --all-extras
docker compose up -d   # PostgreSQL + Redis
cp .env.example .env   # defaults work for local dev
uv run alembic upgrade head

No API keys required for basic operation (Polymarket APIs are public).

Usage

# Start the tracker (streams trades, profiles wallets, scores risk, alerts)
uv run python -m polymarket_insider_tracker

# Dry run (no alerts sent)
uv run python -m polymarket_insider_tracker --dry-run

# Debug mode (see every trade)
uv run python -m polymarket_insider_tracker --log-level DEBUG

# Validate config without starting
uv run python -m polymarket_insider_tracker --config-check

Interpreting Signals

Risk Assessment Output

Each flagged trade produces a risk assessment with:

• Confidence score (0.0-1.0): Composite of weighted signals
• Signal breakdown: Which detectors fired and their individual confidence
• Wallet profile: Age, nonce, transaction count, funding source
• Market context: Volume, category, order book depth

Signal Interpretation Guide

Score Range	Interpretation	Action
0.6-0.7	Moderate: single strong signal or two weak ones	Monitor, note the market
0.7-0.85	High: multiple signals converging	Investigate the market and wallet
0.85-1.0	Critical: fresh wallet + large size + niche market	High-confidence informed flow

What This Is NOT

• Not a trading signal generator. Informed flow != actionable alpha without further analysis (hypothesis -> leakage-aware backtest -> capital).
• Not real-time enough for front-running. The tool detects patterns for research and monitoring, not millisecond-level execution.
• Detection of informed flow does not prove insider trading. Many legitimate reasons exist for the patterns this tool flags.

Rate Limits and Etiquette

• Polymarket WebSocket: No explicit rate limit; one persistent connection. Do not open multiple connections unnecessarily.
• Polymarket CLOB REST: Built-in rate limiter at 10 req/s with retry backoff on 429/5xx. Respect this for metadata/orderbook queries.
• Polygon RPC: Public endpoints (polygon-rpc.com) have low limits. For sustained use, configure a dedicated RPC provider via POLYGON_RPC_URL. Built-in token-bucket rate limiter at 25 req/s with Redis caching (5min TTL).

Known Pitfalls

1. WebSocket subscription format: Must include action: "subscribe" in the envelope. Without it, the server accepts the connection but delivers zero trade events (silent failure). Fixed in the current version.

2. Message routing: Live-data WebSocket pushes {connection_id, payload: {...trade fields}}, not {topic, type, payload}. Route by checking for transactionHash + proxyWallet keys in payload.

3. Public RPC rate limits: Default Polygon RPC will throttle under load. Use a dedicated provider for production.

4. Database required: PostgreSQL + Redis must be running. Use docker compose up -d for local dev.

Cross-References

• Repository: https://github.com/pselamy/polymarket-insider-tracker
• Issues: https://github.com/pselamy/polymarket-insider-tracker/issues
• Agent skill landing (follow-on): selamy-labs/agent-skills