ml4t-live

Live trading runtime for ML4T strategies with broker integrations, risk checks, and shadow mode.

Use ml4t-live after a strategy has passed research and backtesting. It runs strategies that follow lifecycle version 1 against Interactive Brokers or Alpaca, applies SafeBroker limits, and supports a staged path from shadow mode to paper trading and live execution.

Installation

ml4t-live supports Python 3.12, 3.13, and 3.14 on Linux, macOS, and Windows.

uv add ml4t-live

The default installation includes the Interactive Brokers, Alpaca, CCXT, and OKX adapters. Install the experimental extra only when evaluating the DataBento feed:

uv add 'ml4t-live[experimental]'

Broker execution requires an account, a configured paper or live environment, and market-data permissions. The credential-free quick start below verifies the installed public API and shadow portfolio behavior without contacting a broker or placing an order.

Quick start

from ml4t.backtest import Order, OrderSide, OrderStatus
from ml4t.live import VirtualPortfolio

portfolio = VirtualPortfolio(initial_cash=100_000)
fill = Order(
    asset="SPY",
    side=OrderSide.BUY,
    quantity=10,
    order_id="shadow-1",
    status=OrderStatus.FILLED,
    filled_price=500.0,
    filled_quantity=10,
)
portfolio.process_fill(fill)

position = portfolio.positions["SPY"]
assert position.quantity == 10
assert portfolio.cash == 95_000
print(f"shadow position: {position.quantity:g} SPY")

Expected output:

shadow position: 10 SPY

Continue with the shadow-mode tutorial before connecting a provider.

Supported boundary

• LiveEngine, SafeBroker, Interactive Brokers and Alpaca execution adapters, the OKX funding feed, and typed bar aggregation are stable-supported within their documented capabilities.
• Alpaca, Interactive Brokers, generic CCXT, and DataBento feeds require explicit experimental opt-in with experimental=True. Experimental adapters report their missing guarantees on first use.
• Shadow mode never routes orders to the wrapped broker. Paper and live modes require explicit execution identity and provider-specific qualification.
• State and journal files enforce current-user ownership and mode 0600 on POSIX systems. On Windows, restrict the containing directory with service-account ACLs.
• The package has no hardware-specific acceleration or hardware dependency.

Read the support and qualification boundary before promoting a strategy beyond shadow mode.

Documentation

• Installation
• Backtest-to-live migration
• Risk controls
• Brokers
• Data feeds
• Operator CLI
• API reference

ml4t-backtest provides the portable Strategy lifecycle used here. ml4t-specs defines the shared lifecycle and canonical intent contracts. See the ML4T libraries page for the broader ecosystem.

Development

Read the contribution guide before opening an issue or pull request.

git clone https://github.com/ml4t/live.git
cd live
uv sync --all-extras --dev --locked

uv run ruff check --no-fix src tests
uv run ruff format --check src tests
uv run ty check
uv run pytest

Run the repository's full release qualification before preparing a release:

uv run python scripts/qualification/run_stable_gate.py

The qualification script is the authoritative definition of the full release gate.

Report defects through the issue tracker. Report suspected vulnerabilities through private vulnerability reporting, not a public issue. Release notes and artifacts are available from GitHub Releases.

License

MIT