---
title: "OpenClaw Skill"
description: "Trade prediction markets from WhatsApp, Telegram, Discord, and Slack through the OpenClaw bot framework."
icon: "/images/integrations/openclaw.svg"
---

[OpenClaw](https://github.com/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:

<Steps>
  <Step title="Install the skill from ClawHub">
    ```bash
    clawhub install horizon-trader
    ```

    Or with npx (no global install needed):
    ```bash
    npx clawhub@latest install horizon-trader
    ```
  </Step>
  <Step title="Install the Horizon SDK">
    ```bash
    pip install horizon-sdk
    # or
    uv pip install horizon-sdk
    ```
  </Step>
  <Step title="Set environment variables">
    In your OpenClaw `.env` or environment:
    ```bash
    HORIZON_API_KEY=your-key
    HORIZON_EXCHANGE=paper
    ```
  </Step>
  <Step title="Restart OpenClaw">
    The bot will discover the `horizon-trader` skill from `SKILL.md` on startup.
  </Step>
</Steps>

### Option B: Manual install from source

<Steps>
  <Step title="Install Horizon">
    ```bash
    pip install horizon-sdk
    # or
    uv pip install horizon-sdk
    ```
  </Step>
  <Step title="Copy the skill to your OpenClaw skills directory">
    ```bash
    cp -r skills/horizon-trader/ /path/to/openclaw/skills/horizon-trader/
    ```

    Or if you've installed Horizon as a package, the skill is at:
    ```bash
    cp -r $(python -c "import horizon; print(horizon.__path__[0])")/../skills/horizon-trader /path/to/openclaw/skills/
    ```
  </Step>
  <Step title="Set environment variables">
    In your OpenClaw `.env` or environment:
    ```bash
    HORIZON_API_KEY=your-key
    HORIZON_EXCHANGE=paper
    ```
  </Step>
  <Step title="Restart OpenClaw">
    The bot will discover the `horizon-trader` skill from `SKILL.md` on startup.
  </Step>
</Steps>

## Commands

The skill exposes these commands via the CLI script:

### Portfolio

```bash
# 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

```bash
# 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

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

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

### Kelly Sizing

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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 user@example.com "My Name"

# Login and generate new SDK key
HORIZON_PASSWORD="mypassword" python3 scripts/horizon.py login user@example.com

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

### Simulation & Arbitrage

```bash
# 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:

```yaml
---
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:

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

On error:

```json
{
  "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](https://docs.openclaw.ai/tools/clawhub) for details.

## Deployment

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