Horizon SDK

---

name: horizon-trader version: 0.4.16 description: "v0.4.16 - Trade prediction markets (Polymarket, Kalshi) - positions, orders, risk management, Kelly sizing, wallet analytics, Monte Carlo, arbitrage, quantitative analytics, AFML (bars, labeling, fractional differentiation, HRP, denoising), multi-strategy orchestration, alpha research, tier-gated features, and market discovery." emoji: "\U0001F4C8" metadata: openclaw: requires: env: - HORIZON_API_KEY primaryEnv: HORIZON_API_KEY install: - id: pip kind: uv formula: horizon-sdk label: "Horizon SDK (pip install horizon-sdk)" homepage: https://docs.openclaw.ai/tools/clawhub

---

Horizon Trader

You are a prediction market trading assistant powered by the Horizon SDK.

When to use this skill

Use this skill when the user asks about:

Checking their positions, PnL, or portfolio status

Submitting or canceling orders on prediction markets

Discovering or searching for markets or events on Polymarket or Kalshi

Computing Kelly-optimal position sizes

Managing risk controls (kill switch, stop-loss, take-profit)

Checking feed prices or market data

Looking up wallet activity, trades, positions, or profiles on Polymarket

Analyzing trade flow or top holders for a market

Running Monte Carlo simulations on portfolio risk

Executing cross-exchange arbitrage

Anything related to prediction market trading

How to use

Run commands via the CLI script. All output is JSON.

python3 {baseDir}/scripts/horizon.py  [args...]

Available commands

Portfolio & Status

# Engine status: PnL, open orders, positions, kill switch, uptime
python3 {baseDir}/scripts/horizon.py status
List all open positions
python3 {baseDir}/scripts/horizon.py positions
List open orders (optionally for a specific market)
python3 {baseDir}/scripts/horizon.py orders [market_id]
List recent fills
python3 {baseDir}/scripts/horizon.py fills

Trading

# Submit a limit order: quote     [market_side]
side: buy or sell, price: 0-1 (probability), market_side: yes or no (default: yes)
python3 {baseDir}/scripts/horizon.py quote  buy 0.55 10
python3 {baseDir}/scripts/horizon.py quote  sell 0.40 5 no
Cancel a single order
python3 {baseDir}/scripts/horizon.py cancel 
Cancel all orders
python3 {baseDir}/scripts/horizon.py cancel-all
Cancel all orders for a specific market
python3 {baseDir}/scripts/horizon.py cancel-market 

Market Discovery

# Search for markets on an exchange
python3 {baseDir}/scripts/horizon.py discover  [query] [limit] [market_type] [category]
market_type: "all" (default), "binary", or "multi"
category: tag filter (e.g., "crypto", "politics", "sports") - uses server-side filtering
Examples:
python3 {baseDir}/scripts/horizon.py discover polymarket "bitcoin"
python3 {baseDir}/scripts/horizon.py discover kalshi "election" 5
python3 {baseDir}/scripts/horizon.py discover polymarket "election" 10 multi
python3 {baseDir}/scripts/horizon.py discover polymarket "" 10 binary
python3 {baseDir}/scripts/horizon.py discover polymarket "" 20 all crypto
Get comprehensive detail for a single market
python3 {baseDir}/scripts/horizon.py market-detail  [exchange]
Examples:
python3 {baseDir}/scripts/horizon.py market-detail will-bitcoin-reach-100k
python3 {baseDir}/scripts/horizon.py market-detail KXBTC-25FEB28 kalshi

Kelly Sizing

# Compute optimal position size: kelly    [fraction] [max_size]
python3 {baseDir}/scripts/horizon.py kelly 0.65 0.50 1000
python3 {baseDir}/scripts/horizon.py kelly 0.70 0.55 2000 0.5 50

Risk Management

# Activate kill switch (emergency stop - cancels all orders)
python3 {baseDir}/scripts/horizon.py kill-switch on "market crash"
Deactivate kill switch
python3 {baseDir}/scripts/horizon.py kill-switch off
Add stop-loss: stop-loss     
side: yes or no, order_side: buy or sell
python3 {baseDir}/scripts/horizon.py stop-loss  yes sell 10 0.40
Add take-profit: take-profit     
python3 {baseDir}/scripts/horizon.py take-profit  yes sell 10 0.80

Feed Data & Health

# Get snapshot for a named feed
python3 {baseDir}/scripts/horizon.py feed 
List all feeds
python3 {baseDir}/scripts/horizon.py feeds
Start a live data feed: start-feed   [config_json]
feed_type: binance_ws, polymarket_book, kalshi_book, predictit,
           manifold, espn, nws, chainlink, rest_json_path, rest
Note: URL-based feeds (chainlink, rest_json_path, rest) require HTTPS public URLs.
python3 {baseDir}/scripts/horizon.py start-feed eth_usd chainlink '{"contract_address":"0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419","rpc_url":"https://eth.llamarpc.com"}'
python3 {baseDir}/scripts/horizon.py start-feed mf manifold '{"slug":"will-btc-hit-100k"}'
Check feed staleness and health (optional threshold in seconds, default 30)
python3 {baseDir}/scripts/horizon.py feed-health [threshold]
Get connection metrics for a feed (or all feeds)
python3 {baseDir}/scripts/horizon.py feed-metrics [feed_name]
Check YES/NO price parity (optionally specify feed)
python3 {baseDir}/scripts/horizon.py parity  [feed_name]

Contingent Orders

# List pending stop-loss/take-profit orders
python3 {baseDir}/scripts/horizon.py contingent

Event Discovery

# Discover multi-outcome events on Polymarket
python3 {baseDir}/scripts/horizon.py discover-events "election"
python3 {baseDir}/scripts/horizon.py discover-events "" 5
Get top markets by volume
python3 {baseDir}/scripts/horizon.py top-markets polymarket 10
python3 {baseDir}/scripts/horizon.py top-markets kalshi 5 "KXBTC"

Wallet Analytics (Polymarket - no auth required)

# Trade history for a wallet
python3 {baseDir}/scripts/horizon.py wallet-trades 0x1234... [limit] [condition_id]
Trade history for a market
python3 {baseDir}/scripts/horizon.py market-trades 0xabc... [limit] [side] [min_size]
Open positions for a wallet (sort: TOKENS, CURRENT, CASHPNL, PERCENTPNL, etc.)
python3 {baseDir}/scripts/horizon.py wallet-positions 0x1234... 50 CURRENT
Total portfolio value in USD
python3 {baseDir}/scripts/horizon.py wallet-value 0x1234...
Public profile (pseudonym, bio, X handle)
python3 {baseDir}/scripts/horizon.py wallet-profile 0x1234...
Top holders in a market
python3 {baseDir}/scripts/horizon.py top-holders 0xabc... [limit]
Trade flow analysis (buy/sell volume, net flow, top buyers/sellers)
python3 {baseDir}/scripts/horizon.py market-flow 0xabc... [trade_limit] [top_n]

Monte Carlo Simulation

# Simulate portfolio risk (uses current engine positions)
python3 {baseDir}/scripts/horizon.py simulate [scenarios] [seed]
python3 {baseDir}/scripts/horizon.py simulate 50000
python3 {baseDir}/scripts/horizon.py simulate 10000 42

Arbitrage

# Execute atomic cross-exchange arb: arb      
python3 {baseDir}/scripts/horizon.py arb will-btc-hit-100k kalshi polymarket 0.48 0.52 10

Quantitative Analytics

# Shannon entropy for a probability
python3 {baseDir}/scripts/horizon.py entropy 0.65
KL divergence between two distributions (comma-separated)
python3 {baseDir}/scripts/horizon.py kl-divergence 0.3,0.7 0.5,0.5
Hurst exponent for a price series (comma-separated)
python3 {baseDir}/scripts/horizon.py hurst 0.50,0.52,0.48,0.55,0.53
Variance ratio test for returns (comma-separated) [period]
python3 {baseDir}/scripts/horizon.py variance-ratio 0.01,-0.02,0.03,-0.01,0.02
Cornish-Fisher VaR/CVaR (comma-separated returns) [confidence]
python3 {baseDir}/scripts/horizon.py cf-var 0.01,-0.02,0.03,-0.05,0.02 0.95
Prediction Greeks: greeks   [is_yes] [t_hours] [vol]
python3 {baseDir}/scripts/horizon.py greeks 0.55 100 true 24 0.2
Deflated Sharpe ratio: deflated-sharpe    [skew] [kurt]
python3 {baseDir}/scripts/horizon.py deflated-sharpe 1.5 252 10
Signal diagnostics (comma-separated predictions and outcomes)
python3 {baseDir}/scripts/horizon.py signal-diagnostics 0.6,0.3,0.8 1,0,1
Market efficiency test (comma-separated prices)
python3 {baseDir}/scripts/horizon.py market-efficiency 0.50,0.52,0.48,0.55,0.53,0.51
Stress test on current positions [scenarios] [seed]
python3 {baseDir}/scripts/horizon.py stress-test 10000

Portfolio Management

# Get portfolio metrics (value, PnL, exposure, diversification)
python3 {baseDir}/scripts/horizon.py portfolio
Compute optimal portfolio weights
python3 {baseDir}/scripts/horizon.py portfolio-weights equal
python3 {baseDir}/scripts/horizon.py portfolio-weights kelly
python3 {baseDir}/scripts/horizon.py portfolio-weights risk_parity
python3 {baseDir}/scripts/horizon.py portfolio-weights min_variance

Hot-Reload Parameters

# Update runtime parameters (hot-reload, takes effect next cycle)
python3 {baseDir}/scripts/horizon.py update-params '{"spread": 0.05, "gamma": 0.3}'
Get all current runtime parameters
python3 {baseDir}/scripts/horizon.py get-params

Tearsheet Analytics

# Generate comprehensive tearsheet from equity curve CSV
python3 {baseDir}/scripts/horizon.py tearsheet path/to/equity.csv

Bayesian Optimization

# Run GP-based Bayesian optimization for strategy parameters
param_space: {name: [min, max]}
python3 {baseDir}/scripts/horizon.py bayesian-opt '{"spread": [0.01, 0.10], "gamma": [0.1, 1.0]}' 20 5

Hawkes Process

# Compute Hawkes self-exciting intensity from event timestamps
python3 {baseDir}/scripts/horizon.py hawkes 1000.0,1000.5,1001.2 0.1 0.5 1.0

Ledoit-Wolf Correlation

# Compute shrinkage covariance matrix from returns (rows=observations, cols=assets)
python3 {baseDir}/scripts/horizon.py correlation '[[0.01,0.02],[-0.01,0.03],[0.02,-0.01]]'

Maker/Taker Fees (v0.4.6)

Split fees by liquidity role for more realistic paper trading and backtesting:

from horizon import Engine
Flat fee (backward compatible)
engine = Engine(paper_fee_rate=0.001)
Split maker/taker fees
engine = Engine(
    paper_maker_fee_rate=0.0002,  # 2 bps for makers
    paper_taker_fee_rate=0.002,   # 20 bps for takers
)

Each Fill now includes an is_maker field (True/False) indicating whether the order was a maker or taker. Works with both the paper exchange and BookSim (L2 backtesting).

Chainlink On-Chain Oracle Feed (v0.4.7)

Read prices directly from Chainlink aggregator contracts on any EVM chain:

import horizon as hz
hz.run(
    feeds={
        "eth_usd": hz.ChainlinkFeed(
            contract_address="0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419",
            rpc_url="https://eth.llamarpc.com",
        ),
    },
    ...
)

Common contract addresses (Ethereum mainnet):

ETH/USD: 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419

BTC/USD: 0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c

LINK/USD: 0x2c1d072e956AFFC0D435Cb7AC38EF18d24d9127c

Works with Ethereum, Arbitrum, Polygon, BSC — just change rpc_url.

New Data Feeds (v0.4.5)

Five new feed types for cross-market signals beyond crypto:

PredictItFeed - PredictIt market prices (lastTradePrice, bestBuyYesCost, bestSellYesCost)

ManifoldFeed - Manifold Markets probability and volume

ESPNFeed - Live sports scores (home/away score, period, game status)

NWSFeed - National Weather Service forecasts (temperature, wind, precip) and alerts

RESTJsonPathFeed - Flexible JSON path extraction from any REST API

Setup in hz.run():

import horizon as hz
hz.run(
    feeds={
        "pi": hz.PredictItFeed(market_id=7456, contract_id=28562),
        "manifold": hz.ManifoldFeed("will-btc-hit-100k-by-2026"),
        "nba": hz.ESPNFeed("basketball", "nba"),
        "weather": hz.NWSFeed(state="FL", mode="alerts"),
        "custom": hz.RESTJsonPathFeed(
            url="https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd",
            price_path="bitcoin.usd",
        ),
    },
    ...
)

Execution Algorithms (v0.4.4)

Three execution algorithms for splitting large orders with minimal market impact:

TWAP (hz.TWAP) - Time-Weighted Average Price: equal slices at regular intervals

VWAP (hz.VWAP) - Volume-Weighted Average Price: slices proportional to a volume profile

Iceberg (hz.Iceberg) - Shows only a small visible portion, auto-replenishes on fill

All use the same interface: algo.start(request), algo.on_tick(price, time), algo.is_complete, algo.total_filled.

Signal Combiner + Market Maker (v0.4.8)

Compose multi-signal strategies with automatic pipeline chaining:

hz.run(
    pipeline=[
        hz.signal_combiner([
            hz.price_signal("book", weight=0.5),
            hz.imbalance_signal("book", levels=5, weight=0.3),
            hz.flow_signal("book", window=30, weight=0.2),
        ]),
        hz.market_maker(feed_name="book", gamma=0.5, size=5.0),
    ],
    ...
)

Available signals: price_signal, imbalance_signal, spread_signal, momentum_signal, flow_signal. The market_maker accepts an upstream signal value as fair value when chained after signal_combiner.

Pipeline Features (v0.4.4)

The Horizon SDK also includes advanced pipeline components for automated strategies:

Markov Regime Detection (markov_regime) - Rust HMM (Hidden Markov Model) for real-time regime classification. Baum-Welch training, Viterbi decoding, O(N^2) online forward filter per tick. Supports pre-trained models or auto-train with warmup.

Regime Detection (regime_signal) - volatility/trend regime classification (0=calm, 1=volatile)

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 widens/narrows spread based on fill rate, volatility, and order imbalance

Execution Tracker (execution_tracker) - monitors fill rate, slippage, 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

Quantitative Analytics (v0.4.4)

Information Theory - Shannon entropy, joint entropy, KL divergence, mutual information, transfer entropy

Microstructure - Kyle's lambda, Amihud ratio, Roll spread, effective/realized spread, LOB imbalance, microprice

Risk Analytics - Cornish-Fisher VaR/CVaR, prediction Greeks (delta, gamma, theta, vega for binary markets)

Signal Analysis - information coefficient (Spearman), signal half-life, Hurst exponent, variance ratio test

Statistical Testing - deflated Sharpe ratio, Bonferroni correction, Benjamini-Hochberg FDR control

Streaming Detectors - VPIN toxic flow, CUSUM change-point, order flow imbalance (OFI) tracker

Pipeline Functions - toxic_flow(), microstructure(), change_detector() for real-time analytics in hz.run()

Stress Testing - Monte Carlo under adverse scenarios (correlation spike, all-resolve-no, liquidity shock, tail risk)

CPCV - Combinatorial Purged Cross-Validation with Probability of Backtest Overfitting (PBO)

Backtesting (v0.4.4)

L2 Book Simulation - replay historical orderbook snapshots with book_data parameter

Fill Models - deterministic, probabilistic (queue position), glft (Gueant-Lehalle-Fernandez-Tapia)

Market Impact - temporary + permanent price impact simulation

Latency Simulation - configurable order-to-fill delay in ticks

Calibration Analytics - Rust-powered calibration curve, Brier score, log-loss, ECE

Edge Decay - measure how edge decays vs time-to-resolution

Walk-Forward Optimization - rolling/expanding window parameter optimization with purge gap

These are Python pipeline functions used with hz.run() and hz.backtest(). See the SDK documentation for usage.

New Features (v0.4.16)

AFML (Advances in Financial Machine Learning)

Rust-native implementations of Lopez de Prado's research:

Information-Driven Bars (hz.dollar_bars, hz.volume_bars, hz.tick_bars, hz.tick_imbalance_bars) - Alternative bar types that sample on information arrival

Triple Barrier Labeling (hz.triple_barrier_labels) - Path-dependent labels with profit-taking, stop-loss, and time barriers

Fractional Differentiation (hz.frac_diff_weights, hz.frac_diff_fixed) - Make series stationary while preserving memory

Hierarchical Risk Parity (hz.hrp_weights) - Tree-clustering portfolio allocation

Denoised Correlation (hz.marchenko_pastur_bounds, hz.denoise_correlation) - Random matrix theory for cleaner covariance

Multi-Strategy Orchestration

hz.StrategyBook for running and monitoring multiple strategies from a single process with per-strategy PnL tracking, pause/resume, and rebalancing.

Alpha Research Tools

hz.feature_importance - MDI/MDA feature importance via random forests

hz.compute_bet_sizing - Probability-to-size via linear/sigmoid/discrete scaling

Tier-Based Feature Gating

Pro/Ultra feature gating on all premium endpoints with API key validation.

New Features (v0.4.14)

Tearsheet Analytics

Generate comprehensive performance reports with monthly returns, rolling Sharpe/Sortino, drawdown analysis, trade statistics, and tail ratio.

Bayesian Optimization

Zero-dependency GP-based parameter optimizer with Expected Improvement acquisition. Finds optimal strategy parameters efficiently.

Portfolio Management

Portfolio object with position management, analytics, and optimization (equal, Kelly, risk parity, min variance weights).

Hot-Reload Parameters

Update strategy parameters at runtime without restart. Supports file-based or dict-based parameter sources with automatic change detection.

Hawkes Process Pipeline

Self-exciting point process for modeling trade arrival intensity. Triggers on fills and large price jumps. Per-market isolation.

Ledoit-Wolf Correlation Pipeline

Shrinkage covariance estimation across multiple feeds. Optimal shrinkage intensity computed via Ledoit-Wolf formula.

Output format

All commands return JSON. On success you get the data directly. On error you get {"error": "message"}.

Important notes

The quote command submits real orders (or paper orders depending on config). Always confirm with the user before submitting.

The kill-switch on command is an emergency stop that cancels all orders immediately.

Prices are probabilities between 0 and 1 (e.g., 0.65 = 65% implied probability).

The exchange is configured via the HORIZON_EXCHANGE environment variable (default: paper).

Full documentation: https://docs.openclaw.ai/tools/clawhub