Stop Missing PolyMarket Alpha: polyterm Puts Whale Tracking in Your Terminal

Stop Missing PolyMarket Alpha: polyterm Puts Whale Tracking in Your Terminal

Every morning, thousands of prediction market traders wake up to the same nightmare. While they slept, a whale dumped $50,000 into a political market. An insider with 80% historical accuracy quietly accumulated YES shares. A cross-platform arbitrage gap between PolyMarket and Kalshi opened—and closed—before their coffee finished brewing. By the time they open their browser, the alpha is gone. Buried in Discord noise. Lost in Twitter's algorithm. Expensive.

What if your terminal could whisper these secrets in real-time?

Meet polyterm—the open-source, terminal-based intelligence layer that transforms your command line into a PolyMarket war room. No browser tabs. No notification fatigue. Just pure, structured alpha flowing through ASCII charts and WebSocket-fed data streams. Built by nytemode, battle-tested with 1,068 tests, and trusted by traders who refuse to trade blind.

This isn't another API wrapper. This is polyterm: 73+ interactive TUI screens, 20+ analytics features no other CLI offers, and a stateful SQLite database that makes your research compound over time. Ready to stop missing moves? Let's dive in.

What is polyterm?

polyterm is a powerful, terminal-based monitoring and analytics tool for PolyMarket prediction markets. Created by the team at nytemode, it represents a fundamental shift in how sophisticated traders interact with prediction market data—moving from browser-based dashboards to keyboard-driven, terminal-native workflows.

The project emerged from a clear gap in the PolyMarket ecosystem. While the official PolyMarket CLI provides basic API access, it lacks the analytical depth, visual feedback, and stateful intelligence that serious traders need. polyterm fills this void by functioning as an analytics and intelligence layer rather than a simple wrapper.

What makes polyterm genuinely different? Three architectural decisions set it apart:

• Terminal-native visualization: ASCII line charts, sparklines, depth charts, and side-by-side market comparisons—all rendered without leaving your terminal. No Electron bloat. No browser memory leaks.
• Stateful local intelligence: A SQLite database (~/.polyterm/data.db) that accumulates value over time. Bookmarks, price alerts, trade journals, position tracking, screener presets, and recently viewed markets persist between sessions.
• Zero custody risk: View-only wallet features. No private keys ever touch the system. No attack surface for key theft.

The project has evolved rapidly through aggressive iteration. Version 0.10.0 introduced real-time WebSocket order books with sub-second updates. Version 0.9.1 completed the CLOB V2 migration. Each release hardens reliability—exponential backoff retry logic, shared cross-process rate limiting, and automatic REST fallbacks when WebSocket connections fail.

With 1,068 passing tests across API, core logic, CLI, TUI, and database layers, polyterm isn't experimental software. It's production-grade infrastructure for prediction market intelligence.

Key Features That Separate polyterm from Everything Else

The polyterm feature set reads like a wishlist from professional prediction market traders. Here's the technical breakdown of what actually matters:

Real-Time Market Intelligence

• polyterm monitor: Live market tracking with configurable refresh rates, sorting by volume/probability/recency, and JSON output for scripting pipelines
• polyterm live-monitor: Dedicated terminal window for focused monitoring with WebSocket-fed updates
• polyterm orderbook --live: Real-time WebSocket depth display with keyboard controls (P=pause, D=cycle depth, Q=quit), automatic REST fallback, and instant settlement detection via market_resolved events

Whale & Smart Money Analytics

• polyterm whales: Volume-based whale detection with configurable thresholds (--min-amount 50000)
• polyterm wallets: Three-tier wallet classification—whales (by volume), smart money (>70% win rate), and suspicious (high risk score)
• polyterm clusters: Same-entity wallet group detection using behavioral fingerprinting
• polyterm follow: Copy-trading workflow with direct position tracking

Arbitrage Detection (Cross-Platform)

• polyterm arbitrage: Intra-market YES+NO price inefficiencies, correlated market discrepancies, and Kalshi cross-platform spreads (--include-kalshi)
• polyterm negrisk: Multi-outcome market arbitrage scanning for NegRisk pools
• Configurable minimum spread thresholds with dynamic fee awareness

Signal-Based Predictions (No "AI" Hype)

Rebranded from misleading "AI predictions" in v0.9.0, the prediction engine uses multi-factor signal aggregation:

• Price momentum and trend analysis
• Volume acceleration patterns
• Whale behavior pattern matching
• Smart money positioning signals
• Technical indicators (RSI)
• Time-to-resolution decay modeling

Risk & Compliance Layer

• polyterm risk: Market risk scoring with A-F grades
• polyterm wash_trade_detector: Wash trade pattern identification
• polyterm uma_tracker: UMA oracle dispute risk analysis
• Insider detection scoring: Behavioral anomaly flagging

Terminal UI Excellence

• 73+ interactive TUI screens with menu navigation, contextual help (h/?), and an onboarding tutorial (t)
• Lazy-loaded CLI: 81 commands load on-demand, eliminating startup lag
• Multi-channel alerts: Telegram, Discord, system notifications, and sound alerts with configurable severity filtering

Real-World Use Cases Where polyterm Dominates

Scenario 1: The Pre-Debate Whale Hunter

It's 8 PM. A presidential debate starts in 60 minutes. You launch polyterm whales --hours 24 --min-amount 50000 and spot three wallets that have each deposited $75K+ into "Will Trump mention Biden's age?" in the last 4 hours. One wallet has 78% historical accuracy. You pull polyterm predict --market <id> --min-confidence 0.7—signal confidence: 0.82. You check polyterm orderbook <token> --chart—depth supports a $2K position without significant slippage. Decision made. Position entered before the broadcast starts.

Scenario 2: The Cross-Platform Arbitrageur

Kalshi lists "Will CPI exceed 3.2%?" at 62% YES. PolyMarket has the same event at 58% YES. You run polyterm arbitrage --include-kalshi --min-spread 0.025 and the opportunity surfaces instantly. The scanner accounts for both platforms' fee structures, calculates net profit after CLOB V2 dynamic fees, and flags the position size needed for meaningful return. You execute on both sides before the spread compresses.

Scenario 3: The Risk-Manager Building a Portfolio

You're running 12 open positions across political, crypto, and macro markets. polyterm mywallet --pnl shows consolidated P&L with correct NO-side profit calculation (fixed in v0.8.4—previously inverted). polyterm risk grades each market A-F. polyterm simulate -i lets you stress-test new positions with Kelly Criterion sizing that accounts for protocol fees (fixed in v0.8.2, updated for CLOB V2 in v0.9.1). Your database accumulates 30 days of position history for pattern analysis.

Scenario 4: The Signal System Builder

You pipe polyterm predict --format json | jq '.predictions[] | select(.confidence > 0.7)' into a personal notification system. polyterm monitor --format json --once | jq '.markets[] | select(.probability > 0.8)' feeds a spreadsheet. polyterm alerts --type arbitrage --unread triggers Telegram messages via webhook. You're not trading manually anymore—you're operating a systematic intelligence infrastructure.

Step-by-Step Installation & Setup Guide

Option 1: PyPI Install (Recommended)

# pipx provides clean isolation without virtualenv management
pipx install polyterm

# Verify installation
polyterm --version

Option 2: One-Command Install

# Downloads and executes install script from main branch
curl -sSL https://raw.githubusercontent.com/NYTEMODEONLY/polyterm/main/install.sh | bash

Option 3: Manual Development Install

# Clone repository
git clone https://github.com/NYTEMODEONLY/polyterm.git
cd polyterm

# Create isolated environment
python↗ Bright Coding Blog -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Editable install with dev dependencies
pip install -e ".[dev]"

# Run full test suite to verify
pytest

First Launch & Configuration

# Launch interactive TUI with tutorial
polyterm

# First-time users: press 't' for interactive tutorial covering
# prediction market basics, whale tracking, and arbitrage detection

# Configure notification channels (optional but recommended)
polyterm config --set notification.telegram.enabled true
polyterm config --set notification.telegram.bot_token "YOUR_BOT_TOKEN"
polyterm config --set notification.telegram.chat_id "YOUR_CHAT_ID"

# Test notification delivery
polyterm alerts --test-telegram
polyterm alerts --test-discord

Configuration File Location

# Edit directly for advanced configuration
~/.polyterm/config.toml

Key defaults to customize:

• whale_tracking.min_whale_trade: Volume threshold for whale flagging (default: $10,000)
• arbitrage.min_spread: Minimum profitable spread (default: 2.5%)
• alerts.probability_threshold: Price movement alert sensitivity (default: 5%)
• display.refresh_rate: TUI refresh interval in seconds (default: 2)

REAL Code Examples from the Repository

Example 1: Whale Detection with JSON Pipeline

# Find high-volume whale activity in last 24 hours, output as JSON
polyterm whales --hours 24 --min-amount 50000 --format json

This command surfaces wallets exceeding your volume threshold. The --format json flag enables scripting integration—pipe into jq, log to files, or feed monitoring systems. The --hours parameter controls lookback window; --min-amount filters noise from retail flow. Critical for identifying accumulation patterns before price moves.

Example 2: Live Order Book with Depth Analysis

# Real-time WebSocket order book with ASCII depth chart
polyterm orderbook <market_token_id> --live --chart --depth 50

# Keyboard controls during live session:
#   P = pause/resume updates
#   D = cycle depth levels (10/20/50)
#   Q = quit

The --live flag activates WebSocket subscription to wss://ws-live-data.polymarket.com with automatic REST fallback. The --chart renders ASCII bid/ask depth visualization. --depth 50 shows 50 levels per side. This replaced broken Subgraph-dependent workflows in v0.7.4 and added settlement detection in v0.10.0.

Example 3: Signal-Based Prediction with Confidence Filtering

# Generate predictions for top 10 markets, 24-hour horizon, high confidence only
polyterm predict --limit 10 --horizon 24 --min-confidence 0.7 --format json

# Predict specific market by ID
polyterm predict --market <market_id> --format json | jq '.signals'

Critical technical note: These are signal-based predictions, not AI/LLM outputs. The engine combines six orthogonal signals: price momentum (trend analysis), volume acceleration, whale behavior patterns, smart money positioning, RSI technical indicator, and time-to-resolution decay. Each signal receives weighting; confidence scores reflect signal agreement strength. The --min-confidence 0.7 filter eliminates low-conviction predictions.

Example 4: Arbitrage Scanning with Cross-Platform Support

# Scan for arbitrage with 2.5% minimum spread, include Kalshi comparison
polyterm arbitrage --min-spread 0.025 --limit 10 --include-kalshi

# JSON output for automated execution systems
polyterm arbitrage --format json | jq '.opportunities[] | select(.net_profit > 2)'

Three arbitrage types detected:

• Intra-market: YES + NO prices sum to < $1.00 (guaranteed profit after fees)
• Correlated markets: Similar events with price discrepancies
• Cross-platform: PolyMarket vs Kalshi price differences (requires Kalshi API key)

Fee calculations use CLOB V2 dynamic fee curves (updated v0.9.1), not naive 2% assumptions. The --include-kalshi flag was broken in early versions; v0.7.5 corrected fee math, and v0.10.0 added WebSocket price integration for lower-latency detection.

Example 5: View-Only Wallet Tracking

# Connect wallet address (NO PRIVATE KEYS - view only)
polyterm mywallet --connect

# View open positions with correct NO-side P&L calculation
polyterm mywallet -p

# P&L summary with streak analysis
polyterm mywallet --pnl

# Analyze any wallet by address
polyterm mywallet -a 0x123...

# Disconnect when done
polyterm mywallet --disconnect

Security architecture: This feature intentionally requires only your public address. No wallet connection, no signing, no private key exposure. The system queries PolyMarket's Data API for position and trade history. P&L calculation was critically broken for NO positions until v0.8.4 (stored as 'NO' uppercase, queried as 'no' lowercase—returning inverted profits). This fix alone justifies upgrading from earlier versions.

Advanced Usage & Best Practices

Building Systematic Workflows

Combine polyterm commands with Unix pipes for automated intelligence flows:

# Cron-friendly: dump high-confidence predictions to file
polyterm predict --format json --min-confidence 0.75 --once > /var/lib/predictions/$(date +%Y%m%d-%H%M).json

# Alert on whale activity exceeding threshold
polyterm whales --format json --min-amount 100000 | jq -e '.whales | length > 0' && polyterm alerts --test-telegram

Database Maintenance

# Database auto-prunes at 10,000 rows (>30 days old), but manual cleanup:
rm ~/.polyterm/data.db  # Nuclear option: reset all state

# Backup before major version upgrades
cp ~/.polyterm/data.db ~/.polyterm/data.db.backup

Performance Optimization

• Use --once flag for scripting (prevents TUI overhead)
• Leverage --format json for downstream processing
• Enable SharedRateLimiter for concurrent processes (v0.10.0): file-lock-based coordination prevents API rate limit violations across multiple terminal sessions

WebSocket Reliability

The two-tier resilience model (v0.10.0) handles connection instability:

• Inner loop: automatic reconnection with exponential backoff
• Supervisor: restarts entire connection cycle after 3 failed retries with 60s cooldown
• Whale tracker falls back to REST polling (5s interval) on permanent WebSocket failure

Comparison with Alternatives

Verdict: The official CLI provides basic API access. Browser trading offers visual familiarity but lacks systematic intelligence. polyterm is the only solution combining terminal-native workflow, analytical depth, and stateful accumulation of trading intelligence.

FAQ: Common Developer & Trader Questions

Is polyterm free to use?

Yes—completely. Version 0.9.0 removed all premium/paid-tier language. No subscriptions, no gated features, no "pro" version. MIT licensed.

Does polyterm store my private keys?

Never. Wallet features are view-only. You provide a public address; the system queries PolyMarket's Data API. No signing, no connection, no key storage.

How does polyterm handle API rate limits?

SharedRateLimiter (v0.10.0) coordinates across all processes using file-based locks. Default: 60 requests/minute shared. Automatic stale lock cleanup for crashed processes.

What's the difference between "AI predictions" and "signal-based predictions"?

Version 0.9.0 removed all "AI" branding. The engine uses momentum, volume, whale, smart money, and RSI signals—no LLM or neural network. The rebrand reflects honest technical architecture.

Can I run polyterm on Windows?

Yes, with caveats. The SharedRateLimiter gracefully falls back to per-process limiting on Windows or permission errors. Most features work; some TUI rendering may vary by terminal emulator.

How reliable is the live order book data?

WebSocket-fed with automatic REST fallback. The two-tier supervisor restarts connections after failures. Settlement detection via market_resolved events provides instant resolution notification.

What happened to portfolio tracking features?

PolyMarket's Subgraph was deprecated by The Graph. polyterm migrated to local database tracking (v0.7.4) and Data API integration. Some historical features are limited during this transition.

Conclusion: Your Terminal Is Now Your Edge

Prediction markets reward information velocity. The trader who spots whale accumulation first, who catches arbitrage before spread compression, who systematically tracks smart money positioning—that trader compounds edge while others refresh browsers and hope.

polyterm transforms your terminal from a passive shell into an active intelligence platform. With 1,068 tests ensuring reliability, 73+ TUI screens enabling discovery, and a development velocity that ships WebSocket live feeds and CLOB V2 migrations in weeks, this isn't a side project. It's infrastructure.

The painful alternative? Alt-tabbing between PolyMarket tabs, losing track of watched markets, missing alerts in notification noise, and never accumulating institutional memory of your research. Every session starts from zero.

Stop starting from zero.

Install polyterm today. Run pipx install polyterm. Launch polyterm, press t for the tutorial, and experience what terminal-native prediction market intelligence feels like. Your future self—watching that whale move hit your Telegram alert while others are still loading their browsers—will thank you.

Star the repo. Open an issue. Join the traders who refuse to trade blind.

Built for the PolyMarket community. A nytemode project.