Documentation
Skip to content

Quickstart: complete a shadow run

Run a strategy through LiveEngine and SafeBroker with synthetic bars. The example needs Python 3.12-3.14 and uv; it needs no credentials, market-data subscription, or network service after installation. It never sends an order to a venue.

Run the example

Get the maintained example from the public repository, then run it with the published package:

git clone https://github.com/ml4t/live.git
cd live
uv run --isolated --no-project --with ml4t-live python examples/shadow_mode_demo.py

--isolated keeps an existing checkout environment from substituting an editable development package for the published package.

The script defines a synthetic feed that emits one DEMO bar per second for 65 seconds. A moving average strategy submits a buy or sell when its signal changes. SafeBroker records virtual fills and positions under execution_mode="shadow"; the example broker raises if it receives a real order. The input and full program are in examples/shadow_mode_demo.py.

The run prints Starting shadow mode demo with a synthetic feed., timestamped prices, five-second position heartbeats, and Finished shadow mode demo. final_positions=.... The final position may be flat or long because the synthetic signal changes during the run. A completed final line means the engine stopped cleanly. The printed positions show what the virtual portfolio held; no venue state changed.

To check the installed API without waiting for the full run, the README quick start processes a single virtual fill and asserts its resulting position and cash balance. For the next operator task, the reconciliation example shows a restart mismatch without a broker connection.

Understand the boundary

This first run proves that the strategy callback, engine lifecycle, safety wrapper, and virtual portfolio work with synthetic input. It does not qualify a broker, external feed, or restart on an active account. A real paper session needs broker credentials or TWS/IB Gateway, the applicable market-data access, a compatible feed, explicit execution_mode="paper", and clean startup reconciliation. Alpaca and IB feeds require experimental=True and do not have stable reconnect continuity guarantees.

The public OKX funding feed needs outbound HTTPS but no credentials. To try it with the CLI, see Run a bounded shadow session. A quiet feed or a run with no trade intent is not evidence that a provider workflow is ready for paper orders.

Continue