OpenClaw Skill

Trade prediction markets from WhatsApp, Telegram, Discord, and Slack through the OpenClaw bot framework.

OpenClaw is a multi-platform Claude bot framework that runs on WhatsApp, Telegram, Discord, and Slack. The Horizon skill lets users trade prediction markets through natural conversation on any of these platforms.

How It Works

The OpenClaw skill provides a CLI script that Claude calls to interact with the Horizon engine:

User (WhatsApp/Telegram/Discord)
    │
    ▼
OpenClaw Bot (Claude)
    │ reads SKILL.md instructions
    ▼
scripts/horizon.py <command> [args]
    │
    ▼
horizon.tools → Engine (Rust)

Each command prints JSON to stdout. Claude interprets the JSON and responds in natural language.

Installation

Option A: Install from ClawHub (recommended)

The fastest way to add the Horizon trader skill to your OpenClaw bot:

1. Install the skill from ClawHub

   clawhub install horizon-trader
   

   Or with npx (no global install needed):

   npx clawhub@latest install horizon-trader
   
2. Install the Horizon SDK

   pip install horizon-sdk
   # or
   uv pip install horizon-sdk
   
3. Set environment variables

   In your OpenClaw .env or environment:

   HORIZON_API_KEY=your-key
   HORIZON_EXCHANGE=paper
   
4. Restart OpenClaw

   The bot will discover the horizon-trader skill from SKILL.md on startup.

Option B: Manual install from source

1. Install Horizon

   pip install horizon-sdk
   # or
   uv pip install horizon-sdk
   
2. Copy the skill to your OpenClaw skills directory

   cp -r skills/horizon-trader/ /path/to/openclaw/skills/horizon-trader/
   

   Or if you’ve installed Horizon as a package, the skill is at:

   cp -r $(python -c "import horizon; print(horizon.__path__[0])")/../skills/horizon-trader /path/to/openclaw/skills/
   
3. Set environment variables

   In your OpenClaw .env or environment:

   HORIZON_API_KEY=your-key
   HORIZON_EXCHANGE=paper
   
4. Restart OpenClaw

   The bot will discover the horizon-trader skill from SKILL.md on startup.

Commands

The skill exposes these commands via the CLI script:

Portfolio

# Engine status
python3 scripts/horizon.py status

# List positions
python3 scripts/horizon.py positions

# List open orders
python3 scripts/horizon.py orders

# List orders for a specific market
python3 scripts/horizon.py orders will-btc-hit-100k

# Recent fills
python3 scripts/horizon.py fills

Trading

# Submit a limit buy
python3 scripts/horizon.py quote will-btc-hit-100k buy 0.55 10

# Submit a limit sell
python3 scripts/horizon.py quote will-btc-hit-100k sell 0.60 5

# Cancel an order
python3 scripts/horizon.py cancel p1

# Cancel all orders
python3 scripts/horizon.py cancel-all

# Cancel all orders for a specific market
python3 scripts/horizon.py cancel-market will-btc-hit-100k

Discovery

# Search Polymarket
python3 scripts/horizon.py discover polymarket "bitcoin"

# Search Kalshi
python3 scripts/horizon.py discover kalshi "KXBTC" 5

Kelly Sizing

# kelly <prob> <price> <bankroll> [fraction] [max_size]
python3 scripts/horizon.py kelly 0.65 0.50 1000
python3 scripts/horizon.py kelly 0.70 0.55 2000 0.5 50

Risk Management

# Emergency stop
python3 scripts/horizon.py kill-switch on "market crash"

# Resume trading
python3 scripts/horizon.py kill-switch off

# Add stop-loss: stop-loss <market_id> <side> <order_side> <size> <trigger_price>
python3 scripts/horizon.py stop-loss will-btc-hit-100k yes sell 10 0.40

# Add take-profit: take-profit <market_id> <side> <order_side> <size> <trigger_price>
python3 scripts/horizon.py take-profit will-btc-hit-100k yes sell 10 0.80

Feed Data & Health

# Get a feed snapshot
python3 scripts/horizon.py feed btc

# List all feeds
python3 scripts/horizon.py feeds

# Check feed staleness and health (optional threshold in seconds)
python3 scripts/horizon.py feed-health
python3 scripts/horizon.py feed-health 60

Contingent Orders

# List pending SL/TP
python3 scripts/horizon.py contingent

# Check parity
python3 scripts/horizon.py parity will-btc-hit-100k

# Feed connection metrics (single feed or all)
python3 scripts/horizon.py feed-metrics btc
python3 scripts/horizon.py feed-metrics

Event Discovery

# Discover multi-outcome events on Polymarket
python3 scripts/horizon.py discover-events "election"

# Top markets by volume
python3 scripts/horizon.py top-markets polymarket 10
python3 scripts/horizon.py top-markets kalshi 5 "KXBTC"

Wallet Analytics (Polymarket - no auth required)

# Trade history for a wallet
python3 scripts/horizon.py wallet-trades 0x1234...

# Open positions with PnL
python3 scripts/horizon.py wallet-positions 0x1234... 50 CURRENT

# Portfolio value
python3 scripts/horizon.py wallet-value 0x1234...

# Public profile
python3 scripts/horizon.py wallet-profile 0x1234...

# Top holders in a market
python3 scripts/horizon.py top-holders 0xabc...

# Trade flow analysis
python3 scripts/horizon.py market-flow 0xabc... 500

Hedging & Cross-Market

# Compute hedge ratio, effectiveness, basis risk
python3 scripts/horizon.py hedge-analysis '[100,102,101,103]' '[50,51,50.5,51.5]' 60

# Scenario analysis on a hedged position
python3 scripts/horizon.py hedge-scenario 100 50.0 -50 25.0 '[-0.20,-0.10,0.0,0.10,0.20]'

# Multi-ticker hedge: optimal weights
python3 scripts/horizon.py hedge-multi '[0.01,-0.02,0.03]' '[[0.005,-0.01,0.015],[0.008,-0.015,0.02]]' '["SPY","QQQ"]'

# Hedge cost summary
python3 scripts/horizon.py hedge-costs

Account & Credentials

# Always pass password via env var (avoids shell history exposure)
# Create account and generate SDK key (encrypted, saved to ~/.horizon/credentials.json)
HORIZON_PASSWORD="mypassword" python3 scripts/horizon.py setup [e-mail] "My Name"

# Login and generate new SDK key
HORIZON_PASSWORD="mypassword" python3 scripts/horizon.py login [e-mail]

# Check credential status
python3 scripts/horizon.py key-status

Simulation & Arbitrage

# Monte Carlo on current positions
python3 scripts/horizon.py simulate 50000

# Cross-exchange arb
python3 scripts/horizon.py arb will-btc-hit-100k kalshi polymarket 0.48 0.52 10

Conversation Examples

Telegram

User: What's my PnL today?

Bot: 📊 Your engine status:
     Daily PnL: +$9.25
     Realized: +$12.45 | Unrealized: -$3.20
     3 open orders, 2 positions

User: Find me some bitcoin markets

Bot: Found 5 markets on Polymarket:
     1. Will BTC hit $100k by end of 2025?
     2. Will BTC hit $150k by end of 2025?
     ...

User: Buy 20 contracts of will-btc-hit-100k at 0.52

Bot: ✅ Order submitted:
     Order ID: p1
     Buy 20 contracts @ 0.52
     Market: will-btc-hit-100k

WhatsApp

User: kill switch NOW

Bot: 🚨 Kill switch activated.
     All orders canceled.
     Reason: user emergency request

     Send "resume trading" to deactivate.

SKILL.md Reference

The SKILL.md file tells Claude when and how to use the skill:

---
name: horizon-trader
description: Trade prediction markets (Polymarket, Kalshi)
emoji: "\U0001F4C8"
metadata:
  requires_env:
   - HORIZON_API_KEY
  install: pip install horizon-sdk
---

The body contains natural language instructions for:

• When to activate (user asks about trading, positions, markets)
• Command syntax with examples
• Output format (JSON)
• Safety notes (confirm before submitting orders)

Output Format

All commands return JSON. On success:

{
  "running": true,
  "kill_switch_active": false,
  "open_orders": 3,
  "daily_pnl": 9.25
}

On error:

{
  "error": "risk rejection: max position exceeded"
}

The bot interprets the JSON and responds in natural language, never showing raw JSON to the user.

Pipeline Features (v0.4.0)

The Horizon SDK includes advanced pipeline components for automated strategies:

• Regime Detection (regime_signal) - volatility/trend regime classification
• Feed Guard (feed_guard) - auto-activates kill switch when feeds go stale
• Inventory Skew (inventory_skewer) - shifts quotes to reduce position risk
• Adaptive Spread (adaptive_spread) - dynamically adjusts spread based on market conditions
• Execution Tracker (execution_tracker) - monitors fill quality and adverse selection
• Multi-Strategy - run different pipelines per market via dict config
• Cross-Market Hedging (cross_hedger) - generates hedge quotes when portfolio delta exceeds threshold

These are used with hz.run() in Python strategies. See the full documentation for details.

Deployment

Deploy the OpenClaw skill with the Horizon trader to your preferred platform. Full deployment guide: https://docs.openclaw.ai/tools/clawhub