Filters & Signals

A Filters & Signals script marks the backtesting timeline. It declares named outputs of two kinds — and one script may host both:

• Signal — a moment in time: "this just happened" (a breakout, a session open). The output is the list of timestamps where it fired, rendered as markers on a timeline track.
• Filter — a boolean condition over time: "is this true right now?" (in-session, above the moving average). The output is the time ranges where it was true, rendered as shaded ranges on a timeline track.

Use them to jump straight to the interesting places while backtesting manually, and as building blocks a Strategy script references.

Shape and lifecycle

A script is a TypeScript class, default-exported. No base class, no imports of external packages. State lives in instance fields.

export default class implements Script {
  private ema = 0; private k = 0;

  onInit(ctx: InitContext) {              // once, before any market data
    this.k = 2 / (ctx.inputs.emaLen + 1);
  }

  onUpdate(ctx: Context) {                // every market update, in time order
    this.ema += this.k * (ctx.bid - this.ema);
    ctx.filters.aboveEma.set(ctx.bid > this.ema);
    if (ctx.isNewBar && ctx.bid > this.ema) ctx.signals.crossUp.raise();
  }

  onFinish?(ctx: Context) { /* optional — rarely needed */ }
}

• onInit(ctx) — runs once before the data feed. Gets inputs, timers, and deps — no market data yet. Subscribe timers and configure dependencies here.
• onUpdate(ctx) — called for every market update, in time order; must not be async. It sees bid and ask, finer than bars. Optional if a timer is subscribed in onInit — one of the two is required.
• onFinish(ctx) — optional, once after the last update.

The ctx you get each update

The forming-bar trap

Signals

ctx.signals.<name>.raise() — no arguments; the event timestamp is ctx.time. Raise as often as the logic demands; each raise is one marker on the track.

Filters

ctx.filters.<name>.set(active):

• Call cadence is free — set every update or only on change; not calling carries the previous value forward. The engine turns consecutive values into clean time ranges.
• prevValue: boolean | null — the carried value; null only before the first set.

Timers — logic across data gaps

Market data has gaps — forex weekends mean no updates from Friday close to Sunday open, so a tick-driven filter cannot close a session at the Friday close. Timers fix this:

onInit(ctx: InitContext) {
  ctx.timers.every(60 * 60 * 1000, (c) => {       // hourly, epoch-aligned marks
    c.filters.inSession.set(isSessionHour(c.time));
  });
}

• ctx.timers.every(intervalMs, cb) — the callback fires at every aligned mark, even inside data gaps (delivered in correct time order), plus once at the range start. c.time is the mark; price and bar fields reflect the last real update. Returns a handle with .stop().
• ctx.timers.at(timestamp, cb) — one-shot: fires once at timestamp (ms). A past timestamp fires at the next opportunity. Same handle with .stop().

Use timers for session and calendar boundaries; use onUpdate for price logic.

metadata.json

The metadata that matches the class above:

{
  "name": "EMA Trend", "shortName": "EMAT",
  "historyBars": 50,
  "inputs": {
    "emaLen": { "type": "int", "default": 20, "min": 1, "max": 500, "name": "EMA Length" }
  },
  "signals": {
    "crossUp": { "name": "Cross Up", "color": "#26a69a", "description": "Bid crossed above EMA" }
  },
  "filters": {
    "aboveEma": { "name": "Above EMA", "color": "#787b86" }
  }
}

• At least one output (signals and/or filters) is required — see how the kind is derived.
• Input types: int / float (optional min/max/step) / bool / enum (the default must be one of the options). Keys must be identifiers — they become ctx.inputs.<key>.
• inputGroups — presentation-only sections for the parameters form; a group key on an input refers to a group. Never affects behavior.
• historyBars — closed bars preloaded before the range start (so lookbacks are warm at the first update) and the depth of ctx.bars. This sets your request; the run loads the deepest requirement across the script and its dependencies, so ctx.bars may reach further back. Default 0.

Referencing indicators and other scripts

A Filters & Signals script may declare dependencies in metadata (alias → pinned script) and consume them via ctx.deps.<alias> — most usefully indicators: read ctx.deps.myRsi.plots.rsi each update, recomputed exactly as on the chart. Configure with .setParams({...}) in onInit. Dependency versions freeze at save — pinning and Update to vN are covered in Scripts explained. A dependency can never be a strategy. The full consumer API lives on the Strategy scripts page — it's the same mechanism.

Saving and diagnostics

Save type-checks the code against the metadata-generated API and returns precise line/column diagnostics — see Scripts explained for drafts, versions, and the full save lifecycle.

Limits and where results go

• Each output records at most 10,000 items per run (signal events or filter flips). Hitting the cap stops recording for that output and flags it as truncated — the run still succeeds. A signal firing 10,000+ times usually means the condition is too loose to be a useful marker.
• Runs count against your daily compute time. Compiles on save never count.
• Results are deterministic — same version, parameters, and range, same result.

To see the output, open the timeline's Filters & Signals window (the + button) and pick your script — its markers and shaded ranges render over the backtesting timeline, are remembered in this browser (see Timeline), and recompute when the range or instrument changes.