Kalshalyst

Contrarian prediction market scanner that finds mispricings on Kalshi using Claude Sonnet analysis, Brier score calibration, and Kelly Criterion position sizing. Five-phase pipeline: fetch markets, classify, estimate contrarian probabilities, calculate edge, and alert. Tracks estimate accuracy over time so you know when to trust the signal. Part of the OpenClaw Prediction Market Trading Stack — feeds edge data to Market Morning Brief and pairs with Kalshi Command Center for execution.

# Kalshalyst — Contrarian Prediction Market Scanner

## Overview

Kalshalyst is a complete intelligence system for finding and trading prediction market opportunities. It combines:

- **Claude Sonnet contrarian estimation** — sees market prices and finds reasons they're WRONG
- **Brier score tracking** — measures how well your estimates calibrate against actual outcomes
- **Kelly Criterion position sizing** — calculates optimal trade size for each opportunity
- **Five-phase pipeline** — FETCH → CLASSIFY → ESTIMATE → EDGE → ALERT

The key insight: blind estimation (not seeing prices) produces consensus-matching estimates with zero edge. **Contrarian mode** (showing Claude the price and asking it to disagree) produces opinionated, directional calls with real edge.

## When to Use This Skill

- You want to find mispricings on Kalshi prediction markets
- You're looking for contrarian opportunities where the market is wrong
- You need to track how accurate your probability estimates are over time
- You want to size positions intelligently based on edge and confidence
- You're building a systematic prediction market trading system

First run does not require Kalshi credentials. If they are missing, Kalshalyst prints a realistic demo scan and writes demo cache data so downstream tools like Market Morning Brief still have something useful to show.

## Requirements

### API Keys & Credentials

<!-- CODEX: reconciled skill requirements and cost guidance with the public code path. -->

1. **Kalshi API Key** (free at kalshi.com)
   - Sign up at https://kalshi.com
   - Navigate to Settings → API
   - Generate API credentials (key ID + private key file)
   - Cost: Free tier supports unlimited reads, small position limits

2. **Anthropic API Key** (for Claude Sonnet)
   - Create account at https://console.anthropic.com
   - Generate an API key
   - The public reference implementation calls Anthropic directly
   - Budget: variable by scan volume; expect non-zero Claude cost if you run frequent scans

3. **Polygon.io API Key** (optional, free tier available)
   - Sign up at https://polygon.io
   - Free tier includes market data + basic news
   - Cost: Free tier sufficient, paid plans for higher volume

### Python & Dependencies

- Python 3.10 or higher
- Required packages:
  ```bash
  pip install kalshi-python requests anthropic pyyaml
  ```

- Optional (for local fallback estimation):
  - Ollama (https://ollama.ai) with Qwen model
  - Install from https://ollama.ai (macOS, Linux, Windows)
  - Then: `ollama pull qwen3:latest`

## Configuration

Create or update your `config.yaml` file with:

```yaml
kalshi:
  enabled: true
  api_key_id: "your-key-id-here"
  private_key_file: "path/to/private.key"
  ticker_names: {}  # Optional: custom display names for tickers

anthropic:
  api_key: "sk-ant-..."

polygon:
  api_key: "pk_..."  # Optional

kalshalyst:
  enabled: true
  check_interval_minutes: 60
  min_volume: 50
  min_days_to_close: 7
  max_days_to_close: 365
  max_pages: 10
  max_markets_to_analyze: 50
  min_edge_pct: 3.0
  min_qwen_confidence: 0.4
  alert_edge_pct: 6.0
  max_alerts: 5
  max_fetch_seconds: 30
  page_timeout_seconds: 8
```

## The Five-Phase Pipeline

### Phase 1: FETCH — Kalshi Market Discovery

Fetches all open markets from Kalshi and applies pre-filters:

**Blocklist Filtering:**
- **Ticker prefixes**: KXHIGH, KXLOW, KXRAIN, KXSNOW, INX, NASDAQ (weather, intraday noise)
- **Category slugs**: weather, climate, entertainment, sports, social-media
- **Micro-timeframes**: "in next 15 min", "in next 5 hours" (coin flips)
- **Sports tokens**: NFL, NBA, soccer, esports (blocked from the production stack)

**Timeframe Gates:**
- Minimum days to close: 7 (default)
- Maximum days to close: 365 (default)
- Markets without expiration dates are blocked (usually garbage)

**Volume Floor:**
- Minimum volume: 50 contracts (default)
- Filters out illiquid, low-interest markets

**Price Availability:**
- Must have at least one price signal (yes_bid, yes_ask, yes_price, or last_price)
- Resolves multiple price sources (bid/ask mid preferred)

**Output:** List of ~100-500 pre-filtered markets ready for analysis

### Phase 2: CLASSIFY — Market Classification

**Status: Disabled (Qwen unreliable)** — Markets pass through with defaults.

When re-enabled, would use local Qwen to classify each market by:
- Category: politics, economics, crypto, policy, technology, etc.
- Tradability: 0.0-1.0 score (how analyzable with public info?)
- News sensitivity: True if breaking news would materially shift the probability

For now, all markets receive default classification values and proceed to Phase 3.

### Phase 3: ESTIMATE — Claude Contrarian Probability Estimation

**The core IP.** Claude sees the market price and is asked to find reasons it's WRONG.

**System Prompt (Contrarian Mode):**
```
You are a contrarian prediction market analyst. You look for reasons markets are WRONG.

Your job: given a prediction market and its current price, determine if there's a
directional opportunity. You are advising a sophisticated trader who uses limit orders.

CRITICAL RULES:
1. You WILL be shown the current market price. Your job is to DISAGREE with it when you have reason to.
2. Don't just confirm the market. That's worthless. Look for what the market is MISSING or LAGGING on.
3. Consider: breaking news the market hasn't priced, political dynamics shifting, timing mismatches,
   crowd psychology errors, base rate neglect by the market.
4. Be opinionated. A 50% estimate on a 50% market is useless. Either find a reason it's wrong or
   say confidence is low.
5. Weight recent developments HEAVILY — markets are often slow to react to news in the last 24-48 hours.
6. Think about asymmetric upside: where is the cost of being wrong low but the payoff of being right high?

You must respond with ONLY a JSON object:
{
  "estimated_probability": <float 0.01-0.99>,
  "confidence": <float 0.0-1.0>,
  "reasoning": "<one sentence explaining WHY the market is wrong>",
  "key_factors": ["<factor 1>", "<factor 2>", "<factor 3>"],
  "conviction": "<strong|moderate|weak>"
}
```

**Context Enrichment:**
- Recent news from Polygon.io (if configured)
- Macro indicators: S&P 500, Bitcoin, VIX proxy, Gold
- X/Twitter sentiment signals (if available)
- Market liquidity and volume

**Fallback to Qwen:**
- If Claude is unavailable (cooldown, network error), falls back to local Qwen
- Qwen runs blind (no price shown) to prevent anchoring
- Falls back to full Qwen batch mode after 3 consecutive Claude failures

**Output:** Estimated probability, confidence, reasoning, key factors

### Phase 4: EDGE — Edge Calculation

For each estimate, calculates the edge (profit potential):

```
Raw Edge = |estimated_prob - market_price| * 100%
Direction = "underpriced" if estimate > market else "overpriced" else "fair"
Effective Edge = Raw Edge - 0.0% (limit orders assumption — no spread penalty)
```

**Why limit orders?** You're a sophisticated trader who can post limit orders at midpoint or better, avoiding spread costs.

**Filtering:**
- Minimum effective edge: 3% (default, configurable)
- Minimum confidence: 0.4 (filter out uncertain estimates)
- Drop estimates with direction = "fair" (no edge)

**Output:** Ranked list of edges, highest first

### Phase 5: CACHE & ALERT

**Cache Writing:**
- Writes research cache to `.kalshi_research_cache.json` (used by related commands)
- Detailed edge data to `state/kalshalyst_results.json` for analysis

**Alerting:**
- Filters opportunities by alert threshold (default: 6% effective edge)
- Sends top 3 opportunities to the user
- Format: ticker, direction (YES/NO), probability, edge, confidence, reasoning

**Brier Tracking:**
- Every estimate is logged to SQLite database
- Computes info_density (news + X signals + economic context + liquidity)
- Used for later calibration analysis

## Blocklist System

### Complete Blocklist Reference

**Ticker Prefixes (High-Volume Garbage):**
```
KXHIGH, KX