This is a live WebSocket scanner that connects to Polymarket's real-time data feed and displays every trade worth $1,000 or more across ALL markets. It shows colorful "whale alerts" in your terminal as they happen - like a police scanner for big trades.
In crypto/trading slang, a whale is someone who trades very large amounts. In this scanner, a whale is anyone who trades $1,000 or more in a single transaction on Polymarket.
Why track whales? Large trades can indicate:
HTTP (regular): You ask the server "any new trades?" every 10 seconds. The server says "yes" or "no."
WebSocket: You open a permanent connection to the server. The server pushes new trades to you the millisecond they happen. No asking needed - it just streams in.
This is like the difference between checking your mail every hour vs. having someone hand you each letter as it arrives.
WebSocket connections can silently die if neither side sends data for a while. The scanner sends a ping every 30 seconds to keep the connection alive. If the server doesn't respond, it knows the connection is dead and reconnects.
MIN_WHALE_USD = 1_000 # Only show trades >= $1,000
WEBSOCKET_URL = "wss://ws-live-data.polymarket.com"
PING_INTERVAL = 30 # Keep connection alive
HEARTBEAT_INTERVAL = 10 # Fun status line every 10sWhat it does: Sets up the connection parameters. The WebSocket URL is Polymarket's live data endpoint. The minimum whale threshold filters out small trades.
def on_open(ws):
# Connection established!
print("Connected to Polymarket live data!")
# Start heartbeat thread
start_heartbeat()
def on_message(ws, message):
# New trade data arrived!
trade = json.loads(message)
process_trade(trade)
def on_error(ws, error):
# Something went wrong
print(f"WebSocket error: {error}")
def on_close(ws, code, reason):
# Connection closed - auto-reconnect
if not shutdown_flag:
connect_websocket() # Reconnect!What it does: These four functions handle the WebSocket lifecycle:
on_open: Runs when connected. Starts the heartbeat thread.on_message: Runs for every incoming trade. Processes and displays it.on_error: Runs on errors. Logs the issue.on_close: Runs when disconnected. Auto-reconnects unless you pressed Ctrl+C.def process_trade(trade):
size = float(trade.get('size', 0))
price = float(trade.get('price', 0))
usd_value = size * price
# Only show trades >= $1,000
if usd_value >= MIN_WHALE_USD:
print_whale(trade, usd_value)
stats['whales_printed'] += 1
if usd_value > stats['biggest_whale_usd']:
stats['biggest_whale_usd'] = usd_valueWhat it does: For every incoming trade, calculates the USD value. If it's $1,000+, displays a colorful whale alert and updates the session statistics (tracking the biggest whale seen).
def heartbeat_loop():
while not shutdown_flag:
# Rotate through fun phrases
phrase = random.choice(HEARTBEAT_PHRASES)
spinner = SPINNER_FRAMES[frame % 4]
print(f" {spinner} {phrase}...")
time.sleep(HEARTBEAT_INTERVAL)What it does: Every 10 seconds, prints a fun rotating status line to show the scanner is still alive and working. Phrases like "scanning the deep blue for whales" and "sonar pinging the deep" keep the terminal lively.
def signal_handler(signum, frame):
# Ctrl+C pressed - clean up nicely
shutdown_flag = True
ws_app.close()
# Print final statistics
print(f"Session: {stats['trades_seen']} trades, "
f"{stats['whales_printed']} whales")
print(f"Biggest whale: ${stats['biggest_whale_usd']:,.2f}")What it does: When you press Ctrl+C, sets the shutdown flag, closes the WebSocket connection cleanly, and prints your session statistics before exiting. No orphaned connections or hanging processes.
pip install websocket-client termcolorOnly two packages! No API keys needed - Polymarket's live data feed is public.
| Term | Meaning |
|---|---|
| Whale | A trader who makes very large trades (typically $1,000+) |
| WebSocket | A protocol for real-time two-way communication between client and server |
| Ping/Pong | Small messages sent to keep a connection alive and detect disconnections |
| Heartbeat | A periodic signal showing the scanner is still running |
| Reconnect | Automatically re-establishing a dropped connection |
| Thread | A separate unit of execution running in parallel with the main program |
| Signal Handler | A function that runs when the OS sends a signal (like Ctrl+C) |
| Graceful Shutdown | Closing all connections and cleaning up before exiting |
# --- PYTHON ---
MIN_WHALE_USD = 1_000
WEBSOCKET_URL = "wss://ws-live-data.polymarket.com"
PING_INTERVAL = 30
HEARTBEAT_INTERVAL = 10
shutdown_flag = False
stats = {'trades_seen': 0, 'whales_printed': 0,
'biggest_whale_usd': 0.0, 'started_at': time.time()}
WHALE_EMOJIS = ['🐋', '🐳', '🦈', '🌊', '💰', '💎', '🚀', '🔥']
# --- PSEUDO-CODE ---
SET minimum whale trade size to $1,000
SET WebSocket URL to Polymarket's live data endpoint
SET ping interval to 30 seconds (keep connection alive)
SET heartbeat interval to 10 seconds (fun status updates)
INITIALIZE shutdown flag to FALSE (bot is running)
INITIALIZE statistics tracker:
trades_seen: 0 (how many total trades streamed in)
whales_printed: 0 (how many big trades were displayed)
biggest_whale_usd: $0 (largest trade seen so far)
started_at: current time
SET list of rotating whale emojis for fun display# --- PYTHON ---
def on_open(ws):
print("Connected!")
start_heartbeat()
def on_message(ws, message):
trade = json.loads(message)
process_trade(trade)
def on_error(ws, error):
print(f"Error: {error}")
def on_close(ws, code, reason):
if not shutdown_flag:
connect_websocket() # auto-reconnect
# --- PSEUDO-CODE ---
FUNCTION on_open(websocket):
This runs when the connection is first established
PRINT "Connected to Polymarket live data!"
START the heartbeat thread (periodic fun status messages)
FUNCTION on_message(websocket, raw message text):
This runs EVERY TIME a new trade comes in
PARSE the message from JSON text into a data object
CALL process_trade() to analyze and maybe display it
FUNCTION on_error(websocket, error):
This runs if something goes wrong
PRINT the error
FUNCTION on_close(websocket, close code, reason):
This runs when the connection drops
IF we didn't intentionally shut down:
RECONNECT automatically (the connection just died)# --- PYTHON ---
def process_trade(trade):
size = float(trade.get('size', 0))
price = float(trade.get('price', 0))
usd_value = size * price
stats['trades_seen'] += 1
if usd_value >= MIN_WHALE_USD:
print_whale(trade, usd_value)
stats['whales_printed'] += 1
if usd_value > stats['biggest_whale_usd']:
stats['biggest_whale_usd'] = usd_value
stats['biggest_whale_market'] = trade.get('market', '')
# --- PSEUDO-CODE ---
FUNCTION process_trade(trade data):
EXTRACT the trade size (how many shares)
EXTRACT the trade price (how much per share)
CALCULATE the total USD value = size x price
ADD 1 to the total trades counter
IF the trade value is $1,000 or more (it's a WHALE!):
CALL print_whale() to display a colorful alert
ADD 1 to the whales printed counter
IF this is the biggest whale we've seen so far:
UPDATE the record tracker with this trade's details# --- PYTHON ---
def heartbeat_loop():
while not shutdown_flag:
phrase = random.choice(HEARTBEAT_PHRASES)
spinner = SPINNER_FRAMES[frame % 4]
print(f" {spinner} {phrase}...")
time.sleep(HEARTBEAT_INTERVAL)
# --- PSEUDO-CODE ---
FUNCTION heartbeat_loop():
LOOP until the user shuts down:
PICK a random fun phrase from the list
e.g., "scanning the deep blue for whales"
e.g., "sonar pinging the deep"
e.g., "patience pays - whales are coming"
PICK the next spinner animation frame (🌊 rotating)
PRINT the spinner + phrase to the terminal
WAIT 10 seconds
REPEAT# --- PYTHON ---
def signal_handler(signum, frame):
global shutdown_flag
shutdown_flag = True
ws_app.close()
elapsed = time.time() - stats['started_at']
print(f"Session: {stats['trades_seen']} trades, "
f"{stats['whales_printed']} whales in {elapsed/60:.0f} min")
print(f"Biggest whale: ${stats['biggest_whale_usd']:,.2f}")
# --- PSEUDO-CODE ---
FUNCTION signal_handler(triggered when user presses Ctrl+C):
SET shutdown flag to TRUE (tell all loops to stop)
CLOSE the WebSocket connection cleanly
CALCULATE how long the session lasted
PRINT session summary:
Total trades seen through the stream
Total whales (trades >= $1,000) displayed
Session duration in minutes
The biggest whale trade seen (and which market)
EXIT the program cleanly