--- name: horizon-trader version: 0.4.7 description: Trade prediction markets (Polymarket, Kalshi) - positions, orders, risk management, Kelly sizing, wallet analytics, Monte Carlo, arbitrage, quantitative analytics (entropy, Hurst, VaR, Greeks, stress testing), 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. ```bash python3 {baseDir}/scripts/horizon.py [args...] ``` ## Available commands ### Portfolio & Status ```bash # 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 ```bash # 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 ```bash # Search for markets on an exchange python3 {baseDir}/scripts/horizon.py discover [query] [limit] # Examples: python3 {baseDir}/scripts/horizon.py discover polymarket "bitcoin" python3 {baseDir}/scripts/horizon.py discover kalshi "election" 5 ``` ### Kelly Sizing ```bash # 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 ```bash # 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 ```bash # 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 python3 {baseDir}/scripts/horizon.py start-feed mf manifold '{"slug":"will-btc-hit-100k"}' python3 {baseDir}/scripts/horizon.py start-feed nba espn '{"sport":"basketball","league":"nba"}' # 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 ```bash # List pending stop-loss/take-profit orders python3 {baseDir}/scripts/horizon.py contingent ``` ### Event Discovery ```bash # 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) ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ``` ## Maker/Taker Fees (v0.4.6) Split fees by liquidity role for more realistic paper trading and backtesting: ```python 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: ```python 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()`: ```python 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", ), }, ... ) ``` ## 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. ## 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