How It Works
Scan Schedule & Rate Limits
The cron runs every 15 minutes. Expensive phases are distributed across the four 15-minute ticks (:00 / :15 / :30 / :45) to stay under the Worker CPU budget. Fast DB-only work (signals, alerts) runs on every tick so Polly always has fresh data to act on.
Every tick (runs on :00, :15, :30, :45)
| Phase | What It Does | Rate Limit Protection |
|---|---|---|
| Untraded Resolution | Closes out expired opportunities with would-have-won / would-have-lost outcomes | DB-only |
| Signal Generation | Converts up to 50 opportunities into agent-consumable signals; auto-closes live trades | DB-only |
| Opportunity Expiry | Expires stale opportunities (timing: 4h, others: 24h, or market close) | DB-only |
| Alert Checks | Creates alerts for new high-score whales and high-edge opportunities | DB-only |
Distributed phases
| Tick | Phase | What It Does | Rate Limit Protection |
|---|---|---|---|
| :00 | Whale Detection | Scans 80 candidate markets per hour, fetches 200 trades per market from Data API | 5 markets in parallel, 500ms between batches |
| :15 | Market Sync | Fetches up to 3,000 events from Gamma API (30 pages × 100) | 200ms delay between pages |
| :15 | Price Tracking | Snapshots prices for active markets and detects price spikes | DB-only |
| :15 | Backfill Sweep | Fetches trader positions for 30 markets per hour that resolved in the last 48 hours (older markets get aged out by cleanup before they can contribute to the sharp aggregate) | 5 parallel, 500ms between batches |
| :15 | Wallet Promotions | Auto-promotes winning wallets and co-movement followers to watchlist | DB-only |
| :30 | Broad Whale Sweep | Scans 30 active markets per hour (no keyword filter) to discover whales in unfiltered universe | 5 parallel, 500ms between batches |
| :30 | Timing Scan | Scores markets closing within 14 days, creates up to 50 timing opportunities | DB-only |
| :45 | Market Sync | Second market sync + stale market resolution (50 markets/hour) | 150ms between resolution calls |
| :45 | Stats | Strategy stats, category stats. Sharp wallet cache refreshes twice daily (00:45 and 12:45 UTC). | DB-only |
| :45 | Data Lifecycle Cleanup | Ages out resolved positions, stale co-movements, expired signals — see Data Retention below | 100k rows/table cap per run |
| :45 | Wallet Enrichment | Enriches watchlisted wallets (10/hour) with full trade history from Data API | Data API, sequential |
External APIs used: Gamma API (market data, public, no auth), Polymarket Data API (trade history, public, no auth). The CLOB API (order book) requires an API key and is not used in automated scans.
Data Retention & Lifecycle
Every hour at :45 the cleanup job ages out data that is no longer actionable. Aggregated results (sharp wallet cache, strategy stats, category stats) are preserved indefinitely — the cleanup only removes the raw per-row detail once it has been baked into those aggregates.
| Table | Retention | Why |
|---|---|---|
| whale_trades | 30 days | Raw trade stream for audit / replay |
| opportunities | 30 days (expired / resolved only) | Active opportunities kept forever; terminal states dropped after 30d |
| trading_signals | 14 days (expired only) | Active signals kept forever; expired ones have no replay value |
| markets | 30 days past end_date | Deleted after child tables are cleaned first |
| price_history | 7 days | Used for spike detection — older history not actionable |
| price_spikes | 30 days | Historical record of detected spikes |
| alerts | 30 days (read only) | Unread alerts preserved indefinitely so nothing gets missed |
| polly_logs | 90 days | Audit trail of Polly's decisions — kept longer than other tables |
| live_trades, sharp_wallet_cache, watchlist, strategy_stats, category_stats, wallet_identities | Forever | Aggregates and user-curated data — never auto-deleted |
Cleanup is bounded at 100,000 rows per table per run, so the hourly write burst stays well under the D1 write budget even when backlogged. If a table needs a larger one-off trim, it can be triggered via POST /api/scan/cleanup?limit=N.
Market Universe
Markets are sourced from the Polymarket Gamma API ordered by volume (highest first).
| Filter | Value | Why |
|---|---|---|
| Max pages | 30 (3,000 events) | Captures the vast majority of active Polymarket events |
| Close window | 30 days | Focus on near-term actionable markets |
| Price range | 2¢ – 98¢ | Excludes near-certain outcomes with no edge |
| Status | Active, not closed | Only scan live markets with tradeable outcomes |
Classification
- Category: auto-detected from question text — politics, legal, finance, crypto, technology, sports, entertainment, weather
- Region: US EU ASIA GLOBAL — detected by keyword matching. EU/Asia/Global keywords are checked first; unmatched markets default to US (Polymarket is a US-based platform).
Noise Filters
The following market types are excluded from Opportunities and Signals by default (whale buying in these markets is normal trading, not insider signal):
- Weather: temperature, rainfall, precipitation, weather forecasts
- Commodity futures: Gold (GC), Silver (SI), Crude Oil (CL), Natural Gas (NG), Copper (HG)
- Price prediction: "settle at", "hit (HIGH)", "hit (LOW)" markets
- Crypto price bets: "price of Bitcoin above/below", "price of Ethereum above/below"
- Index daily moves: S&P 500, Nasdaq, Dow Jones "Up or Down" markets
Markets with genuine insider edge are kept: political decisions, regulatory rulings, corporate events, legal outcomes, IPOs, elections, arrests, investigations.
Polly can bypass filters with exclude_noise=false.
Whale / Insider Detection
Scans Polymarket for unusually large trades that may indicate insider knowledge. Focuses on markets where non-public information is plausible — political decisions, regulatory rulings, corporate announcements, legal outcomes.
1. Market Selection
Two-tier candidate selection identifies markets where insider activity is plausible:
- Priority 1: Markets matching insider-prone keywords (any volume): executive order, pardon, veto, nomination, cabinet, appointment, tariff, sanctions, FDA approval, SEC ruling, FTC, FCC, EPA ruling, indictment, verdict, settlement, guilty, convicted, earnings, merger, acquisition, IPO, airdrop, hack, exploit, lawsuit, investigation, subpoena, antitrust, bankruptcy, default, recall, patent, delisting, spin-off, buyback, guidance, forecast
- Priority 2: Markets with volume > $25K (whales also trade high-volume markets)
All candidates must have: price between 2¢ and 98¢, active outcome tokens, not yet resolved.
2. Whale Trade Detection
For each candidate market, the 200 most recent trades are fetched from the Polymarket CLOB API. The median trade size (in USD) is calculated, then each trade is evaluated. A trade is flagged as a "whale" if it meets both conditions:
- Trade size ≥ 5x the median trade size for that market
- Trade size ≥ $500 USD (absolute floor)
Whale trades are then clustered by wallet address to identify accumulated positions. A trade is marked contrarian if the whale is betting against consensus: buying YES below 25¢ or selling YES above 75¢ (and vice versa for NO).
"Size" on the dashboard = total USD of all whale-qualifying trades by that address in that market. "Trades" = number of individual whale-qualifying trades by that address.
3. Insider Score (0–100)
Each whale address gets a composite score from 5 factors:
| Factor | Max Points | How It's Calculated |
|---|---|---|
| Whale Multiple | 25 | How many times larger than median trade size. min(25, multiple × 2.5) — min threshold 5x. |
| Contrarian | 25 | Betting against market consensus (e.g., big YES buy when price <25¢) = 25 pts. With consensus = 5 pts. |
| Category | 20 | Political/regulatory = 20, legal = 18, corporate = 15, crypto = 12, other = 5. Boosted by keyword density. |
| Concentration | 15 | What share of recent market volume comes from this one address. min(15, concentration × 75). |
| Timing | 15 | How close to the market's resolution date. Last 20% of life = 15 pts, last 40% = 10 pts, last 60% = 5 pts. |
4. Throughput
Each 15-minute cron cycle scans a rotating batch of 80 candidate markets. With 4 cycles per hour, this covers 320 unique markets/hour. Candidate markets are selected in two tiers: keyword-matching markets first (any volume), then high-volume (>$25K) markets. Markets rotate via offset so the full candidate pool is covered over multiple hours.
- 200 trades fetched per market from the Polymarket Data API
- 5 markets analyzed in parallel per batch
- 500ms delay between batches to respect rate limits
- Minimum 10 trades required per market to perform analysis (skip thin markets)
5. Wallet Tracking
Every whale trade and aggregated position is stored per wallet address. The Wallets page provides a searchable database of all tracked whale addresses with:
- Track record: wins vs losses computed from resolved markets (price ≤3¢ or ≥97¢)
- Volume & frequency: total USD traded, number of markets, trade count
- Scoring history: average and max insider scores across all appearances
- Directional bias: YES vs NO bet ratio
- Detail view: click any wallet to see all positions with entry prices, current prices, and outcomes
On the Opportunities page, whale addresses show a mini track record ("5 mkts, $12,340") linking to the full wallet detail.
Timing Opportunities
Finds announcement-driven markets closing soon where the answer may be knowable before the market fully prices it in.
Pipeline
- Identify — find markets closing within 14 days that are announcement-driven (FDA, court, earnings, policy, geopolitical, etc.)
- Classify — sports, entertainment, weather are tagged and excluded from opportunities/signals (see Noise Filters above)
- Score — announcement keywords, off-hours close, urgency, price uncertainty, region relevance, resolution source. Expanded keywords include: investigation, subpoena, recall, bankruptcy, patent, antitrust, rate cut/hike, summit, treaty, ceasefire, election, referendum, impeach
- Research — Polly analyzes top candidates to hunt for the answer
- Signal — if Polly finds an edge, creates an opportunity with trade direction
The key insight: the outcome often becomes known (via announcement, filing, press release) before the market fully adjusts — especially during off-hours when fewer traders are watching.
AI Research (Information Asymmetry)
Uses Polly (local Ollama) to deeply research individual markets and estimate the true probability, looking for cases where the crowd is wrong.
Candidate Selection
- Closing within 7 days (near-term, actionable)
- Announcement-driven categories: politics, economics, finance, technology, science, crypto, legal
- Excludes: sports, entertainment, pop culture, esports
- Mid-range prices: not near-certain (<5¢ or >95¢)
Research Process
Polly analyzes each candidate by:
- Identifying what data/evidence determines the outcome
- Checking historical base rates and precedents
- Assessing current conditions and recent developments
- Identifying crowd blind spots and biases
- Generating a calibrated probability estimate
An opportunity is created when the weighted edge exceeds 8% (edge = |AI probability − market price|, weighted by confidence: high=1.0, medium=0.6, low=0.3).
Sharp Following
Identifies wallets with proven prediction accuracy and surfaces their current positions as high-confidence signals. While whale detection flags suspicious activity in real-time, sharp following validates who is consistently right.
How Sharps Are Identified
Every whale trade and position is stored with the wallet address. When a market resolves (price ≤3¢ or ≥97¢), the system retroactively checks whether each whale's position was on the winning side. Over time this builds a win/loss record per wallet.
A wallet qualifies as a "sharp" when it meets both thresholds (adjustable via filters):
How It Complements Other Strategies
| Strategy | Signal Type | Time Horizon |
|---|---|---|
| Whale Detection | Pattern-based — "this trade looks insider-ish" | Real-time (current cycle) |
| Sharp Following | Track-record-based — "this wallet has proven they know something" | Historical (validated over time) |
| Timing | Structural — announcement-driven markets closing in off-hours | Near-term (14-day window) |
| AI Research | Analysis-based — Polly finds the crowd is wrong | Near-term (7-day window) |
What to Watch For
- Current open positions: When a sharp wallet takes a new position, it's a high-confidence signal
- Convergence: Multiple sharps betting the same way on the same market is a strong indicator
- Contrarian sharps: A sharp with a high win rate betting against consensus is especially notable
- Resolved history: Review their full track record to understand if their edge is domain-specific (e.g., only politics)
The Sharps page shows qualifying wallets with expandable rows revealing both current open positions and resolved bet history. Click any wallet to view its full detail on the Wallets page.
Cross-Entity Linking & Market Close Times
Every entity in the system is linked back to its parent opportunity, making it easy to trace the full lifecycle of a detection from initial whale trade through to signal, live trade, and resolution.
| Page | Links To | How |
|---|---|---|
| Opportunities | Signal # | Shows latest signal generated from this opportunity |
| Signals | Opp # | Links back to the source opportunity |
| Whale Tracker | Opp #, Signal # | Matched via market ID + wallet address to the opportunity that flagged this whale |
| Trades | Opp # | Each live trade tracks which opportunity triggered it |
All clickable IDs use highlight navigation — clicking "Opp #478" on the Whale Tracker navigates to the Opportunities page and scrolls to that row with a green highlight.
The "Closes" column appears on Opportunities, Signals, Whale Tracker, and Trades pages, showing
a countdown to when the underlying market resolves (e.g., "4h left", "2d left", "Closed"). This uses the market's
end_date from the Polymarket API. Color-coded: red = <4 hours,
yellow = <24 hours, gray = >24 hours or closed.
Live Trading
Polly executes trades against active signals and reports them back to the API. Trades
are tracked in the live_trades table and auto-closed server-side when
the underlying market resolves.
- Max position: $100 per trade
- Minimum edge to act: 3%
- Minimum confidence: 60% (30% for legal-category markets)
- 2% winner fee applied on close (Polymarket fee structure)
- Auto-close on market resolution via scheduled cron
Polly Cron Schedule
Polly runs on a set of cron schedules from the local machine, feeding data into The Edge API.
| Schedule | Job | Uses Qwen? |
|---|---|---|
| :00, :30 | Tier 1 signal scan + auto-execute | Yes |
| :05 | Opportunity research — AI analysis | Yes |
| :07, :22, :37, :52 | Heartbeat — keeps dashboard alive | No |
| :20 | Whale winners — follow quality wallets | Yes |
| 7am AEST daily | Daily summary | No (shell only) |
Signal Lifecycle
Actionable opportunities are published as agent-consumable trading signals for automated execution.
| Constraint | Value | Purpose |
|---|---|---|
| Min edge | ≥ 3% (2% for legal) | Only signal opportunities with meaningful edge. Legal markets have lower threshold due to structural edge. |
| Min confidence | ≥ 35% (25% for legal) | Filter out low-conviction detections. Legal markets get relaxed threshold — complexity creates mispricing, whale signals are more reliable. |
| Actions included | buy_yes, buy_no, monitor | Monitor signals from timing appear on dashboard only (no live trade) |
| Max per cycle | 50 signals | Cap to prevent signal flood |
| Signal expiry | 4 hours or market close | Whichever comes first |
| Opportunity expiry | 24 hours | Stale opportunities auto-expire |
| Deduplication | 1 active signal per opp | Won't regenerate signal if one already active |
- Includes CLOB token ID for direct Polymarket execution
- Stale signals cleaned up every 15 minutes
- Legal market upweighting: Legal/law category markets have lower thresholds (2% edge, 25% confidence for signals; 2% edge, 30% confidence for Polly to act) because complexity creates mispricing, outcomes are definitive, and information asymmetry is real
Signal Lifecycle
Detected → Actionable (Polly may execute a live trade) → Signal Published → Expired / Resolved
Timing opportunities follow a parallel path: Detected → Monitor Signal (dashboard only, no live trade) → Actionable (if Polly confirms edge) → Signal Published