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

# CLI

> Trade prediction markets, equities, options, and crypto. Discover opportunities and manage funds from the command line.

The Horizon CLI gives you full access to the trading engine, market discovery, wallet analytics, and fund management from your terminal. Every command supports `--json` for pipeable output.

## Installation

<CodeGroup>
  ```bash pip theme={null}
  pip install horizon-sdk
  ```

  ```bash uv theme={null}
  uv pip install horizon-sdk
  ```

  ```bash uvx (no install) theme={null}
  uvx horizon-sdk discover "election"
  ```

  ```bash bunx (no install) theme={null}
  bunx horizon-sdk discover "election"
  ```
</CodeGroup>

After installation, the `horizon` command is available on your PATH:

```bash theme={null}
horizon --help
```

Or run without installing using `uvx` or `bunx`:

```bash theme={null}
uvx horizon-sdk top-markets --json | jq '.[0]'
bunx horizon-sdk top-markets --json | jq '.[0]'
```

## Quick Start

```bash theme={null}
# Search for markets
horizon discover "bitcoin"

# See the hottest markets
horizon top-markets --limit 5

# Size a position with Kelly
horizon kelly --prob 0.65 --price 0.50 --bankroll 1000

# Check a wallet's P&L
horizon wallet value 0x1234...abcd

# Run a strategy
horizon run my_strategy.py --mode paper --dashboard
```

## Configuration

The CLI reads configuration from environment variables:

```bash theme={null}
export HORIZON_API_KEY="your-key"
export HORIZON_EXCHANGE="paper"          # paper, polymarket, kalshi
export HORIZON_DB="./horizon.db"         # persistence database path

# For Polymarket live trading
export POLYMARKET_API_KEY="..."
export POLYMARKET_API_SECRET="..."
export POLYMARKET_API_PASSPHRASE="..."
export POLYMARKET_PRIVATE_KEY="..."

# For Kalshi live trading
export KALSHI_API_KEY="..."
```

## Global Options

| Flag        | Description                              |
| ----------- | ---------------------------------------- |
| `--json`    | Output as JSON (pipeable to jq, scripts) |
| `--version` | Show version                             |
| `--help`    | Show help                                |

```bash theme={null}
# Human-readable output
horizon discover "election"

# JSON output for scripting
horizon discover "election" --json | jq '.[].slug'
```

## Commands

### Discovery

<AccordionGroup>
  <Accordion title="discover - Search markets">
    ```bash theme={null}
    horizon discover [QUERY] [OPTIONS]
    ```

    | Option       | Default      | Description                        |
    | ------------ | ------------ | ---------------------------------- |
    | `--exchange` | `polymarket` | Exchange to search                 |
    | `--limit`    | `10`         | Number of results                  |
    | `--type`     | `all`        | `all`, `binary`, or `multi`        |
    | `--category` | -            | Category filter (crypto, politics) |

    ```bash theme={null}
    horizon discover "election" --limit 5
    horizon discover "bitcoin" --exchange kalshi
    horizon discover --type binary --category crypto --json
    ```
  </Accordion>

  <Accordion title="events - Multi-outcome events">
    ```bash theme={null}
    horizon events [QUERY] [OPTIONS]
    ```

    | Option    | Default | Description      |
    | --------- | ------- | ---------------- |
    | `--limit` | `10`    | Number of events |

    ```bash theme={null}
    horizon events "super bowl" --limit 5
    ```
  </Accordion>

  <Accordion title="top-markets - Highest volume">
    ```bash theme={null}
    horizon top-markets [OPTIONS]
    ```

    | Option       | Default      | Description       |
    | ------------ | ------------ | ----------------- |
    | `--exchange` | `polymarket` | Exchange          |
    | `--limit`    | `10`         | Number of markets |
    | `--category` | -            | Category filter   |

    ```bash theme={null}
    horizon top-markets --limit 20
    horizon top-markets --exchange kalshi --json
    ```
  </Accordion>

  <Accordion title="market - Market detail">
    ```bash theme={null}
    horizon market SLUG [OPTIONS]
    ```

    | Option       | Default      | Description |
    | ------------ | ------------ | ----------- |
    | `--exchange` | `polymarket` | Exchange    |

    ```bash theme={null}
    horizon market "will-trump-win-2024"
    horizon market "KXBTC-25MAR14" --exchange kalshi --json
    ```
  </Accordion>
</AccordionGroup>

### Trading

<AccordionGroup>
  <Accordion title="submit - Place an order">
    ```bash theme={null}
    horizon submit [OPTIONS]
    ```

    | Option          | Required | Default | Description       |
    | --------------- | -------- | ------- | ----------------- |
    | `--market-id`   | Yes      | -       | Market identifier |
    | `--side`        | Yes      | -       | `buy` or `sell`   |
    | `--price`       | Yes      | -       | Limit price (0-1) |
    | `--size`        | Yes      | -       | Order size        |
    | `--market-side` | No       | `yes`   | `yes` or `no`     |

    ```bash theme={null}
    horizon submit --market-id will-btc-hit-100k --side buy --price 0.55 --size 10
    horizon submit --market-id will-btc-hit-100k --side sell --market-side no --price 0.45 --size 5
    ```
  </Accordion>

  <Accordion title="cancel / cancel-all - Cancel orders">
    ```bash theme={null}
    horizon cancel ORDER_ID
    horizon cancel-all
    ```
  </Accordion>

  <Accordion title="positions / orders / fills - View state">
    ```bash theme={null}
    horizon positions
    horizon orders --market-id will-btc-hit-100k
    horizon fills --limit 50
    ```
  </Accordion>

  <Accordion title="kill-switch - Emergency stop">
    ```bash theme={null}
    horizon kill-switch on --reason "volatility spike"
    horizon kill-switch off
    ```
  </Accordion>

  <Accordion title="status - Engine overview">
    ```bash theme={null}
    horizon status
    horizon status --json
    ```

    Shows PnL, open orders, active positions, kill switch state, and uptime.
  </Accordion>
</AccordionGroup>

### Analytics

<AccordionGroup>
  <Accordion title="kelly - Position sizing">
    ```bash theme={null}
    horizon kelly [OPTIONS]
    ```

    | Option       | Required | Default | Description            |
    | ------------ | -------- | ------- | ---------------------- |
    | `--prob`     | Yes      | -       | True probability (0-1) |
    | `--price`    | Yes      | -       | Market price (0-1)     |
    | `--bankroll` | No       | `1000`  | Capital in USD         |
    | `--fraction` | No       | `0.25`  | Kelly fraction         |
    | `--max-size` | No       | `100`   | Max position           |

    ```bash theme={null}
    horizon kelly --prob 0.65 --price 0.50 --bankroll 5000
    horizon kelly --prob 0.8 --price 0.60 --fraction 0.5 --json
    ```
  </Accordion>

  <Accordion title="parity - Arbitrage check">
    ```bash theme={null}
    horizon parity MARKET_ID [--feed FEED_NAME]
    ```

    Checks if YES + NO prices sum to \~1.0.

    ```bash theme={null}
    horizon parity "will-btc-hit-100k"
    ```
  </Accordion>

  <Accordion title="simulate - Monte Carlo">
    ```bash theme={null}
    horizon simulate [OPTIONS]
    ```

    | Option        | Default | Description     |
    | ------------- | ------- | --------------- |
    | `--scenarios` | `10000` | Number of paths |
    | `--seed`      | -       | Random seed     |

    ```bash theme={null}
    horizon simulate --scenarios 50000 --json
    ```
  </Accordion>
</AccordionGroup>

### Wallet Analytics

All wallet commands are under the `wallet` subgroup:

```bash theme={null}
horizon wallet COMMAND [ARGS]
```

<AccordionGroup>
  <Accordion title="wallet trades - Trade history">
    ```bash theme={null}
    horizon wallet trades ADDRESS [--limit N] [--condition-id ID]
    ```

    ```bash theme={null}
    horizon wallet trades 0x1234...abcd --limit 20
    horizon wallet trades 0x1234...abcd --json | jq '[.[] | .usdc_size] | add'
    ```
  </Accordion>

  <Accordion title="wallet positions - Open positions">
    ```bash theme={null}
    horizon wallet positions ADDRESS
    ```
  </Accordion>

  <Accordion title="wallet value - Portfolio value">
    ```bash theme={null}
    horizon wallet value ADDRESS
    ```
  </Accordion>

  <Accordion title="wallet profile - Public profile">
    ```bash theme={null}
    horizon wallet profile ADDRESS
    ```
  </Accordion>

  <Accordion title="wallet score - Performance score">
    ```bash theme={null}
    horizon wallet score ADDRESS [--limit N]
    ```
  </Accordion>

  <Accordion title="wallet top-holders - Largest holders">
    ```bash theme={null}
    horizon wallet top-holders CONDITION_ID [--limit N]
    ```
  </Accordion>

  <Accordion title="wallet flow - Buy/sell flow">
    ```bash theme={null}
    horizon wallet flow CONDITION_ID [--window HOURS] [--min-size USD]
    ```
  </Accordion>

  <Accordion title="wallet market-trades - Market trades">
    ```bash theme={null}
    horizon wallet market-trades CONDITION_ID [--limit N]
    ```
  </Accordion>
</AccordionGroup>

### Feed Management

All feed commands are under the `feed` subgroup:

```bash theme={null}
horizon feed COMMAND [ARGS]
```

<AccordionGroup>
  <Accordion title="feed list - Active feeds">
    ```bash theme={null}
    horizon feed list
    horizon feed list --json
    ```
  </Accordion>

  <Accordion title="feed snapshot - Latest data">
    ```bash theme={null}
    horizon feed snapshot FEED_NAME
    ```
  </Accordion>

  <Accordion title="feed health - Staleness check">
    ```bash theme={null}
    horizon feed health [--threshold SECONDS]
    ```
  </Accordion>

  <Accordion title="feed metrics - Connection stats">
    ```bash theme={null}
    horizon feed metrics FEED_NAME
    ```
  </Accordion>

  <Accordion title="feed start - Start a feed">
    ```bash theme={null}
    horizon feed start NAME TYPE [OPTIONS]
    ```

    | Option       | Description              |
    | ------------ | ------------------------ |
    | `--symbol`   | Symbol for Binance feeds |
    | `--url`      | URL for REST feeds       |
    | `--config`   | JSON config string       |
    | `--interval` | Poll interval (seconds)  |

    ```bash theme={null}
    horizon feed start btc-price binance_ws --symbol btcusdt
    horizon feed start nba-scores espn --config '{"sport":"basketball","league":"nba"}'
    ```
  </Accordion>
</AccordionGroup>

### Fund Management

All fund commands are under the `fund` subgroup:

```bash theme={null}
horizon fund COMMAND [ARGS]
```

<AccordionGroup>
  <Accordion title="fund status / report">
    ```bash theme={null}
    horizon fund status
    horizon fund report --json
    ```
  </Accordion>

  <Accordion title="fund deploy / stop / pause / resume">
    ```bash theme={null}
    horizon fund deploy --name my-mm --markets will-btc-hit-100k --mode paper
    horizon fund stop my-mm
    horizon fund pause my-mm
    horizon fund resume my-mm
    ```
  </Accordion>

  <Accordion title="fund list / scale">
    ```bash theme={null}
    horizon fund list
    horizon fund scale my-mm --capital 10000
    ```
  </Accordion>

  <Accordion title="fund nav / risk / pnl / stress-test">
    ```bash theme={null}
    horizon fund nav --limit 30
    horizon fund risk
    horizon fund pnl
    horizon fund stress-test
    ```
  </Accordion>

  <Accordion title="fund explain / regime / alerts">
    ```bash theme={null}
    horizon fund explain
    horizon fund regime
    horizon fund alerts --limit 10
    ```
  </Accordion>
</AccordionGroup>

### Account

<AccordionGroup>
  <Accordion title="setup - Create account">
    ```bash theme={null}
    horizon setup user@example.com --name "My Bot"
    ```
  </Accordion>

  <Accordion title="login - Login">
    ```bash theme={null}
    horizon login user@example.com
    ```
  </Accordion>

  <Accordion title="key-status - Check credentials">
    ```bash theme={null}
    horizon key-status
    ```
  </Accordion>
</AccordionGroup>

### Database Queries

For offline analysis of persisted strategy data, use the `db` subgroup:

```bash theme={null}
horizon db COMMAND [OPTIONS]
```

<AccordionGroup>
  <Accordion title="db fills - Historical fills">
    ```bash theme={null}
    horizon db fills [--path DB] [--limit N] [--market ID]
    ```

    ```bash theme={null}
    horizon db fills --path ./my_strategy.db --limit 20
    horizon db fills --market will-btc-hit-100k
    ```
  </Accordion>

  <Accordion title="db positions - Position snapshots">
    ```bash theme={null}
    horizon db positions [--path DB]
    ```
  </Accordion>

  <Accordion title="db orders - Order history">
    ```bash theme={null}
    horizon db orders [--path DB] [--limit N] [--open-only/--all]
    ```
  </Accordion>
</AccordionGroup>

## Scripting with --json

Every command supports `--json` for structured output. Pipe to `jq` for powerful scripting:

```bash theme={null}
# Get the slug of the top market
horizon top-markets --limit 1 --json | jq -r '.[0].slug'

# Sum a wallet's total PnL
horizon wallet positions 0x1234...abcd --json | jq '[.[].pnl] | add'

# Find markets with edge > 5%
horizon discover "crypto" --json | jq '[.[] | select(.yes_price < 0.45)]'

# Kelly size across multiple scenarios
for prob in 0.55 0.60 0.65 0.70; do
  echo "prob=$prob: $(horizon kelly --prob $prob --price 0.50 --json | jq .optimal_size)"
done
```

## Architecture

The CLI shares the same tool layer as the MCP servers. All three interfaces delegate to `horizon.tools`, which wraps the Rust engine via PyO3:

```
horizon.tools (shared business logic)
    |
    +---> horizon.cli        (Click CLI, for humans)
    +---> horizon.mcp_server (MCP server, for AI agents)
    +---> horizon.mcp_fund   (MCP fund server, for AI agents)
```

This means the CLI has feature parity with the MCP interface. Same functions, same data, different transport.