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

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