PolyMarket Whale Watcher 🐋

A Telegram bot that monitors large trades (whale activity) on PolyMarket and sends real-time notifications.

Features

• 📊 Real-time monitoring of whale trades on PolyMarket
• 🔔 Telegram notifications for significant trades
• 🎯 Customizable filters (minimum value, market IDs, keywords)
• 👥 Track multiple whale addresses
• 🔄 Automatic retry on API errors
• 💾 Trade deduplication to prevent duplicate notifications
• 🛡️ Single chat ID restriction for security
• ⚙️ Easy configuration via Telegram bot commands

Prerequisites

• Python 3.8 or higher
• A Telegram bot token (get one from @BotFather)
• Your Telegram chat ID (get it from @userinfobot)

Installation

Windows Setup

1. Clone the repository:

   git clone https://github.com/ebc81/polymarket-whale-watcher.git
   cd polymarket-whale-watcher

2. Create a virtual environment:

   python -m venv venv
   venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure the bot:

   • Copy .env.example to .env
   • Edit .env with your Telegram bot token and chat ID

   copy .env.example .env
   notepad .env

5. Run the bot:

   python -m src.main

Raspberry Pi / Linux Setup

1. Clone the repository:

   git clone https://github.com/ebc81/polymarket-whale-watcher.git
   cd polymarket-whale-watcher

2. Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure the bot:

   • Copy .env.example to .env
   • Edit .env with your credentials

   cp .env.example .env
   nano .env

5. Run the bot:

   python -m src.main

Running as a Systemd Service (Linux/Raspberry Pi)

1. Edit the service file:

   nano service/polymarket-bot.service

   Update the User and WorkingDirectory paths to match your setup.

2. Copy the service file:

   sudo cp service/polymarket-bot.service /etc/systemd/system/

3. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable polymarket-bot.service
   sudo systemctl start polymarket-bot.service

4. Check the status:

   sudo systemctl status polymarket-bot.service

5. View logs:

   sudo journalctl -u polymarket-bot.service -f

Configuration

Environment Variables

Edit the .env file to configure the bot:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# PolyMarket Configuration
POLL_INTERVAL=60                # How often to check for new trades (seconds)
MIN_TRADE_VALUE=0               # Minimum trade value to notify (USD)
HEARTBEAT_INTERVAL=600          # How often to send heartbeat notifications (seconds)

# Bootstrap whale addresses (comma-separated)
WHALE_ADDRESSES=0x0029ec6df644c87b7ba49e9627b04b8fa0f6bc93,0x003f24b98b1b54a49e3df4bb3a07a0f5fda4a3ed

# Market filters (optional, comma-separated market IDs)
MARKET_IDS=

# Market text filters (optional, comma-separated keywords)
MARKET_TEXT_FILTERS=

# Market exclusion filters (optional, comma-separated market IDs to exclude)
EXCLUDE_MARKET_IDS=

# Market text exclusion filters (optional, comma-separated keywords to exclude)
EXCLUDE_MARKET_TEXT_FILTERS=

Getting Your Telegram Credentials

1. Bot Token:

   • Open Telegram and search for @BotFather
   • Send /newbot and follow the instructions
   • Copy the bot token provided

2. Chat ID:

   • Start a chat with your bot
   • Send any message to it
   • Open @userinfobot and get your user ID
   • Use this ID as your TELEGRAM_CHAT_ID

Finding PolyMarket Top Trader Addresses

To effectively monitor whale activity, you need to identify and track addresses of top traders. Here are several methods to find high-value trader addresses:

1. PolyMarket Leaderboard and Analytics

• Visit the PolyMarket Leaderboard to see top traders ranked by profit
• Browse market-specific pages on PolyMarket to identify large positions
• Use third-party analytics platforms like Dune Analytics for deeper insights into trader behavior
• Copy wallet addresses directly from these platforms

2. PolyMarket Public API

You can use the PolyMarket trades API to identify frequent or large traders:

# Example: Fetch recent trades and inspect for large transactions
# First, explore the API response to understand available fields
curl "https://clob.polymarket.com/trades?limit=100"

# The response contains trade objects with fields like 'maker_address', 'size', 'price', etc.
# You can filter for large trades (adjust the size threshold as needed)
curl "https://clob.polymarket.com/trades?limit=100" | jq '.[] | select(.size > 10000)'

• Monitor the trades endpoint for large transactions
• Note maker_address values that appear frequently with high-value trades
• Track addresses from significant market movements

3. Community Sources and On-Chain Verification

• Discord/Telegram Communities: Join PolyMarket community channels where traders share insights
• Twitter/X: Follow PolyMarket traders and analysts who share wallet addresses
• Blockchain Explorers: Use Polygonscan to verify addresses and inspect trading history
  • Search for addresses you find to confirm their trading activity
  • Check transaction history and volumes to validate they're active traders
• On-chain verification: Always verify addresses through blockchain explorers before adding them

4. Adding Addresses to the Bot

Once you've identified whale addresses, add them using either method:

Via Environment Variable (at startup):

# Edit .env file
WHALE_ADDRESSES=0x1234...,0x5678...,0x9abc...

Via Telegram Command (while running):

/addwhale 0x1234567890abcdef1234567890abcdef12345678
/listwhales

Tips:

• Start with 5-10 high-volume traders for focused monitoring
• Regularly review and update your whale list based on market activity
• Use /listwhales to manage your tracked addresses
• Combine whale tracking with market filters for targeted alerts

Bot Commands

Once the bot is running, you can manage it using these Telegram commands:

General Commands

• /start or /help - Show help message with all commands
• /status - Show current configuration

Whale Management

• /addwhale <address> - Add a whale address to track
• /removewhale <address> - Remove a whale address
• /listwhales - List all tracked whale addresses

Market Filters

• /addmarket <id> - Add a market ID filter
• /removemarket <id> - Remove a market ID filter
• /listmarkets - List all market filters

Market Exclusion Filters

• /addmex <id> - Exclude a market by ID
• /removemex <id> - Remove market ID exclusion
• /listmex - List excluded market IDs

Text Filters

• /addtext <keyword> - Add a keyword filter for market names
• /removetext <keyword> - Remove a keyword filter
• /listtexts - List all text filters

Text Exclusion Filters

• /addtex <keyword> - Exclude markets by keyword
• /removetex <keyword> - Remove keyword exclusion
• /listtex - List excluded keywords

Configuration

• /setminvalue <value> - Set minimum trade value (USD)
• /setinterval <seconds> - Set poll interval (minimum 10 seconds)
• /setheartbeat <seconds> - Set heartbeat notification interval (minimum 60 seconds)

Example Usage

/addwhale 0x1234567890abcdef1234567890abcdef12345678
/setminvalue 1000
/setinterval 30
/addtext trump
/status

How It Works

1. Polling Loop: The bot continuously polls the PolyMarket trades API at the configured interval
2. Trade Fetching: It fetches recent trades for all tracked whale addresses
3. Filtering: Trades are filtered based on priority order:
   • Minimum trade value threshold
   • Market ID exclusions (reject if matched)
   • Text exclusions (reject if matched)
   • Market ID inclusions (if configured, must match)
   • Text inclusions (if configured, must match)
4. Deduplication: Each trade is checked against a local store to prevent duplicate notifications
5. Notifications: Qualifying trades are formatted and sent to your Telegram chat

Filter Priority

The bot applies filters in the following priority order:

1. Minimum trade value: Trades below the minimum are always excluded
2. Exclude market IDs: If a trade matches an excluded market ID, it's rejected
3. Exclude text filters: If a trade matches an excluded keyword, it's rejected
4. Include market IDs: If market ID filters are configured, only matching trades pass
5. Include text filters: If text filters are configured, only matching trades pass

This means exclusion filters take priority over inclusion filters, allowing you to fine-tune which trades you want to be notified about.

Project Structure

polymarket-whale-watcher/
├── src/
│   ├── __init__.py           # Package initialization
│   ├── config.py             # Configuration management
│   ├── store.py              # Trade storage and deduplication
│   ├── polymarket.py         # PolyMarket API client
│   ├── telegram_bot.py       # Telegram bot implementation
│   └── main.py               # Main entry point
├── service/
│   └── polymarket-bot.service # Systemd service file
├── .env.example              # Example environment configuration
├── .gitignore                # Git ignore rules
├── requirements.txt          # Python dependencies
└── README.md                 # This file

Troubleshooting

Bot doesn't respond to commands

• Verify your TELEGRAM_CHAT_ID is correct
• Make sure you've started a chat with your bot first
• Check that the bot token is valid

python-telegram-bot v22 lifecycle notes

• The bot uses Application from PTB v22. For commands to work, the application must be initialized and started before polling.
• Lifecycle in this project:
  • Initialize: await application.initialize()
  • Start: await application.start() (activates handlers/dispatcher)
  • Poll: await application.updater.start_polling(...) (runs asynchronously in a background task)
  • Stop: await application.updater.stop() then await application.stop() and await application.shutdown()
• If you see "event loop already running", avoid calling run_polling() inside asyncio.run(...). Use the async lifecycle above.

No trade notifications

• Verify whale addresses are correctly configured
• Check if MIN_TRADE_VALUE is set too high
• Ensure the bot is running (check logs)
• Verify network connectivity to PolyMarket API

"Unauthorized access" message

• Your Telegram chat ID doesn't match the configured TELEGRAM_CHAT_ID
• Only the configured chat ID can use the bot

Service won't start on Linux

• Check file permissions: chmod +x src/main.py
• Verify paths in the service file are correct
• Check logs: sudo journalctl -u polymarket-bot.service -f

Security Notes

• Never commit your .env file to version control
• Keep your bot token secret and secure
• The bot only responds to the configured chat ID
• Store whale addresses and API keys securely
• If your token is exposed: Immediately rotate it via @BotFather → /mybots → select your bot → "Bot Settings" → "Regenerate Token"
• Always keep .env and state files (like config_state.json) local - they are ignored by Git for your security
• See SECURITY.md for detailed security guidelines and best practices

API Rate Limiting

The PolyMarket API has rate limits. The bot includes:

• Configurable poll intervals (default: 60 seconds)
• Automatic retry on errors with exponential backoff
• Request timeouts to prevent hanging

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Disclaimer

This bot is for informational purposes only. Use at your own risk. The authors are not responsible for any trading decisions made based on notifications from this bot.