Documentation/Lightwick Script

Review what your agent authored.

You usually do not need to write Lightwick Script yourself. It is the deterministic, completed-bar language your agent uses to express plots, advisory signals, and risk rules in a form you can inspect and reproduce.

Designed to be inspectable.

A .mtrade file cannot place orders, access the network or filesystem, read the wall clock, generate randomness, or call arbitrary Swift or JavaScript.

A complete strategy

This example combines inputs, a helper expression, session-aware logic, a completed higher timeframe, plots, protective risk, and advisory events.

Session-Breakout.mtrade

language 2
strategy "Session Breakout"
timezone "America/New_York"

input len: int = 14 in 2...100
input stop_atr: number = 2.0 in 0.5...10

define stop_distance(multiple) = multiple * atr(len)

let trend = timeframe("h1", ema(close, 50))
let rth = in_session(570, 960)
let breakout = crosses_above(close, highest(high, 20)[1])

plot trend as "H1 Trend"
plot rsi(close, len) as "RSI" pane "RSI"
hline 70.0 as "Overbought" pane "RSI"

risk stop_loss offset stop_distance(stop_atr)
risk take_profit offset stop_distance(stop_atr * 2)
risk max_bars bars 40

signal buy when rth and close > trend and breakout
signal exit when not rth

timeframe("h1", …)

Maps the last fully completed hourly value onto the chart without looking ahead.

highest(high, 20)[1]

Uses the prior completed value; historical indexing can only look backward.

risk stop_loss

Resolves on every bar, then samples the distance when a position is entered.

signal exit

Closes an open position. A sell signal would open or reverse short.

Declarations

Scripts are read from top to bottom. Bindings are immutable and must be declared before use.

language 2

Declare the required language version. Versions 1 and 2 compile.

strategy "Name"

Name the strategy. It must match the saved strategy name.

timezone "America/New_York"

Set the calendar for clock values and session VWAP. UTC is the default.

input

Declare an immutable int, number, or bool that testing and optimization can vary.

define

Create a reusable, non-recursive expression that is inlined at each call site.

let

Bind an immutable expression before it is used.

plot / hline

Draw a numeric series or static level on price or in a named pane.

signal

Emit an advisory buy, sell, or exit event on a false-to-true transition.

risk

Declare a stop loss, target, trailing stop, or maximum holding period.

Signals, fills, and risk

These semantics matter more than punctuation. They determine what a correct-looking strategy actually does.

Signals are transitions

A signal fires only when its condition moves exactly from false to true. It does not repeat while the condition remains true, and missing-to-true does not fire.

The last bar may still be forming

Live evaluation excludes the final forming candle. Historical MCP tools treat stored bars as completed.

Fills happen on the next bar

A signal on a completed bar fills at the next bar's open. A signal on the final available bar cannot execute.

Sell is not exit

buy enters or reverses long; sell enters or reverses short; exit closes to flat.

Intrabar risk has an order

The backtester checks the tighter fixed or trailing stop first, then the target, then max_bars.

Risk declarations

risk stop_loss     percent 1.5
risk stop_loss     offset  2 * atr(14)
risk take_profit   offset  3 * atr(14)
risk trailing_stop percent 1.0
risk max_bars      bars    40

Percent and offset bases apply to stop_loss, take_profit, and trailing_stop. max_bars uses the bars basis. Each risk field may be declared once.

Values, missing data, and state

The language keeps per-bar behavior explicit and bounded.

Market values

open, high, low, close, volume, hl2, hlc3, and ohlc4.

Bar clock

time, bar_index, calendar fields, session time, and new-day or new-week flags resolve in the declared timezone.

Missing values

Warm-up and invalid per-bar arithmetic produce missing values, not zero. Use na, fill_missing, or hold explicitly.

State without recursion

Use bounded functions such as bars_since, value_when, cum_since, count, and latch.

Higher timeframes

timeframe("h1", expression) sees market values, the bar clock, inputs, built-ins, and helpers—but not chart-timeframe let bindings.

Boolean arithmetic

Booleans are not numbers. Use iff(condition, a, b) or to_number(condition) when arithmetic needs a condition.

Canonical reference

Function signatures and grammar are generated by the language implementation so agents and tooling do not need to guess.

get_language_guide

Read the full semantics and worked examples over MCP.

list_builtins

List functions and values by category, including math, indicators, state, time, and timeframe.

get_grammar

Read EBNF, the current language version, signal kinds, and risk fields.

validate_strategy

Compile a draft and return diagnostics with stable codes, ranges, and suggestions.

Command-line reference for developers

The optional CLI exposes the same compiler metadata and can check or format local files.

lightwick-script

swift run lightwick-script check strategy.mtrade --json
swift run lightwick-script format strategy.mtrade
swift run lightwick-script builtins --json
swift run lightwick-script grammar

Current limitation

Lightwick Script currently receives OHLCV bars only. Per-bar bid volume, ask volume, and delta are not available to scripts or historical research, so footprint and order-flow strategies cannot yet be represented faithfully.