Below is a fully updated version of your README, with:
- New “Insider / Informed Trader Alert” features clearly documented (without accusatory language).
- Concrete, step-by-step guidance for integrating the Hashdive (Hashmaps) API, including configuration, rate limits, data flow, and where it fits in the pipeline.
- Clear separation between data provider responsibilities and detector logic, keeping the project compliance-aware and research-focused.
You can replace your existing README.md with the content below.
(for GitHub Copilot Agent & Research Use)
This repository contains the PolyMarket Anomaly Detector, a local research and monitoring tool built in Python that detects and flags unusual, high-signal trading behavior on PolyMarket using publicly available data only.
The system is designed for research, market surveillance, and compliance analysis — not enforcement. It focuses on identifying statistical and behavioral anomalies, including whale activity, coordinated actors, timing-based anomalies, and potentially informed or privileged trading patterns, without making claims about intent or legality.
The architecture is modular, explainable, and reproducible, combining public APIs, enriched trade data, and on-chain signals.
- PolyMarket public endpoints
- Polygon on-chain data
- Hashdive (Hashmaps) API for enriched trades, OHLCV, and whale activity
- Rule-based detectors
- Statistical baselines & z-scores
- Temporal and cross-market correlation logic
- Detects pre-resolution positioning, pre-news accumulation, and asymmetric timing advantages
- Labels alerts as “Informed Timing Risk” or “Elevated Information Asymmetry”
- Produces evidence bundles instead of judgments
- DuckDB + Polars feature views
- Wallet-level, market-level, and temporal features
- Combines detector outputs into unified, explainable scores
- Built in FastAPI + Streamlit / PyWebIO
- Drill-downs by wallet, market, and alert type
- CSV trade slices
- JSON summaries
- Price + timing charts for each alert
Alerts indicate statistically unusual timing or positioning patterns that may warrant further analysis.
- Wallet accumulates a large position shortly before market resolution
- Especially when price impact is minimal at entry
- Trades occur shortly before major market-moving events (debates, court rulings, announcements)
- Compared against historical behavior of the same wallet
- Wallet takes large directional exposure with unusually low downside volatility
- Compared to contemporaneous traders
- Same wallet positions consistently ahead of correlated markets resolving
- Triggered detector IDs (e.g.
D7_TIMING_ASYMMETRY) - Risk score contribution
- Trade-level evidence (from Hashdive + on-chain)
- Market context (price, volume, liquidity)
- Clear non-accusatory language
polymarket-anomaly-detector/
├── README.md
├── docker-compose.yml
├── requirements.txt
├── setup.py
├── .env.example
├── config/
│ ├── detectors.yaml
│ ├── pipeline.yaml
│ └── logging.yaml
│
├── data/
│ ├── bronze/ # Raw API & on-chain data (Parquet)
│ ├── silver/ # Feature tables (DuckDB views)
│ └── gold/ # Aggregated risk & alerts
│
├── src/
│ ├── api/ # FastAPI endpoints
│ ├── app_frontend/ # Streamlit / PyWebIO UI
│ ├── data/
│ │ ├── ingest_hashdive.py # Hashdive API ingestion
│ │ ├── ingest_polymarket.py
│ │ └── ingest_chain.py
│ ├── features/
│ ├── detectors/
│ │ ├── d1_whale_trades.py
│ │ ├── d5_coordination.py
│ │ ├── d7_timing_asymmetry.py # Insider-style timing detector
│ │ └── d9_pre_resolution.py
│ ├── risk/
│ ├── alerts/
│ ├── storage/
│ ├── utils/
│ ├── main.py
│ └── settings.py
│
├── tests/
├── notebooks/
└── scripts/
The Hashdive API is the primary source of enriched PolyMarket trade data used by this system.
- Normalized trade history by wallet
- Market metadata enrichment
- OHLCV aggregates
- Whale trade detection
- Consistent pagination & formats
Add the following to your .env file:
HASHDIVE_API_KEY=your_api_key_here
HASHDIVE_BASE_URL=https://hashdive.com/api
HASHDIVE_RATE_LIMIT_QPS=1