Trade Hunter 🎯

The institutional edge for prediction market flow.

In prediction markets, alpha isn't just about knowing the news first—it's about seeing the money move before the news breaks. By the time a headline hits social media, the orderbook has already repriced.

Trade Hunter is a real-time, locally-hosted intelligence dashboard built to catch coordinated institutional flow, aggressive hedging, and mathematically improbable volume spikes across prediction markets (like Kalshi) the exact second they happen.

---

🛰️ Trade Hunter vs. Traditional SaaS

While cloud-based prediction trackers are convenient, Trade Hunter is built for traders who prioritize privacy, speed, and deep technical control.

Feature	Trade Hunter (Local-First)	Standard SaaS Tools
Data Privacy	100% Private. Your watchlists and SQLite database stay on your hardware.	Your activity and interests are stored on third-party servers.
Execution Latency	Direct. Connects your machine directly to Kalshi WebSockets.	Delayed. Data often passes through a middle-man server first.
Intelligence	Dual-AI. Use your own API keys for transparent, un-metered analysis.	Opaque, "black box" logic that you cannot audit or tune.
Customization	Open Logic. Modify the Poisson thresholds or AI prompts yourself.	"One size fits all" alerts and fixed configurations.
Cost	Free & Open Source. No monthly subscriptions to maintain access.	Recurring monthly fees.

---

🔬 Detection Logic: The Math Behind the Signal

Trade Hunter doesn't just alert on high volume; it identifies statistically improbable events using high-frequency anomaly detection.

Whale Cluster Probability

To separate coordinated institutional "sweeps" from organic retail flow, we model trade frequency using a Poisson Distribution. When $\ge 3$ trades from the 99th percentile of historical volume occur within a rolling 120-second window, we calculate the probability $P$ of that cluster occurring by chance:

$$P(k; \lambda) = \frac{\lambda^k e^{-\lambda}}{k!}$$

• $\lambda$ (Lambda): The expected arrival rate of "Whale" trades based on the 24-hour baseline.
• $k$: The number of observed large trades in the current window.

If the resulting probability is $p < 0.01$, the system triggers a Purple Neon Edge alert. This signals high-conviction institutional movement with less than a 1% chance of being random market noise.

---

⚡ Key Features

• 🐋 Whale Cluster Detection: Real-time Poisson probability modeling to catch the biggest players.
• 🧠 Dual AI Analysts (Claude + Perplexity): Integrated agents analyze order flow context and label each move as real, noise, or uncertain — shown as an AI: pill on every card, separate from the detector tier.
• ⚙️ Autonomous Tuning System: An Advisor suggests threshold corrections based on false positives, while a Governor ensures logic stays within safe baseline rules.
• 📈 Dynamic Baseline Detector: Flags flow based on volume delta multiples rather than static numbers.
• 🔔 Smart Discord Integration: Routes specific topics (Crypto, Elections, etc.) to dedicated channels with AI-filtered signal verification.
• 💾 Zero-Friction Local Runtime: Lightweight SQLite backbone with self-cleaning retention, running on localhost:8765.

---

🚀 Quick Start

Commercial Edition (Windows exe)

1. Download the Trade Hunter executable (trade-hunter-*.exe) from Gumroad
2. Double-click — browser opens automatically at http://127.0.0.1:8765
3. Starts in Simulation mode instantly. No Python, no install.

Public / Simulation Edition (from source)

Requires Python 3.11+.

git clone https://github.com/lweiss01/trade-hunter.git
cd trade-hunter
pip install -e .[integrations]
python -m app

Open http://127.0.0.1:8765 in your browser.

Both editions start in Simulation mode by default — no API keys needed to try the dashboard.

---

📊 Alert Tiers

Each alert is graded into a visual tier so you know exactly how to react:

Tier	Meaning	Visual
watch	Early — a directional bias is present, but below the notable thresholds.	Standard
notable	Significant — both the volume and price-move qualifiers are clearly met.	Yellow Edge
signal	Strongest score tier — volume $\ge 3\times$ and price move $\ge 1.75\times$ the minimum thresholds.	Red Neon Edge
whale-cluster	Statistical anomaly — coordinated whale entry ($\ge 3$ 99th-percentile trades in 120s, Poisson $p < 0.01$).	Purple Neon Edge
cross-venue divergence	The same contract priced differently across venues (e.g. Kalshi vs Polymarket), flagged from cross-venue ingest.	Blue Edge

---

⚙️ Configuration & Live Mode

To switch to live Kalshi data and enable the AI Analysts, create a .env file in the root directory:

# Core Modes
ENABLE_SIMULATION=false
ENABLE_KALSHI=true

# Kalshi Credentials
KALSHI_API_KEY_ID=your-key-id
KALSHI_PRIVATE_KEY_PATH=/path/to/kalshi.key

# Seeds your watchlist on FIRST RUN only. After that, tickers are managed in
# the app's Markets page and stored in data/watchlist.json — so app updates
# never lose your saved markets.
KALSHI_MARKETS=KXBTC15M,KXTOPCHEF-26DEC31

# AI Analyst Integrations
ANTHROPIC_API_KEY=sk-ant-api03...  # Primary Analyst
PERPLEXITY_API_KEY=pplx-...        # Fallback Analyst

# Notifications
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

---

Market Resolution Magic

You don't need to hunt for exact contract IDs. Whether you add markets in the app's Markets page or seed them via KALSHI_MARKETS, each entry accepts:

• Series Slugs (e.g., KXBTC15M) → Auto-resolves to the currently open 15-minute BTC market.
• Event Tickers (e.g., KXTOPCHEF) → Auto-subscribes to all open sub-markets for that event.
• Specific Tickers → For tracking an exact, granular contract.

Manage your watchlist directly from the Dashboard's Markets page — add/remove without ever restarting the server. Your list is saved to data/watchlist.json and preserved across app updates; KALSHI_MARKETS in .env only seeds it on first run.

---

📊 Reading the Dashboard

When an alert fires it is graded into one of the visual tiers described under Alert Tiers above. Each card also shows the AI analyst's own read as an AI: pill (real / noise / uncertain) — a separate judgment from the detector tier.

---

The 10-Minute Freshness Window:

In live mode, the dashboard exclusively displays events from the last 10 minutes. If the panels look empty, check the status pills at the top—if kalshi seen is updating, data is flowing, but the markets are just genuinely quiet.

---

🛠️ System Architecture

• Database: SQLite (trade_hunter.db). Survives restarts, auto-cleans events older than RETENTION_DAYS (default 7).
• Single-Instance Guardian: The exe automatically terminates any hanging instance on the same port before launching — no zombie processes, no port conflicts.
• Testing: Run py -m app --smoke-test to safely test the detector pipeline and AI integrations locally without touching live order flow.

---

Built to separate the signal from the noise.