PolyTracker Bot — Polymarket Whale Tracker

A production-grade Python bot that monitors high-performing wallets on Polymarket and sends Telegram alerts when they make profitable trade signals.

Overview

What it does:

Discovers and scores the top-performing wallets on Polymarket
Tracks only wallets that meet profitability thresholds (60%+ win rate, 5ドルk+ lifetime profit, etc.)
Polls tracked wallets every 5 minutes for new positions
Sends Telegram alerts with direct market links when high-conviction signals are detected
Supports "high conviction" alerts when 2+ whales enter the same market

Why it matters: Following consistent winners on prediction markets can improve decision-making and reduce research overhead.

Tech Stack

Language: Python 3.11+
Async HTTP: httpx with retry logic & rate limiting
Scheduler: APScheduler (5-minute polling + daily digest)
Database: SQLite (with aiosqlite)
Telegram: python-telegram-bot v20+
Logging: loguru
Config: python-dotenv

Project Structure

PolyTrackerBot/
├── polytracker/
│ ├── __init__.py
│ ├── config.py # Load config from .env
│ ├── db.py # SQLite database + queries
│ ├── main.py # Entry point
│ ├── scheduler.py # APScheduler job definitions
│ │
│ ├── polymarket/
│ │ ├── __init__.py
│ │ ├── client.py # Async Polymarket API client
│ │ ├── wallet_scanner.py # Discover & score wallets
│ │ └── trade_monitor.py # Poll tracked wallets for new positions
│ │
│ ├── signals/
│ │ ├── __init__.py
│ │ ├── filter.py # Apply 7 viability filters
│ │ └── scorer.py # Wallet scoring formula
│ │
│ └── telegram/
│ ├── __init__.py
│ ├── bot.py # Telegram bot setup
│ └── alerts.py # Format & send alerts
│
├── tests/
│ ├── test_scorer.py
│ ├── test_filter.py
│ └── conftest.py
│
├── .env.example # Template (copy to .env)
├── requirements.txt # Dependencies
├── Dockerfile # Container setup
├── docker-compose.yml # Local dev
└── README.md # This file

Verified Polymarket API Endpoints

Data API (`https://data-api.polymarket.com`)

All endpoints are public — no authentication required.

Endpoint	Purpose
`GET /v1/leaderboard`	Top traders by PnL or volume
`GET /v1/user/{address}/positions`	Current open positions
`GET /v1/user/{address}/trades`	Recent trade history
`GET /v1/user/{address}/activity`	Recent activity stream
`GET /v1/profiles/{address}/public-profile`	Public wallet stats (PnL, win rate, vol)

Parameters for leaderboard:

category: OVERALL, POLITICS, SPORTS, CRYPTO, CULTURE, etc. (default: OVERALL)
timePeriod: DAY, WEEK, MONTH, ALL (default: DAY)
orderBy: PNL or VOL (default: PNL)
limit: 1-50 (default: 25)
offset: Pagination (default: 0)

Gamma API (`https://gamma-api.polymarket.com`)

Market & event metadata (no auth).

Endpoint	Purpose
`GET /v1/markets/{slug}`	Market details by slug
`GET /v1/conditions/{id}`	Market details by condition ID

CLOB API (`https://clob.polymarket.com`)

Orderbook & pricing (public endpoints only).

Endpoint	Purpose
`GET /v1/prices/midpoint`	Current midpoint price
`GET /v1/orderbook?token_id=...`	Liquidity estimate

Setup Instructions

1. Create Telegram Bot

Message @BotFather on Telegram
Type /start then /newbot
Follow prompts to name your bot
Save the bot token (e.g., 123456789:ABCdefGHIjkLmNoPQRstUVWxYzAbcD...)

2. Create/Get Channel ID

Create a channel (e.g., @polytracker) or use existing one
Add your bot as admin
Forward any message to @userinfobot to get the CHANNEL_ID
- Look for -100... format (e.g., -1001234567890)

3. Clone & Setup

cd ~/code/openclaw/projects
git clone <repo-url> PolyTrackerBot
cd PolyTrackerBot
# Copy and fill config
cp .env.example .env
# Edit .env:
# TELEGRAM_BOT_TOKEN=your_token
# TELEGRAM_CHANNEL_ID=-100...

4. Install Dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

5. Run Locally

python -m polytracker.main

You should see:

INFO | PolyTracker Bot started
INFO | Scheduler running with 5 jobs
INFO | Wallet discovery job scheduled for every 6 hours
...

Configuration Reference

Variable	Default	Description
`TELEGRAM_BOT_TOKEN`	(required)	Bot token from @BotFather
`TELEGRAM_CHANNEL_ID`	(required)	Channel ID (with `-100` prefix)
`MIN_WIN_RATE`	0.60	Minimum win rate (0-1)
`MIN_TOTAL_PNL`	5000	Minimum lifetime PnL in USD
`MIN_TRADES`	25	Minimum trade count for validity
`MIN_AVG_POSITION`	200	Minimum average position size USD
`MIN_VOLUME_30D`	2000	Minimum 30-day volume USD
`MAX_WALLETS_TRACKED`	50	Max tracked wallets at once
`MIN_SIGNAL_POSITION`	500	Minimum position size to alert USD
`MIN_MARKET_LIQUIDITY`	10000	Minimum market liquidity USD
`MIN_HOURS_REMAINING`	48	Minimum hours until market close
`POLL_TRADES_INTERVAL_MINUTES`	5	How often to check for new positions
`DATABASE_PATH`	`./data/polytracker.db`	SQLite database path
`LOG_LEVEL`	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)

Scheduler Jobs

Job	Frequency	Purpose
discover_wallets	Every 6 hours	Find new high-performing wallets
rescore_wallets	Every 24 hours	Re-evaluate existing wallets
poll_trades	Every 5 minutes	Check tracked wallets for new positions
check_closures	Every 1 hour	Cleanup resolved/closed markets
daily_digest	08:00 UTC daily	Send summary of day's signals

Alert Format

Standard Alert (1 whale)

📡 POLYTRACKER SIGNAL
Wallet: 0x1234...abcd [Score: 87/100]
Win Rate: 73% | PnL: 24,300ドル | ROI: +142%
📌 Market: "Will X happen by Dec 31?"
Position: YES @ 34¢
Size: 1,200ドル
Liquidity: 85,400ドル
Closes: 14d 6h
🔗 Market: https://polymarket.com/event/will-x-happen
🔗 Wallet: https://polymarket.com/profile/0x1234...abcd
Risk: MEDIUM | Confidence: HIGH

High Conviction Alert (2+ whales same market)

🔥 HIGH CONVICTION — POLYTRACKER
2 tracked whales entered the same market!
Wallets:
 • 0x1234...abcd (Score: 87) → YES @ 34¢ (1,200ドル)
 • 0x5678...efgh (Score: 91) → YES @ 36¢ (3,400ドル)
📌 "Will X happen by Dec 31?"
Combined Position: 4,600ドル
Liquidity: 85,400ドル
Closes: 14d 6h
🔗 https://polymarket.com/event/will-x-happen

Database Schema

wallets

- address (PRIMARY KEY)
- score (0-100)
- win_rate (0-1)
- total_pnl (USD)
- roi (%)
- volume_30d (USD)
- avg_position (USD)
- total_trades (int)
- last_seen (timestamp)
- added_at (timestamp)
- is_active (bool)

trades

- id (PRIMARY KEY)
- wallet_address (FK)
- market_id
- market_slug
- market_title
- direction (YES/NO)
- price (0-1)
- size_usd
- timestamp
- market_closes (timestamp)
- alerted (bool)

alerts_sent

- id (PRIMARY KEY)
- wallet_address (FK)
- market_id
- sent_at (timestamp)
- alert_type ('standard' or 'high_conviction')

Wallet Scoring Formula

score = (win_rate * 40) + (log(total_pnl) * 20) + (roi * 20) + (recency_bonus * 20)
recency_bonus:
 1.0 if last_trade < 7 days
 0.5 if 7-30 days
 0.0 if > 30 days

Signal Viability Filter (All 7 Must Pass)

✅ Tracked wallet opens new position
✅ Market is still open (not resolved)
✅ Position size ≥ 500ドル (configurable)
✅ Market liquidity ≥ 10,000ドル (configurable)
✅ ≥ 48 hours remaining (configurable)
✅ No previous alert for this wallet-market pair
✅ Position direction matches wallet's historical edge in category

Docker Deployment

Build & Run Locally

docker-compose up --build

Production Deployment

docker build -t polytracker:latest .
docker run -d \
 --name polytracker \
 -e TELEGRAM_BOT_TOKEN=... \
 -e TELEGRAM_CHANNEL_ID=... \
 --restart=always \
 -v $(pwd)/data:/app/data \
 polytracker:latest

Systemd Service (Linux)

Create /etc/systemd/system/polytracker.service:

[Unit]
Description=PolyTracker Bot
After=network.target
[Service]
Type=simple
User=bot
WorkingDirectory=/home/bot/PolyTrackerBot
Environment="PATH=/home/bot/PolyTrackerBot/venv/bin"
EnvironmentFile=/home/bot/PolyTrackerBot/.env
ExecStart=/home/bot/PolyTrackerBot/venv/bin/python -m polytracker.main
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target

Enable & start:

sudo systemctl enable polytracker
sudo systemctl start polytracker
sudo journalctl -u polytracker -f # Watch logs

Testing

# Run all tests
pytest tests/ -v
# Run specific test
pytest tests/test_scorer.py -v
# With coverage
pytest tests/ --cov=polytracker --cov-report=html

Monitoring & Troubleshooting

Check Logs

# Local
tail -f logs/polytracker.log
# Docker
docker logs -f polytracker
# Systemd
journalctl -u polytracker -f

Common Issues

Issue	Solution
Bot not sending alerts	Check `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHANNEL_ID` in `.env`
"Rate limited" errors	Reduce `MAX_REQUESTS_PER_SECOND` or increase polling interval
Missing wallets	Run wallet discovery job manually: `python -m polytracker.main --discover-now`
Database locked	Ensure only one instance is running; check `data/polytracker.db` permissions

Future Enhancements (V2)

Web dashboard (React UI)
Webhook support (replace polling with real-time events)
Wallet clustering by trading style
Backtesting framework
Position sizing advice (Kelly Criterion)
Multi-platform alerts (Discord, SMS)
GraphQL API for custom queries

License

TBD

Support

Issues: Open a GitHub issue
Questions: See /docs folder or check AGENTS.md

Built with Python, APScheduler, and caffeine. ⚡

Name		Name	Last commit message	Last commit date
dashboard		dashboard
polytracker		polytracker
scripts		scripts
tests		tests
.env.example		.env.example
.env.phase2		.env.phase2
.gitignore		.gitignore
API_MODE_SWITCH_README.md		API_MODE_SWITCH_README.md
CURRENT_STATUS.md		CURRENT_STATUS.md
DASHBOARD_QUICKSTART.md		DASHBOARD_QUICKSTART.md
DEPLOYMENT_READY.md		DEPLOYMENT_READY.md
DRY_RUN_STATUS.md		DRY_RUN_STATUS.md
Dockerfile		Dockerfile
IMPLEMENTATION_SPEC.md		IMPLEMENTATION_SPEC.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
PHASE_1_QUICKSTART.md		PHASE_1_QUICKSTART.md
PHASE_1_SETUP.md		PHASE_1_SETUP.md
PHASE_1_STATUS.txt		PHASE_1_STATUS.txt
PHASE_1_SUMMARY.md		PHASE_1_SUMMARY.md
PHASE_2_EXECUTION_LOG.md		PHASE_2_EXECUTION_LOG.md
PHASE_2_INTEGRATION.md		PHASE_2_INTEGRATION.md
PHASE_2_OVERVIEW.md		PHASE_2_OVERVIEW.md
PHASE_2_RUN_COMMANDS.sh		PHASE_2_RUN_COMMANDS.sh
PHASE_2_SETUP.md		PHASE_2_SETUP.md
PHASE_2_STARTUP.md		PHASE_2_STARTUP.md
PHASE_2_STATUS.md		PHASE_2_STATUS.md
PHASE_2_SUMMARY.md		PHASE_2_SUMMARY.md
PHASE_3_DEMO_TRANSITION.md		PHASE_3_DEMO_TRANSITION.md
QUICKSTART.md		QUICKSTART.md
QUICK_START.md		QUICK_START.md
README.md		README.md
RUN_INSTRUCTIONS.md		RUN_INSTRUCTIONS.md
SERVICE_STATUS.md		SERVICE_STATUS.md
START_EVERYTHING.sh		START_EVERYTHING.sh
docker-compose-pg.yml		docker-compose-pg.yml
docker-compose.yml		docker-compose.yml
monitor_dryrun.sh		monitor_dryrun.sh
pytest.ini		pytest.ini
requirements.txt		requirements.txt
run_demo.sh		run_demo.sh
run_dryrun.sh		run_dryrun.sh

Latest commit

History

Folders and files

Repository files navigation