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

# Strategy Registry

> Browse, pull, and run your Horizon Cloud strategies locally.

The strategy registry lets you browse your deployed strategies on Horizon Cloud, download them locally, and run them with a single command. Think of it as `git pull` for your trading strategies.

## Quick Start

```python theme={null}
import horizon as hz

# List all your cloud strategies
strategies = hz.registry.list()
for s in strategies:
    print(s)
# Strategy('Fed Rate MM' [deployed], id=a1b2c3d4...)
# Strategy('BTC Arb Scanner' [validated], id=e5f6a7b8...)

# Search by keyword
hz.registry.search("market making")

# Pull a strategy locally
pulled = hz.registry.pull("a1b2c3d4-...")
print(pulled.path)
# ~/.horizon/strategies/fed_rate_mm-a1b2c3d4/

# Run it directly
hz.registry.run("a1b2c3d4-...", exchange=hz.Polymarket())
```

## Authentication

The registry uses your SDK key (the same one you use for `hz.run()` and cloud deploy):

```bash theme={null}
export HORIZON_API_KEY="hz_sdk_..."
```

Or pass it explicitly:

```python theme={null}
from horizon import Registry
reg = Registry(api_key="hz_sdk_...")
```

## Browsing Strategies

### List all

```python theme={null}
strategies = hz.registry.list()
```

Returns a list of `StrategyInfo` objects with `id`, `name`, `description`, `status`, `class_name`, `created_at`.

### Search

```python theme={null}
results = hz.registry.search("volatility")
```

Searches your strategies by name, description, and class name. Results are ranked by relevance.

### Details

```python theme={null}
info = hz.registry.info("strategy-id")
print(info["params"])       # strategy parameters
print(info["risk_config"])  # risk configuration
print(info["status"])       # draft, validated, deployed, stopped, error
```

## Version History

Every time you save changes to a strategy on Horizon Cloud, a version snapshot is created automatically.

```python theme={null}
versions = hz.registry.versions("strategy-id")
for v in versions:
    print(v)
# v5 (2026-03-10)
# v4 (2026-03-08)
# v3 (2026-03-05)
```

Pull a specific version:

```python theme={null}
pulled = hz.registry.pull("strategy-id", version=3)
```

## Pulling Strategies

`pull()` downloads the strategy code and metadata to `~/.horizon/strategies/`:

```python theme={null}
pulled = hz.registry.pull("strategy-id")
```

```
~/.horizon/strategies/
  fed_rate_mm-a1b2c3d4/
    strategy.py      # the strategy code
    manifest.json    # metadata, params, risk config, version
```

### Custom directory

```python theme={null}
pulled = hz.registry.pull("strategy-id", directory="./my-strategies")
```

### What's in the manifest

```json theme={null}
{
  "id": "a1b2c3d4-...",
  "name": "Fed Rate MM",
  "description": "Market maker for Fed rate prediction markets",
  "class_name": "FedRateMM",
  "version": 3,
  "params": {"spread": 0.02, "size": 10},
  "risk_config": {"max_position": 100},
  "pulled_at": "2026-03-11T10:30:00Z"
}
```

## Running Strategies

Pull and execute in one step:

```python theme={null}
hz.registry.run("strategy-id", exchange=hz.Polymarket())
```

With a specific version:

```python theme={null}
hz.registry.run("strategy-id", version=3, exchange=hz.Coinbase())
```

The strategy module is dynamically loaded and executed. If it defines a `main()` or `run()` function, that gets called. Otherwise it runs on import (the standard `hz.run()` pattern).

## Managing Local Strategies

### List pulled strategies

```python theme={null}
local = hz.registry.local()
for s in local:
    print(f"{s.name} v{s.version} at {s.path}")
```

### Remove a local strategy

```python theme={null}
hz.registry.remove("strategy-id")
```

## Workflow Example

```python theme={null}
import horizon as hz

# 1. See what you have deployed
for s in hz.registry.list():
    print(f"{s.name} [{s.status}]")

# 2. Pull the one you want
pulled = hz.registry.pull("a1b2c3d4-...", version=5)

# 3. Read and customize the code
code = pulled.code_path.read_text()
print(code[:200])

# 4. Edit locally, then run
hz.registry.run("a1b2c3d4-...", exchange=hz.Polymarket(), mode="paper")
```

<Tip>
  Use `pull()` to download and inspect strategy code before running it. The pulled strategy is plain Python you can read, modify, and version control with git.
</Tip>