Concepts

Market Lab is organized around five command layers:

• source: raw market data access
• study: computed market metrics built on top of market data
• strategy: native Rust execution algorithms for user-supplied trading intent
• script: JavaScript analysis and strategy logic over one or more sources
• execution: simulated or live trade effects produced by explicit execution calls

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 execute a parent order according to a native algorithm. The user supplies the symbol, side, amount, and execution controls. The strategy determines how the order is scheduled or divided.

Current strategy:

• strategy run twap

TWAP divides a parent amount into child orders and submits them over time. Live strategies are detached jobs owned by mlabd, so the CLI returns after deployment.

Use a strategy when you already know what you want to execute:

• side: buy or sell
• amount: exact size or margin multiplied by leverage
• execution window and cadence

A strategy does not decide whether the market should be bought or sold. An autonomous bot owns that decision internally. Scripts remain the flexible layer and can implement either model. See Strategies.

Script

script commands run JavaScript in a bounded QuickJS runtime.

Scripts are not split into study scripts and strategy scripts. Their behavior determines how Market Lab uses them:

• returning metrics is analysis-oriented
• calling ctx.trade or ctx.cancel is strategy execution
• script backtest sends those calls to the historical simulator
• script run --venue bulk sends those calls to mlabd for live BULK execution

Current script commands:

• script run
• script backtest
• script jobs
• script status
• script logs
• script stop
• script restart
• script runs list
• script runs show

Execution

Execution is always explicit. CLI users issue trade, cancel, close, or submit a confirmed built-in strategy; scripts call ctx.trade or ctx.cancel. Script return values are optional diagnostics, not execution instructions; signal and intent fields are rejected.

Use execution when you want to:

• preview an order with --dry-run
• place a confirmed market or limit order
• inspect positions, open orders, and fills
• cancel an order or close a position
• inspect mlabd lifecycle state and events
• deploy and supervise live strategy jobs

Live mutations route through mlabd; public market data, backtest simulation, and read-only account queries do not. See Execution and Script Execution.

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 studies, default JSON is compact. Built-in strategy submission returns a persistent job record; strategy worker output is available through strategy logs.