Concepts

Market Lab is organized around four command layers:

• source: raw market data access
• study: computed market metrics built on top of market data
• strategy: logic that consumes a time series and emits live events or backtest summaries
• script: local JavaScript logic over Market Lab data sources

This separation matters because it keeps the CLI predictable.

Source

source commands expose provider data directly.

Examples:

• source orderbook
• source candles
• source vd
• source oi
• source volumes

Use source when you want:

• current market state
• raw or lightly-normalized time series
• streaming updates from a provider

Study

study commands compute market structure or execution metrics from source data.

Examples:

• study spread
• study depth
• study imbalance
• study slippage
• study vamp
• study cvd

Use study when you want:

• execution cost estimates
• liquidity shape
• orderbook imbalance
• derived statistics that are more useful than raw provider output

Strategy

strategy commands consume time-series data and evaluate logic over it.

Current example:

• strategy run sma-crossover
• strategy backtest sma-crossover

There are two modes:

• run mode for live evaluation
• backtest mode for historical evaluation

Run mode returns event-oriented output.

Backtest mode returns summary-oriented performance output.

Script

script commands run local JavaScript inside the CLI.

Scripts are not split into study scripts and strategy scripts. The script result determines how Market Lab can use it:

• metrics-only output is analysis-oriented
• signal or intent output is strategy-like and can be backtested

Current script commands:

• script run
• script backtest
• script runs list
• script runs show

Time Model

Market Lab uses milliseconds at the app boundary.

That means --from, --to, and ts_ms are millisecond-oriented in the CLI and JSON outputs.

Some providers, such as MMT, accept seconds over their API. Market Lab converts to provider-native units only at the adapter boundary.

Output Modes

The CLI is designed for both humans and machines.

• terminal: compact human-readable output
• json: machine-readable output
• jsonl: stream-friendly machine-readable output

For study and strategy, default JSON is compact. Add --verbose if you want expanded context.