<div align="center">

🐋 polymarket-whales

CLI whale tracker for Polymarket — terminal alerts when smart money moves.

Quick Start · Configuration · Features · Contributing

</div>

---

What is this?

polymarket-whales monitors the Polymarket CLOB API and fires an alert the moment a trade above your threshold hits the books. Prints to terminal with color-coded output. No sign-up, no API key, no infrastructure. Just Python.

Don't want to self-host? Subscribe to the live whale feed on Telegram: @polymarketwhales_ai

---

📋 Example Output

══════════════════════════════════════════════════
🐋  polymarket-whales
══════════════════════════════════════════════════
  Min trade size : $500
  Check interval : 30s
══════════════════════════════════════════════════

🐋 WHALE ALERT  2026-03-20 14:23:01
───────────────────────────────────────────
Market : Will Trump tweet about crypto today?
Side   : YES
Amount : $2,847.00
Price  : 0.7300  (73% YES)
───────────────────────────────────────────

🐋 WHALE ALERT  2026-03-20 14:26:44
───────────────────────────────────────────
Market : Fed rate cut in March 2026?
Side   : NO
Amount : $12,500.00
Price  : 0.3100  (69% NO)
───────────────────────────────────────────

---

⚡ Quick Start

git clone https://github.com/al1enjesus/polymarket-whales
cd polymarket-whales
pip install -r requirements.txt
python main.py

That's it. Terminal alerts start immediately. No config needed to get started.

---

⚙️ Configuration

Copy .env.example to .env and edit:

MIN_TRADE_SIZE=500        # USD — only alert above this
CHECK_INTERVAL=30         # seconds between polls

# Optional — Telegram push alerts
TELEGRAM_BOT_TOKEN=...
TELEGRAM_CHAT_ID=...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

Or edit config.yaml directly. Environment variables take priority.

Telegram setup (optional):

1. Message @BotFather → /newbot → copy the token
2. Message @userinfobot → copy your chat ID
3. Paste both into .env

Just want alerts without setup? → Join @polymarketwhales_ai

---

✨ Features

• ✅ Real-time polling of the Polymarket CLOB API
• ✅ Configurable minimum trade size (USD)
• ✅ Colorized terminal output — YES in green, NO in red
• ✅ Optional Telegram push alerts to any chat or channel
• ✅ Optional Discord webhook alerts
• ✅ Export whale trades to CSV or JSON (--export whales.csv)
• ✅ Auto-resolves market names from condition IDs
• ✅ Trade deduplication — no double alerts
• ✅ Graceful handling of network errors and API timeouts
• ✅ No database, no Docker, no setup beyond pip install

---

🛠️ Advanced

Run in background:

nohup python main.py > whales.log 2>&1 &

Custom config path:

python main.py --config /path/to/config.yaml

Export whale trades to CSV or JSON:

python main.py --export whales.csv
python main.py --export whales.json

24/7 on a VPS: Any $5/month VPS works — the script uses <10MB RAM.

---

🤝 Contributing

Good first issues:

• [x] Discord / Slack webhook support (merged — thanks @Deepak8858!)
• [x] Historical whale data export (CSV / JSON) (merged — thanks @Deepak8858!)
• [ ] Filter by specific market or category
• [ ] Track and tag recurring whale wallets
• [ ] Alert cooldown per market (avoid spam)
• [ ] Web dashboard (simple Flask/Streamlit UI)

Open an issue or send a PR — both welcome.

---

📡 Community & Live Whale Feed

Join @polymarketwhales_ai on Telegram:

• 🐋 Live feed of large trades — real-time, no setup required
• 💬 Community chat — discuss strategies, share setups, post your whale catches
• 🤖 AI bot connected — ask questions, get market context, analyze trades

Whether you're running the script or just lurking for signals — this is the place.

---

🌍 Blocked by geo-restrictions?

Polymarket is unavailable in the US and some other countries. If you can't access it, you have two options:

Option A — Self-host with a VPN/proxy Point the script at a proxy by setting HTTPS_PROXY in .env:

HTTPS_PROXY=http://your-proxy:port

Option B — Use PolyClawster's relay (recommended)

PolyClawster runs a transparent proxy to clob.polymarket.com, deployed in Tokyo (outside US geo-blocks). It routes your API calls on their behalf — your requests never touch Polymarket directly.

• 🚫 No VPN needed
• 🚫 No KYC
• ✅ Full Polymarket CLOB API access from any country
• ✅ One line of config

Set in .env:

POLYMARKET_API_URL=https://polyclawster.com/api/clob-relay

Then in main.py the script will use this base URL for all CLOB requests instead of hitting Polymarket directly.

The relay is the same infrastructure used by PolyClawster AI agents to trade Polymarket 24/7 from any country.

---

🤖 Want trades executed automatically?

This tool watches. PolyClawster acts.
AI agent that copies whale moves and trades Polymarket 24/7 — works from any country, no VPN, no KYC, start with $10.

---

MIT · Built by Virixlabs