Set Up Your Polymarket Whale Tracker

What the Whale Hunter Does

PM-03 scans the Polygon blockchain every 60 seconds, watching a curated list of high-performing wallets for new Polymarket positions. The moment a whale moves, you get a Telegram alert with the market, size, direction, and a suggested copy size.

With AUTO_COPY=true it mirrors the trade automatically at the best available price.

• 1

  Every 60 seconds

  Scans on-chain transaction data for each tracked wallet. Detects new Polymarket CTF Exchange interactions — i.e., new positions being opened.

• 2

  Qualifies the trade

  Checks: is the trade size above MIN_WHALE_SIZE? Is the market price below PRICE_CEILING? Does the market have enough time left (MIN_HOURS_LEFT)?

• 3

  Fires Telegram alert in ~60 seconds

  Tells you: which whale, which market, what direction, what size. Includes a suggested copy size based on your COPY_RATIO setting.

• 4

  Optional auto-copy

  Places your copy order automatically at the current best price. Exits at 88¢ TP or 4¢ SL — same as PM-01.

What You Need

• Polymarket account with USDC — same as PM-01
• Polymarket CLOB API keys — same as PM-01
• Telegram bot — same bot works fine
• Alchemy API key (optional but recommended) — free at alchemy.com

Install & Configure

copycd pm-03-whale-hunter
python3 setup.py

Key settings the wizard asks about:

• MIN_WHALE_SIZE — minimum $ trade to trigger alert. Default $500. Lower = more noise, higher = fewer but stronger signals.
• MIN_WIN_RATE — only copy whales above this win rate. Default 0.55. Raise to 0.65 for stricter filtering.
• COPY_RATIO — your copy = X% of whale size. Default 0.01 (1%). A $5,000 whale trade → $50 copy.
• MAX_COPY_SIZE — hard cap per copy. Default $50. Safety net so one huge whale trade doesn't over-size you.
• PRICE_CEILING — never copy above this price. Default 0.80. Protects you from copying into over-priced positions.
• AUTO_COPY — true/false. Start with false, watch alerts for a week, then enable when you trust it.

Managing Your Whale List

PM-03 ships with 10 pre-seeded high-performing wallets sourced from Polygon blockchain data. You can view, add, or remove wallets from data/whales.json:

[
  {
    "address": "0x7f3ad0a9...",
    "label": "Whale_01",
    "win_rate": 0.71,
    "trades": 847,
    "active": true
  },
  ...
]

Adding your own whale

Find a wallet you want to track on polygonscan.com — look for wallets interacting frequently with Polymarket's CTF Exchange contract. Add them:

copy{
  "address": "0xYOUR_WALLET_HERE",
  "label": "My Custom Whale",
  "win_rate": 0.60,
  "trades": 0,
  "active": true
}

Pausing a whale

If a whale goes on a losing streak, set "active": false — the scanner stops copying them without removing their history.

Dry Run — Watch the Whales

copypython3 src/whale_hunter.py --dry-run

You'll see scan cycles every 60 seconds:

[CYCLE 1] 00:14:45
Scanning 10 wallets on Polygon...

Whale_01 (0x7f3a...): No new activity
Whale_03 (0x3b2c...): No new activity
...

[DRY RUN] WHALE MOVE DETECTED
Wallet: Whale_01 (71% win rate, 847 trades)
Market: Will Trump sign executive order on crypto?
Direction: YES @ 41¢
Whale size: $8,400
Suggested copy: $50 @ ~43¢

→ Would copy (dry run — skipped)

Next scan in 60s.

Go Live + 24/7 Daemon

copypython3 src/whale_hunter.py

Install the 24/7 background service:

copy./scripts/setup_launchd.sh

Monitor:

copytail -f /tmp/whale_hunter.log

Running all 3 agents together

PM-01, PM-02, and PM-03 are fully independent services. Each has its own LaunchAgent. Run all three simultaneously:

copy# Each installed separately via their own setup_launchd.sh
# Check all are running:
launchctl list | grep agentcheat

com.agentcheat.pm_monitor     ← PM-01 scanner
com.agentcheat.arb_scanner    ← PM-02 arb
com.agentcheat.whale_hunter   ← PM-03 whale