Skip to main content

​
Installation

Requires Python 3.10+.
1

Install the package

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",
    markets=["test-market"],
    pipeline=[fair_value, quoter],
    risk=hz.Risk(max_position=100, max_drawdown_pct=5),
    interval=1.0,
    mode="paper",
)
Run it: 
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
  1. 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.