API Reference

Module-by-module reference grounded in the actual code

Public API at a glance

python
import horizon as hz

# Types
from horizon import Signal, Direction, Urgency, TargetPosition, OrderAction, Decision
from horizon import Context, FeedData, PortfolioState
from horizon import Strategy, strategy

# Subpackages
from horizon import features, portfolio, risk, venues, discovery, validate, stats

# Entry points
from horizon import run, connect, BacktestConfig, load_preset, run_preset

Module map

Types `Signal`, `Direction`, `TargetPosition`, `OrderAction`, `Decision` Strategy `Strategy` base class + `@strategy` decorator Features `FeatureStore`, `PriceHistory`, built-in feature classes Portfolio `Sizer` protocol, `KellyOptimizer`, `CarverSystematic`, `EqualWeight` Risk `RiskConfig`, `RiskEngine`, stops, guards, kill switch Venues `Venue` protocol, `Paper`, imperative API Quant library `TSMomentum`, `BollingerMeanRev`, `MovingAverageCross`, `RSIMeanRev`, `Ensemble` Data sources `SyntheticGBM`, `SyntheticRegimes`, `DictSource` Validate `Bootstrap`, `OutOfSample`, `WalkForward` Stats Sharpe bootstrap CIs, Jarque-Bera, Ljung-Box, IV solver + rank, Brier / log loss / Kelly for prediction markets. Research Bundled 239-test taxonomy: query by stage, strategy, category; gate criteria; cross-refs to ``horizon.stats`` implementations.

Top-level entry points

hz.run(mode, strategies, asset_classes, universe, ..., backtest, data_source)

The full pipeline orchestrator. See Backtesting for usage.

Required:

  • mode: "backtest" | "paper" | "shadow" | "live"
  • strategies: list of Strategy subclasses or instances
  • universe: a DiscoveryProvider (or list of market ids auto-wrapped)

Optional:

  • asset_classes: inferred from strategies if not given
  • venues: dict of venue name → Venue instance (defaults to a new Paper venue)
  • portfolio: a Sizer instance (defaults to EqualWeight)
  • risk: a RiskConfig (defaults to empty)
  • backtest: a BacktestConfig (required when mode="backtest")
  • data_source: a DataSource (required when mode="backtest" or "paper")
  • params: free-form params passed into Context

Returns BacktestResult | None. None for modes that are scaffolded (live).

hz.connect(venue_name, **kwargs)

Level-1 imperative API. See Imperative API.

python
with hz.connect("paper", initial_cash_usd=100_000) as ex:
    ex.buy("AAPL", qty=10, limit=180.0)
    print(ex.balance())

hz.load_preset(path) / hz.run_preset(path)

Load and optionally run a .hz.toml preset. See Presets + CLI.

Core conventions

  • Frozen dataclasses for all types (Signal, TargetPosition, Decision, OrderAction, etc.)
  • Protocols for pluggable interfaces (Sizer, Venue, Executor, Feature, DataSource, Strategy)
  • Dotted paths for preset strategy / portfolio references (horizon.quant.TSMomentum)
  • Validation at construction: bad inputs raise immediately, not deep in the pipeline
  • Deterministic execution: seeded RNG throughout, verified by the behavioral audit test suite

Testing your integration

Every public API is covered by the test suite. Run:

bash
PYTHONPATH=. python3 -m pytest tests/ -q
# 1573 passed, 2 skipped in ~13s

If you subclass a public type or protocol, your subclass should pass the same tests.

For a real-network paper-sandbox verification against Alpaca (auth, lifecycle, bracket, cancel, WS fill, options chain, audit chain):

bash
export ALPACA_KEY="PK..." ALPACA_SECRET="..."
python examples/alpaca_paper_smoketest.py

See docs/venues/alpaca for the prerequisites.

Next

Start with types The core vocabulary every other layer speaks.