---
title: "Horizon Quickstart"
description: "Install the Horizon SDK and run your first strategy in under 2 minutes."
icon: "bolt"
---

## Installation

Requires **Python 3.10+**.

<Steps>
  <Step title="Install the package">
    <CodeGroup>
    ```bash pip
    pip install horizon-sdk
    ```
    ```bash uv
    uv pip install horizon-sdk
    ```
    </CodeGroup>
  </Step>
  <Step title="Set your API key">
    Get your key at [api.mathematicalcompany.com](https://api.mathematicalcompany.com), then:

    ```bash
    export HORIZON_API_KEY="hz_live_abc123..."
    ```

    Add this to your shell profile (`~/.zshrc` or `~/.bashrc`) so it persists.
  </Step>
  <Step title="Verify installation">
    ```bash
    python -c "import horizon; print(horizon.__version__)"
    ```
  </Step>
</Steps>

## Your First Strategy

Create a file `my_strategy.py`:

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

<CodeGroup>
```bash Direct
python my_strategy.py
```

```bash CLI with options
python -m horizon run my_strategy.py --dashboard --log-level=debug
```
</CodeGroup>

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

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book" href="/core-concepts/hz-run">
    Understand hz.run(), pipelines, and the context object.
  </Card>
  <Card title="Exchanges" icon="building-columns" href="/exchanges/overview">
    Connect to Polymarket, Kalshi, or trade on paper.
  </Card>
  <Card title="Examples" icon="code" href="/examples/simple-mm">
    See full strategy examples with live feeds.
  </Card>
  <Card title="Multi-Exchange" icon="arrows-split-up-and-left" href="/multi-exchange">
    Trade on multiple exchanges simultaneously.
  </Card>
</CardGroup>
