What is Candle Script?

Who should use it?

Use Candle Script for custom indicators, alert conditions, strategy experiments, or chart visualizations that execute against CandleScript.io market bars. New users can start with the moving-average tutorial; experienced developers can use collections, multi-timeframe context, drawing primitives, and the scripts API.

Start with the moving-average crossover tutorial or browse the language reference.

How it works

Scripts run on a stream engine: you write logic for the current bar and the runtime evaluates it once per candle, oldest to newest. Read OHLCV with open, high, low, close, and volume; use composite sources such as hl2, hlc3, ohlc4, and hlcc4; access history with close@1; and emit lines with paint("Name", value).

Try it live in the Workstation Script Lab, or open a saved script from the scripts panel.

Hello world

const fast = avg.simple(close, 10);
const slow = avg.simple(close, 30);

paint("Fast", fast);
paint("Slow", slow);

Inputs

Declare settings with input.*. The platform automatically builds the Inputs tab in script settings from input.int, input.bool, input.select, input.source, and other declarations.

const length = input.int("Length", 20, 2, 200);
const source = input.source("Price source", "hl2");

const basis = avg.simple(source, length);
paint("Basis", basis);

Chart output

paint("Momentum", close - close@1);
paint.style("Momentum", "histogram", "#22c55e", 2, "separate");
paint.candleColor("Trend candle", close > close@1, "#22c55e", "#16a34a");

const dashboard = draw.table("top_right", 2, 2);
draw.setTableCell(dashboard, 0, 0, "Trend");
draw.setTableCell(dashboard, 0, 1, close > avg.simple(close, 20) ? "Bull" : "Bear");

Strategies & backtests

Use trade.* for paper strategies. Market, limit, stop, stop-limit, cancellation, partial exits, per-entry sizing, and script-side introspection are supported. Backtest options include quantity mode and value, long/short margin, pyramiding, and reversal controls. Run backtests from Script Lab or through POST /v1/backtests/run.

const basis = avg.simple(close, 20);

trade.enter("long", signal.crossOver(close, basis), close * 0.98, close * 1.04);
trade.entryStopLimit("long", close > basis, close + 1, close, close * 0.98, close * 1.04, 25);
trade.cancel("long", close < basis);
trade.exit("long", signal.crossUnder(close, basis), 50);

paint("Open intents", trade.openTrades("long"));

Multi-timeframe context

Read aligned higher-timeframe data with context.atResolution, evaluate higher-timeframe expressions with context.security, and inspect lower-timeframe intrabar values with context.lower. Alignment modes are gaps_off, gaps_on, and lookahead_on.

paint("HTF close", context.atResolution(close, 60, "gaps_off"));
paint("HTF SMA", context.security(60, avg.simple(close, 20), "gaps_on"));

const intrabarCloses = context.lower(1, close);
paint("Intrabar count", array.size(intrabarCloses));

Custom values and collections

Candle Script supports record literals, custom type constructors with defaults, receiver-style helper calls, object arrays, string-keyed map.* containers, and bounded matrix.* grids for structured models and dashboards.

type Zone { top: high, bottom: low }

fn span(self) {
  self.top - self.bottom;
}

const zone = Zone(high, low);
const zones = map.new();
map.set(zones, "active", zone);

const grid = matrix.new(2, 2, 0);
matrix.set(grid, 0, 1, zone.span());

paint("Zone span", map.get(zones, "active").span());
paint("Grid cell", matrix.get(grid, 0, 1));

Bars, time, and sessions

Bar helpers expose index, count, time, and confirmation state. Time helpers support UTC offsets, daily and named market sessions, common kill zones, and timeframe conversion.

const regular = time.inNamedSession(bar.time(), "regular", -300);
const nyKillZone = time.inKillZone(bar.time(), "newyork", -300);

paint("Regular", regular ? 1 : 0);
paint("NY kill zone", nyKillZone ? 1 : 0);
paint("Minutes", time.timeframeMinutes("1H"));
paint("Last confirmed", bar.isLastConfirmedHistory() ? 1 : 0);

Standard library

Functions live in original namespaces, never Pine's ta.* namespace:

• avg.* — simple, weighted, exponential, and volume-weighted averages
• band.* — highest, lowest, deviation, true range, and average true range
• momentum.* — MACD, stochastic, RSI, change, and rate
• signal.* — crossOver, crossUnder, and crosses
• array.*, map.*, matrix.* — bounded collections
• context.* — higher- and lower-timeframe reads and expression evaluation
• draw.*, paint.* — visual objects, tables, plot metadata, and candle colors
• bar.*, time.*, num.*, filter.*

The editor offers autocomplete and signature help. Browse every signature in the language reference, or list all built-ins with POST /v1/scripts/diagnostics in the REST API.

Coming from Pine Script?

TradingView's Pine Script documentation is helpful for ideas such as indicators and bar semantics, not syntax. Translate manually:

// Pine (NOT valid Candle Script):
// plot(ta.sma(close, 20))
// x = close[1]

// Candle Script:
paint("SMA 20", avg.simple(close, 20));
const previous = close@1;

Do not use plot, bracket lookbacks such as close[1], version directives, or indicator() headers; they fail with diagnostic AS1005.

Next steps

• Open IDEAL BB with MA in Script Lab, a full indicator with inputs, fills, and alerts.
• Look up every signature in the Candle Script language reference, generated from the standard-library registry.
• Compile and run through the REST API Scripts endpoints.