b962bdaee2
* fix(ingestor): align WebSocket subscribe + routing with live API
The Polymarket ws-live-data WebSocket requires `action: "subscribe"` in
the subscribe envelope. Without it the server accepts the connection but
never delivers trade events, causing the tracker to silently produce
zero alerts.
Additionally, incoming frames are shaped `{connection_id, payload:{...}}`
-- they do NOT echo the `topic`/`type` keys we sent. The previous routing
check matched nothing and every real trade was silently dropped.
Changes:
- Add `action: "subscribe"` to subscription message
- Route incoming messages by payload shape (transactionHash + proxyWallet)
- Add ratchet tests for payload routing edge cases
- Rewrite README as agent-first with <2min quickstart
- Add skill draft (docs/skill-tracking-prediction-market-flow.md)
Closes #89
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(lint): remove unused imports in test_pipeline_persistence
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* style: apply ruff formatting
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|