ScanLang

ScanLang is the safe, declarative screening DSL used to author custom indicators for the scanner. A single program computes one per-symbol decision or scorefrom a symbol’s price and volume history — nothing more, nothing less.

The language is deliberately small. There is no exec, no imports, no attribute access, and no file or network I/O. The interpreter isthe sandbox: programs are safe by construction, which is precisely what lets users — and the AI indicator-creation tool — author and save indicators with no code-jailing, no containers, and no review gate.

A compiled ScanLang program exposes the same calculate(bars, params[, context])contract as a hand-written Python indicator, and it delegates every bit of its math to the same vetted helper functions. As a result a ScanLang indicator scores byte-for-byte identical to its Python equivalent — we call this parity by construction. You are not approximating the Python engine; you are driving it.

A program reads strictly top-to-bottom: headers first (timeframe, requires, params), then a body of statements ending in exactly one output. The output is the indicator’s verdict for the symbol — a boolean, a number, or a categorical state.

timeframe 5m
requires 50 bars
params {
  period = 50 : int(2..400)
}
let fast = ema(close, 8)
let slow = ema(close, period)
guard close > 0
output fast > slow

Everything else in the language — windows, sessions, loops, details, visuals — layers on top of this core shape without changing it.

Every program has the same skeleton: an optional run of headers describing what data the indicator needs, followed by the statements that compute its answer.

program  := comment* header* statement*
header   := timeframe | requires | params   // each at most once, before any statement

The rules are few and worth internalizing:

• Comments may appear anywhere— before headers, between statements, or at the end of a line.
• Headers are optional, but when present each may appear at most once and all of them must come before any statement.
• The body is a sequence of statements, and exactly one of them must be an output— the program’s single result.
• Whitespace is insignificant, with one exception: a newline terminates a statement.

Understanding how values behave is the key to reading and writing ScanLang fluently. At runtime every value is one of just five types.

The reduction rule

This is the single most important concept in the language. A SERIES is a whole list of values, one per bar, but most of the time you only care about where the symbol is right now. ScanLang resolves this automatically.

Functions that genuinely need the whole list — such as ema and sma— declare a SERIES parameter and therefore receive the series untouched. Reduction happens only at the boundary into a scalar context.

When you do want to reach into history explicitly, index the series. Indexing is newest-relative: [0] is the most recent bar and the index counts backward in time.

close[0]   // latest bar
close[1]   // one bar ago
close[5]   // five bars ago

Coercion and the None sentinel

• A bool used as a number reduces to 1.0 / 0.0, so you can sum truthy conditions to count how many fired.
• Noneis the “insufficient data” sentinel. It propagates through arithmetic and comparisons, and ultimately makes the indicator return None — i.e. no signal for that symbol — rather than crashing.
• An out-of-range index returns None, following the same no-signal rule.

The lexer is small and predictable. This section covers the raw tokens — comments, literals, newlines, operators, and reserved words — that make up every program.

Comments

There are two line-comment forms and no block comments:

// line comment to end of line
# alternative line comment

Numbers and strings

Numbers come as 42 (integer), 2.5 (float), or .75 (the float 0.75). Integers and floats are kept distinct internallyso that the language preserves Python’s math semantics exactly.

Strings are double-quoted and support the escapes \\, \", \n, and \t — for example "above_both", which is how STATE values are written.

Newlines and line continuation

Newlines are statement terminators, with two exceptions. Inside ( … ) and [ … ] newlines are suppressed, so you can split a long call or boolean across lines as long as it is wrapped in parentheses. Inside { … } blocks, newlines separate the statements, params, or fields within. This is exactly why a multi-line boolean must be parenthesised:

output (
  close > ema(close, 8)
  and close > ema(close, 21)
  and close > ema(close, 50)
)

Operators and punctuation

->  :=  >=  <=  ==  !=  ..
+ - * / %   > <   ( ) [ ] { }   : , .

Keywords and reserved words

anchor as bars by default detail else false find_first find_last for guard if key
let on output params requires select timeframe to true var visual when while within

The window-aggregation names are reserved too:

avg_over count max_over min_over ratio_where run_length sum_over

And the timeframe literals are their own reserved tokens: daily, 1m, 5m, 15m, 30m, 1h.

Headers configure how an indicator is compiled and run before any logic executes. They are all optional, may each appear at most once, and must come before the first statement in the program.

timeframe

The timeframe header declares the primary timeframe the program operates on. When omitted, the default is daily. The accepted values are daily, 1m, 5m, 15m, 30m, and 1h.

timeframe 5m

output close > ema(close, 20)

requires … bars

The requires header is a warmup guard. If fewer than N bars are available, the indicator returns Noneinstead of producing a signal — this prevents windowed calculations from emitting noise before enough history has accumulated. The bar count can be a literal, or it can reference a declared param (optionally with arithmetic).

requires 50 bars
requires period bars
requires period + 10 bars

params

The params header declares the tunable parameters an indicator exposes. Each entry has a name, a default value, and an optional type hint with an optional range. These hints feed the parameter schema that the UI surfaces, so users can adjust them without editing the program.

params {
  period = 50 : int(2..400)
  threshold = 1.5
  fast = 8 : int(2..50)
}

The type hint may be int, float, or number, each with an optional (low..high) range. A param without a hint (like threshold above) is inferred from its default value.

The body of a program is a sequence of statements. Statements bind values, guard against bad data, and declare the single output. Order matters: a binding must appear before it is used.

let — immutable binding

let introduces an immutable name. Once bound, a let cannot be reassigned. The subtlety is in what gets bound:

• let x = close binds the series— it is reduced lazily wherever it is used, so it can still be indexed.
• let x = volume / sma(volume, 20) evaluates the arithmetic eagerly and collapses to a single latest-bar scalar. It can no longer be indexed.

let fast = ema(close, 8)
let slow = ema(close, 21)

output fast > slow

var and :=

var declares a mutable binding, and :=reassigns it. Only vars can be reassigned — an attempt to reassign a let is an error. This is what makes accumulators possible.

var count = 0
count := count + 1

guard

guard checks a precondition. If the condition is false or None, the indicator immediately returns None and produces no signal. Guards are the idiom for bailing out on insufficient data or invalid prices.

guard close > 0
guard bar_count >= 50

output close > ema(close, 50)

output

Every program has exactly one output statement. The type of its value defines the indicator’s output type: a boolean signal, a number, or a state.

output fast > slow                          // boolean
output (close - ema(close, 50)) / close     // number
output select { … }                         // state

Expressions combine literals, names, series, and calls with operators. Precedence determines how an unparenthesized expression groups; use parentheses whenever the intent is not obvious.

Operator precedence

From lowest binding (evaluated last) to highest binding (evaluated first):

within
or
and
not
comparison   ( >  >=  <  <=  ==  != )
+  -
*  /  %
unary -
postfix      ( call(…)   index[…]   .member )
primary      ( literal | name | (expr) | select | on | window | find )

Arithmetic

The arithmetic operators are +, -, *, /, and %. Division or modulo by zero yields None rather than raising an error, which keeps a single bad bar from crashing a scan.

output (close - ema(close, 50)) / close * 100

Comparison

The comparison operators are >, >=, <, <=, ==, and !=. A comparison against missing data (None) is false. The equality operators == and != also compare states (strings).

Logical

and, or, and not are short-circuiting. For truthiness: None, 0, "" (empty string), and [] (empty list) are false; non-zero numbers and non-empty strings are true.

output not (close < ema(close, 50)) and volume > 1000

Indexing

series[i] indexes a series newest-relative: close[0] is the latest bar, close[1] is the previous one, and so on. An out-of-range index returns None. Only series can be indexed — indexing a scalar let raises Indexing requires a series.

Member access

The . operator reaches into ambient handles and bar objects:

session.first(5)     // first 5 bars of the current session
bar.time             // timestamp of the latest bar
bar.index            // session index of the latest bar
context.direction    // a scalar passthrough field from the engine context
bbar.close           // a field of a bar returned by find_first/find_last

Function calls

Function calls invoke the built-in library — for example ema(close, 50), highest(high, 6), and clamp(score, 0, 100).

select is a multi-way branch that produces a state— a string label. It is the primary way to emit a categorical signal instead of a plain boolean or number.

Each arm is a condition -> value pair. The first arm whose condition is truthy wins. An optional default arm acts as the fallback when no other arm matches.

output select {
  close > sma(close, 20) and close > sma(close, 50) -> "above_both"
  close < sma(close, 20) and close < sma(close, 50) -> "below_both"
  default -> "between"
}

Derived state options

The set of possible states — stateOptions, surfaced to the chart and UI — is derived automatically from the string-literal arms. You do not declare them separately; the arms are the source of truth.

Numeric select for scoring

select can also produce numbers instead of strings. Arms that return values like 1.0 / 0.0 are a common way to emit a score, branching on conditions to assign a numeric weight.

output select {
  close > sma(close, 50) and volume > sma(volume, 20) -> 1.0
  close > sma(close, 50)                               -> 0.5
  default                                              -> 0.0
}

A window aggregation evaluates a { body } block once per bar across a trailing window of N bars, then folds the per-bar results into a single value. They turn a question about one bar into a question about a stretch of recent history without an explicit loop.

The window size is optional. When you omit it, the body runs over every available bar; when you supply it, the body runs over only the most recent N bars. The body itself is an ordinary ScanLang expression — whatever it returns determines which aggregation forms are meaningful.

let bars_above = count(10) { close > ema(close, 8) }
let up_ratio   = ratio_where(20) { close > open }
let avg_vol    = avg_over(20) { volume }

There are two families: boolean reducers that count, measure runs, or take a fraction of truthy bars, and numeric reducers that sum, average, or take the extreme of a numeric body across the window.

The numeric reducers ignore non-finite values, so a missing or undefined bar will not poison a sum_over or avg_over. run_lengthis especially useful for “how many bars in a row” conditions — for example the length of the current streak of higher closes.

Sessions and multi-timeframe features let a filter look beyond its own timeframe and bar — at the opening range, at a higher timeframe, or at a specific earlier bar in the session. They require the three-argument context form of an indicator, calculate(bars, params, context).

You never write that signature yourself. The compiler detects when a program reaches for context and flips the indicator into context mode (needs_context = true); the scan engine then supplies the context bundle at evaluation time. Using on(TF), session.*, or context.* triggers this. Plain bar.* and within do not.

Evaluating against another timeframe

on(TF) { expr }temporarily switches the ambient bars and session to the named timeframe’s data from the engine context, evaluates expr there, and restores the original timeframe afterward.

timeframe 5m
let or_high = on(30m) { highest(high, 1) within session.first(1) }
output close > or_high

Here a 5-minute scan reads the high of the first 30-minute bar of the session — the opening-range high — and checks whether price has broken above it. A missing timeframe yields None, so guard against it where it matters.

Restricting the ambient bars with within

within scope evaluates its left expression with the ambient bars limited to the given bar list. It is how you point an otherwise whole-history reducer at just the opening range, or at a slice of bars before some reference bar.

highest(high, 1) within session.first(1)
let avg_vol = mean(volume, 99) within bars_before(bbar, 10)

Session accessors

Session accessors expose the bars of the current trading session and a couple of scalars describing it.

Bar handle & context passthrough

The bar handle reads the latest bar, and context.<field> reads any scalar the engine attached to the context bundle.

bar.time            // latest bar timestamp
bar.index           // latest bar session index
context.<field>     // any scalar field from the engine context (e.g. context.playbook_score)

Finding bars

find_first(scope) { predicate } returns the first bar in scope where the predicate is truthy; find_last returns the last. When nothing matches they return None, so test the result with exists(bbar) before reading a field off it with bbar.<field>.

let bbar = find_first(drop(session.bars, 1)) { close > or_high }
output exists(bbar) and bbar.close > or_high

Build the scope with helpers like bars_before(bar, n) (the n bars preceding a reference bar) and drop(bars, n) (the bar list with its first n entries removed). In the example above, drop(session.bars, 1) skips the opening bar so the breakout search starts from the second bar onward.

ScanLang has real imperative control flow — if, for, and while— for the cases where a declarative expression gets awkward. Every loop is bounded by a step budget of one million total iterations per evaluation, so a program always halts; exceeding the budget is a runtime error rather than a hang.

Control-flow blocks use { } and may contain only var (declare a mutable), := (assign), if, for, and while. The program-level statements — output, guard, detail, anchor, and visual— are not allowed inside a block.

if / else if / else

var trend = "flat"
if close > ema(close, 20) and close > ema(close, 50) {
  trend := "strong_up"
} else if close > ema(close, 50) {
  trend := "weak_up"
} else {
  trend := "down"
}
output trend

Branches chain with else if and an optional final else. Assign into a var declared before the block, then output it at program level once the block has run.

for

for i = 0 to 9 { x := x + close[i] }        // i runs 0..9 inclusive
for i = 9 to 0 by -1 { … }                  // descending; `by step` is optional

The bounds are inclusive on both ends. The optional by stepclause sets the stride — use a negative step to count down. A step of 0 is an error. The loop variable is scoped to the loop and is the natural index into a bar series, so close[i] and open[i] walk the bars as i advances.

while

var i = 0
while i < 10 { i := i + 1 }

A while loop repeats while its condition is truthy. The same step budget applies, so a condition that never becomes false will terminate the evaluation with a runtime error rather than spinning forever.

var alt = true
for i = 0 to 8 {
  if (close[i] > open[i]) == (close[i+1] > open[i+1]) { alt := false }
}
output alt

These declarative statements enrich a result with evidence rows and chart drawings. The moment any of them appears, the indicator stops returning a bare scalar and instead returns an envelope: { value, details, visuals, anchors }. The score is still value; the rest is context for the UI.

detail — an evidence row

A detail attaches a labeled value to the result so a reviewer can see why a ticker scored the way it did.

detail "EMA 8" = fast as price key "ema8"
detail "Spread" = spread as price
detail "Broke out" = close > orh when exists(orh)   // conditional row

Three optional modifiers shape how and whether a row appears:

• as <format> — the display format, such as price, percent, ratio, or number.
• key "<id>"— a stable identifier for the row; defaults to a slug of the label when omitted.
• when <expr>— emit the row only when the condition is truthy, so a row can appear conditionally.

anchor — a named value for visuals

An anchor stores a computed scalar under a name that a visual can later bind to with anchor(name). It is the bridge between a calculation and the drawing that depicts it.

anchor orh = highest(high, 6)

visual — a chart drawing

A visual declares something to draw on the chart. The kind (level, marker, …) follows the visual keyword; an optional when gates it at runtime; and the { } block holds key: value fields whose values are expressions.

visual level when spread > 0.5 {
  value: anchor(orh)
  label: "OR High"
  style: "dashed"
  color: "red"
}

Here the level is only drawn when spread > 0.5, and its value binds back to the orhanchor defined above — so the dashed red line lands exactly at the computed opening-range high.

These are the ONLY callable functions — there are no others, and no way to define your own. Each delegates to a vetted TA.* helper where one exists, guaranteeing parity with the Python indicators.

Signature notation: series = SERIES, num = NUMBER, bars = BARS, any = any type, [num] = optional argument, num... = variadic.

Series transforms (series → series)

Reducers (series → number)

Crossovers (→ bool)

Scalar math (number → number)

Bars & existence

String / state ops (→ state)

Bar fields & constants

Bar fields — each a SERIES aligned to the bars, auto-reducing to its latest value in scalar context: open high low close volume.

Constants (scalar NUMBER): live_close is the current price (live_price → chart_close → close); bar_count is the number of bars passed to the indicator (len(bars)).

ScanLang is statically checked before it runs. The checker reads each function’s signature from the library, so the editor’s hints and the runtime can never drift.

• Lenient on SERIES vs NUMBER. A series used in a scalar position is auto-reduced at runtime, and a function declaring a NUMBER param accepts a series. You rarely fight the type checker over series/number.
• Strict on names, functions, and arity. Unknown identifiers, calls to non-existent functions, and wrong argument counts are compile-time TypeCheckErrors with line/column.
• No shadowing built-ins. let mean = ... errors because mean is a library function.
• Homogeneous select arms. All-string or all-numeric; mixing them is an error.
• Exactly one output is required.

The compiler also produces a CheckResult describing the program: output_type (boolean | number | state), needs_context, required_lookback, the parameter schema, and the derived state_options.

All errors derive from ScanLangError and carry a message, line, col, and stage. There are four stages.

In the editor these surface as real-time inline diagnostics: the source is parsed and type-checked (no evaluation), debounced ~500ms, and returns 1-based line/col positions. A transient failure shows no diagnostics rather than blocking editing.

A ScanLang indicator travels through five stages, from the editor to a score in the scan engine.

• 1. Authoring.A CodeMirror-based editor provides highlighting, palette-driven autocomplete, hover docs, and live linting. All keywords, functions, signatures, and descriptions come from a generated palette kept in sync with the language library — so the UI is always in sync with the language.
• 2. Compilation. compile_source(source) lexes → parses → type-checks → builds a calculate closure plus a CheckResult.
• 3. Arity. The engine calls calculate(bars, params) for daily indicators or calculate(bars, params, context)for context-aware ones — chosen automatically from CheckResult.needs_context.
• 4. Loading & registry. The plugin loader reads .scan files, compiles them, and drops the closure straight into the metric registry. The scan engine needs zero changes to score a ScanLang indicator. A lang discriminator selects ScanLang (.scan) vs legacy Python (.py); the two coexist.
• 5. Result. calculate returns None | bool | number | str, or — when detail/anchor/visual are present — an envelope { value, details, visuals, anchors }.

The handful of behaviours that catch authors off guard. Each is a quick fix once you know the rule.

Six complete programs, each isolating one capability. Copy any of them into the editor and adapt.

Minimal boolean

The shortest valid indicator: a single boolean output.

output close > ema(close, 50)

Parameterised EMA stack with evidence

A tunable EMA stack that emits price-pane details, an anchor, and a conditional visual marker.

timeframe 5m
requires 50 bars
params {
  period = 50 : int(2..400)
}

let eF = ema(close, 8)
let eM = ema(close, 21)
let eS = ema(close, period)
let spread = max(eF, eM, eS) - min(eF, eM, eS)

output (eF > eM and eM > eS)

detail "EMA 8"  = eF as price key "ema8"
detail "EMA 21" = eM as price key "ema21"
detail "EMA 50" = eS as price key "ema50"
detail "Spread" = spread as price

anchor hi = max(eF, eM, eS)
visual level when spread > 0.5 {
  value: anchor(hi)
  label: "High EMA"
  style: "dashed"
}

State output

A select that classifies each bar into one of three named states.

output select {
  close > sma(close, 20) and close > sma(close, 50) -> "above_both"
  close < sma(close, 20) and close < sma(close, 50) -> "below_both"
  default -> "between"
}

Window aggregation

Count how many of the last lookback bars closed above their fast EMA, then gate on volume.

params { lookback = 10 : int(2..100) }
requires lookback bars
let bars_above = count(lookback) { close > ema(close, 8) }
output bars_above >= 7 and volume > mean(volume, 20) * 1.5

Loop-based candle pattern

A for loop that checks the last ten candles strictly alternate green and red.

// Last 10 candles strictly alternate green/red
var alt = true
for i = 0 to 8 {
  if (close[i] > open[i]) == (close[i+1] > open[i+1]) { alt := false }
}
output alt

Multi-timeframe opening-range breakout

A 3-arg context indicator: read the opening 30m range on a higher timeframe, then look for the first session bar to break it.

timeframe 5m
let or_high = on(30m) { highest(high, 1) within session.first(1) }
let bbar = find_first(drop(session.bars, 1)) { close > or_high }
let has_breakout = exists(bbar)

output select {
  has_breakout -> 1.0
  default -> 0.0
}

detail "Opening 30m High" = or_high as price
detail "Breakout Close" = bbar.close as price when has_breakout

Every change to the ScanLang language, its function library, or its editor tooling is recorded here, newest first. Versions follow semantic versioning — a breaking grammar or semantics change bumps the major, a backward-compatible addition bumps the minor, and a fix or clarification bumps the patch.

Existing saved indicators keep scoring identically across patch and minor releases; only a major release can change how a previously valid program behaves.