Horizon Quickstart

Install the Horizon SDK and run your first strategy in under 2 minutes. Works with prediction markets, equities, options, and crypto.

Installation

Requires Python 3.10+.

1. Install the package

   pip

   pip install horizon-sdk
   
2. Set your API key

   Get your key at api.mathematicalcompany.com, then:

   export HORIZON_API_KEY="hz_live_abc123..."
   

   Add this to your shell profile (~/.zshrc or ~/.bashrc) so it persists.

3. Verify installation

   python -c "import horizon; print(horizon.__version__)"
   

Your First Strategy

Create a file my_strategy.py:

import horizon as hz

def fair_value(ctx: hz.Context) -> float:
    """Simple fair value: just return 0.5 (coin flip)."""
    return 0.50

def quoter(ctx: hz.Context, fair: float) -> list[hz.Quote]:
    """Quote around the fair value with a fixed spread."""
    return hz.quotes(fair, spread=0.06, size=5)

hz.run(
    name="my_strategy",
    api_key="hz_sdk_abc123...",  # or set HORIZON_API_KEY env var
    markets=["test-market"],
    pipeline=[fair_value, quoter],
    risk=hz.Risk(max_position=100, max_drawdown_pct=5),
    interval=1.0,
    mode="paper",
)

Run it:

Direct

python my_strategy.py

You should see output like:

[horizon] Starting strategy 'my_strategy'
[horizon] Mode: paper
[horizon] Exchanges: ['paper']
[horizon] Markets: ['test-market']
[horizon] Feeds: []
[horizon] Pipeline: ['fair_value', 'quoter']
[horizon] Interval: 1.0s
[horizon] Database: ./my_strategy.db

[my_strategy] cycle=10 orders=2 positions=0 pnl=0.00
[my_strategy] cycle=20 orders=2 positions=1 pnl=0.03

Press Ctrl+C to stop. All open orders are canceled automatically on shutdown.

What Just Happened?

1. hz.run() created a paper exchange engine with risk limits
2. A SQLite database was opened at ./my_strategy.db for persistence
3. The main loop started, running your pipeline every 1 second:

• fair_value returned 0.50
• quoter received 0.50 and generated quotes at bid=0.47 / ask=0.53
• The engine canceled stale orders, submitted new quotes, and ticked the paper exchange

4. On Ctrl+C, positions were snapshotted and all orders canceled

Next Steps

Core Concepts

Understand hz.run(), pipelines, and the context object.

Exchanges

Connect to Polymarket, Kalshi, Alpaca, IBKR, Coinbase, Robinhood, or trade on paper.

Examples

See full strategy examples with live feeds.

Multi-Exchange

Trade on multiple exchanges simultaneously.