Prediction Stack Setup

Interactive setup wizard for the OpenClaw Prediction Market Trading Stack. Detects installed skills, walks through API key configuration, creates cron jobs for automated scanning and alerts, enables heartbeat for ambient awareness, and tests iMessage delivery. Wires the 10-skill stack into a connected, proactive trading system in under 5 minutes. Run this after installing the stack — or anytime you need to reconfigure schedules, delivery targets, or alert thresholds.

# Prediction Stack Setup — One-Command System Activation

## Overview

<!-- CODEX: reconciled setup docs with the 10-skill stack and the public Anthropic-backed reference path. -->
This skill wires the 10-skill OpenClaw Prediction Market Trading Stack into a connected, proactive system. Without setup, skills work individually when you ask for them. After setup, the runtime skills run autonomously — scanning markets, detecting edges, monitoring positions, and delivering intelligence to your phone on a schedule.

**What it does:**
1. Detects which stack skills are installed
2. Configures API keys and credentials
3. **Validates all APIs before creating jobs** (prevents silent failures)
4. Creates scheduled jobs (cron) for each skill
5. Enables heartbeat for ambient awareness
6. Sets up iMessage delivery
7. Tests the full pipeline end-to-end

**Time to complete:** Under 5 minutes

## When to Use This Skill

- You just installed the Prediction Market Trading Stack (all 8 skills or any subset)
- You just installed the Prediction Market Trading Stack (all 10 skills or any subset)
- You want to activate automated scanning and alerts
- You need to change your delivery target (new phone, new email handle)
- You want to adjust scan schedules or alert thresholds
- You're migrating from a previous setup or starting fresh
- Something broke and you want to rewire from scratch

## Prerequisites

### Required
- **OpenClaw** installed and running (gateway active)
- **At least one stack skill** installed (any of the 10)
- **Kalshi account** with API credentials (free at kalshi.com)
- **Anthropic API key** (for Claude Sonnet estimation in Kalshalyst)

### Optional (Enhances the Stack)
- **Polygon.io API key** (free tier — adds news context to Kalshalyst)
- **Ollama + Qwen** installed locally (free — adds offline fallback + Xpulse materiality gate)
- **BlueBubbles** running on your Mac (required for iMessage delivery)

## Setup Procedure

### Phase 1: Skill Detection

First, check which stack skills are installed. Run this command:

```bash
openclaw skills list | grep -E "kalshalyst|kalshi-command|polymarket-command|prediction-market-arbiter|xpulse|portfolio-drift|market-morning-brief|personality-engine"
```

**The 10 stack skills:**

| Skill | Role | Required For |
|-------|------|-------------|
| Kalshalyst | Edge detection engine | Edge alerts, Morning Brief edges section |
| Kalshi Command Center | Trade execution | Executing on Kalshalyst recommendations |
| Polymarket Command Center | Market data | Arbiter comparisons, Morning Brief Polymarket section |
| Prediction Market Arbiter | Cross-platform divergences | Arbitrage alerts, Morning Brief divergences section |
| Xpulse | Social signal scanner | Signal alerts, Morning Brief X signals section |
| Portfolio Drift Monitor | Position monitoring | Drift alerts between briefs |
| Market Morning Brief | Daily digest | Consolidated morning/evening intelligence |
| Personality Engine | Agent behavior | Consistent voice across all output |
| Prediction Stack Orchestrator | Premium/experimental pipeline manager | Validation and execution routing |
| Prediction Stack Setup | Setup wizard | Validation, scheduling, delivery wiring |

**Minimum viable stack:** Kalshalyst + Kalshi Command Center + Market Morning Brief. These three give you edge detection, execution, and daily digest. Everything else enriches the system.

**Full stack:** All 10 skills. Morning Brief pulls from every cache and the orchestrator adds a premium/experimental automation path on top.

Install missing skills:
```bash
clawhub install <skill-name>
```

### Phase 2: API Key Configuration

Create or update `~/.openclaw/config.yaml`:

```yaml
# === REQUIRED ===

kalshi:
  enabled: true
  api_key_id: "YOUR_KALSHI_KEY_ID"
  private_key_file: "~/.openclaw/keys/kalshi-secret.pem"

# === REQUIRED FOR KALSHALYST ===
# Set as environment variable or in config:
# export ANTHROPIC_API_KEY="sk-ant-..."

# === OPTIONAL — ENHANCES EDGE QUALITY ===

polygon:
  api_key: "YOUR_POLYGON_KEY"   # Free tier at polygon.io

ollama:
  enabled: true                  # For Xpulse materiality gate + Kalshalyst fallback
  model: "qwen3:latest"
  timeout_seconds: 60

# === SKILL-SPECIFIC TUNING (sensible defaults shown) ===

kalshalyst:
  enabled: true
  check_interval_minutes: 60
  min_volume: 50
  min_days_to_close: 7
  max_days_to_close: 365
  max_markets_to_analyze: 50
  min_edge_pct: 3.0
  alert_edge_pct: 6.0

xpulse:
  enabled: true
  check_interval_minutes: 30
  topics:
    - "Trump tariff"
    - "Ukraine"
    - "inflation CPI"
    - "Fed rate decision"
  min_confidence: 0.7
  materiality_gate: true
  position_gate: true

portfolio_drift:
  threshold_pct: 5.0
  check_interval_minutes: 60
```

**Kalshi key setup** (if you don't have one yet):
1. Log in at https://kalshi.com
2. Go to Settings → API Keys
3. Generate a new key pair
4. Save the private key:
```bash
mkdir -p ~/.openclaw/keys
# Paste your private key into this file:
nano ~/.openclaw/keys/kalshi-secret.pem
chmod 600 ~/.openclaw/keys/kalshi-secret.pem
```

### Phase 2.5: Validate API Keys

**Before creating cron jobs, verify that all configured APIs are working.** This prevents hours of silent failures where the stack runs but can't reach its data sources.

Run the validation script:

```bash
python ~/skills/prediction-stack-setup/scripts/validate_setup.py
```

**Output Example:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Prediction Stack API Validation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

REQUIRED SERVICES (must pass for stack to function)
──────────────────────────────────────────────────────────────────────
✅ PASS Kalshi API             (REQUIRED)       (245ms)
✅ PASS Anthropic (Claude)     (REQUIRED)       (1320ms)

OPTIONAL SERVICES (enhance edge detection and resilience)
──────────────────────────────────────────────────────────────────────
✅ PASS Polygon.io API         (optional)       (180ms)
❌ FAIL Ollama (Qwen)          (optional)       (15ms)
   Error: Ollama not running on localhost:11434
✅ PASS Polymarket API         (optional)       (95ms)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Required: 2/2 passed
Optional: 2/3 passed

✅ All required services validated. Stack is ready to launch.
```

**What each validation tests:**

| Service | Required | Test | Failure Handling |
|---------|----------|------|------------------|
| **Kalshi** | Yes | `get_balance()` call | Blocks setup if auth fails |
| **Claude** | Yes | Simple completion call | Blocks setup if key invalid |
| **Polygon.io** | No | Public market status endpoint | Kalshalyst works without it |
| **Ollama/Qwen** | No | Model availability + inference | Kalshalyst uses Claude fallback |
| **Polymarket** | No | Public API endpoint access | Arbiter works without it |

**If validation fails on REQUIRED services:**

1. **Kalshi fails** — Check error message:
   - "Authentication failed": Verify key ID and private key file are correct at https://kalshi.com/settings/api
   - "Network error": Verify internet connectivity, check Kalshi status at status.kalshi.com
   - "File not found": Verify `private_key_file` path in config.yaml exists and is readable

2. **Claude fails** — Check error message:
   - "Invalid or expired API key": Generate a new key at https://console.anthropic.com/account/keys
   - "Network error": Verify internet connectivity
   - "Rate limited": Wait 60 seconds and retry

3. **Optional services fail** — This is OK. The stack will work but with reduced functionality:
   - Polygon.io missing: Kalshalyst estimates will lack news context
   - Ollama missing: Kalshalyst will use Claude for all estimates (higher cost)
   - Polymarket missing: Arbiter won't find cross-platform divergences

**To validate only specific services:**

```bash
# Test only Kalshi (useful for debugging)
python ~/skills/prediction-stack-setup/scripts/validate_setup.py --kalshi-only

#