> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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+**.

<Steps>
  <Step title="Install the package">
    <CodeGroup>
      ```bash pip theme={null}
      pip install horizon-sdk
      ```

      ```bash uv theme={null}
      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 theme={null}
    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 theme={null}
    python -c "import horizon; print(horizon.__version__)"
    ```
  </Step>
</Steps>

## Your First Strategy

Create a file `my_strategy.py`:

```python theme={null}
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:

<CodeGroup>
  ```bash Direct theme={null}
  python my_strategy.py
  ```

  ```bash CLI with options theme={null}
  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, Alpaca, IBKR, Coinbase, Robinhood, 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>