Polymarket Whale Monitor

Real-time monitoring system for tracking large bets (whales) on Polymarket prediction markets.

Overview

This system monitors Polymarket's real-time data streams to track significant trading activity (≥$1,000 USD bets), providing insights into whale positions, win rates, and market movements.

Key Features

• Real-time WebSocket monitoring of Polymarket trades
• Position tracking with P&L calculations
• Win rate analysis for whale traders
• Insider detection based on trading patterns
• Top 10 holders analysis for market concentration
• Volume spike detection for unusual market activity
• Flask API for data access
• Minimal dark-theme UI for visualization

Architecture

┌─────────────────┐
│  Polymarket API │
│   (WebSocket)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐      ┌──────────────┐
│ whale_service.py│─────▶│  PostgreSQL  │
│ (Data Collector)│      │   Database   │
└─────────────────┘      └──────┬───────┘
                                 │
         ┌───────────────────────┤
         │                       │
         ▼                       ▼
┌─────────────────┐      ┌──────────────┐
│  pnl_updater.py │      │    app.py    │
│ (Update P&L)    │      │  (Flask API) │
└─────────────────┘      └──────┬───────┘
                                 │
                                 ▼
                         ┌──────────────┐
                         │   Frontend   │
                         │  (HTML/JS)   │
                         └──────────────┘

Project Structure

Poly-Sema/
├── src/                      # Main source code
│   ├── whale_service.py      # WebSocket listener for real-time trades
│   ├── app.py                # Flask API server
│   ├── config.py             # Configuration management
│   ├── pnl_updater.py        # P&L calculation updater
│   ├── win_rate_updater.py   # Win rate calculation
│   ├── update_positions.py   # Position tracking
│   ├── top10_backfill.py     # Top 10 holders analysis
│   ├── requirements.txt      # Python dependencies
│   ├── templates/
│   │   └── polymarket.html   # Frontend UI
│   └── DOCS/                 # Technical documentation
├── DOCS/                     # Widget specifications
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore rules
└── README.md                 # This file

Database Schema

PostgreSQL database polymarket_whale_monitor with schema polymarket:

Main Tables

whale_bets - Stores all whale transactions

• Trade details (tx_hash, timestamp, wallet, bet_size, side)
• Position metrics (avg_entry_price, position_size, unrealized_pnl)
• Win rate stats (total_trades, wins, losses, win_rate_percent)
• Market data (outcome, market_question, event_slug)
• Insider flags and top 10 holder percentages

market_cache - Caches market metadata

• Market questions, slugs, and URLs
• Prevents redundant API calls

Setup

Prerequisites

• Python 3.8+
• PostgreSQL 12+
• 2GB RAM minimum

1. Clone Repository

git clone <repository-url>
cd Poly-Sema

2. Environment Setup

Copy the example environment file and configure:

cp .env.example .env

Edit .env and set:

• DATABASE_URL - PostgreSQL connection string
• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
• MIN_WHALE_BET_USD - Minimum bet size to track (default: 1000)

3. Database Setup

Create the database and schema:

createdb polymarket_whale_monitor

psql -d polymarket_whale_monitor -c "CREATE SCHEMA IF NOT EXISTS polymarket;"

The tables will be created automatically when you first run the services.

4. Install Dependencies

cd src
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

5. Run Services

You need to run multiple services:

Terminal 1: WebSocket Listener

cd src
source venv/bin/activate
python whale_service.py

Terminal 2: Flask API

cd src
source venv/bin/activate
python app.py

Terminal 3 (Optional): P&L Updater

cd src
source venv/bin/activate
python pnl_updater.py

Terminal 4 (Optional): Win Rate Updater

cd src
source venv/bin/activate
python win_rate_updater.py

6. Access the Dashboard

Open your browser:

http://localhost:8000

API Endpoints

GET /api/polymarket/whale-bets

Get list of whale bets

Query Parameters:

• limit (int, default: 100) - Number of records
• sort (str, default: 'time') - Sort by 'time' or 'size'

Response:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "timestamp": "2025-12-26T19:00:00Z",
      "whale_wallet": "0x1234...5678",
      "bet_size_usd": 15000.00,
      "outcome": "YES",
      "market_question": "Will Trump win 2024?",
      "avg_entry_price": 0.65,
      "position_size": 23076.92,
      "unrealized_pnl_usd": 1500.00,
      "unrealized_pnl_percent": 10.0,
      "win_rate_percent": 65.5,
      "total_trades": 42
    }
  ],
  "count": 1
}

GET /api/polymarket/stats

Get 24-hour statistics

Response:

{
  "status": "success",
  "data": {
    "total_bets_24h": 156,
    "total_volume_24h": 2345678.00,
    "unique_whales_24h": 42
  }
}

GET /api/health

Health check endpoint

Configuration

All configuration is done through environment variables in .env:

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	-
MIN_WHALE_BET_USD	Minimum bet size to track	1000
FLASK_HOST	Flask server host	127.0.0.1
FLASK_PORT	Flask server port	8000
FLASK_DEBUG	Enable debug mode	True
LOG_LEVEL	Logging level	INFO

Development

Running Tests

cd src
pytest tests/

Code Style

This project uses:

• PEP 8 style guide
• Type hints where applicable
• Docstrings for all functions

Database Migrations

Schema changes should be documented and applied manually. No ORM is used to keep dependencies minimal.

Monitoring & Logging

All services log to console with timestamps. Log levels:

• INFO: Normal operations
• WARNING: Recoverable errors
• ERROR: Critical failures

Check logs for:

# WebSocket listener
tail -f src/whale_service.log

# Flask API
tail -f src/flask_api.log

Troubleshooting

WebSocket disconnects frequently

• Check network stability
• Verify Polymarket WebSocket URL is current
• Review logs for error patterns

Missing whale bets

• Verify MIN_WHALE_BET_USD threshold
• Check if whale_service.py is running
• Confirm database connection

Database connection errors

• Verify PostgreSQL is running
• Check DATABASE_URL in .env
• Ensure database and schema exist

Performance

Expected resource usage:

• Memory: ~200MB per service
• CPU: <5% average
• Disk: ~1GB per week for whale_bets table

Security Notes

• .env file contains sensitive credentials - never commit to git
• Default setup is localhost-only
• For production deployment:
  • Use environment-based secrets
  • Enable HTTPS
  • Implement rate limiting
  • Add authentication

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check /src/DOCS for detailed widget specifications
• Review logs for error messages
• Open an issue on GitHub

Roadmap

• WebSocket reconnection with exponential backoff
• Redis caching layer
• GraphQL API
• Mobile-responsive UI
• Real-time notifications
• Advanced analytics dashboard