Skip to content

Scripted indicators

chartgen can run indicators you write yourself, the way TradingView runs Pine Script. Scripts are written in Starlark, a small, deterministic dialect of Python. You register a script over MCP or write it in the web app’s script editor, and from then on generate_chart accepts its name like any built-in. It is sandboxed: a script cannot read files, use the network or load other code. Design records: ADR-0024 (runtime) and ADR-0025 (registry and MCP tools).

Scripting is off by default. Start the HTTP server with it on:

Terminal window
CHARTGEN_SCRIPTING=1 chartgen --serve
VariableDefaultPurpose
CHARTGEN_SCRIPTINGunset (off)1 lists and serves the scripting tools, and makes generate_chart and list_indicators include your scripts.
CHARTGEN_DB~/.chartgen/chartgen.dbSQLite file for scripts and registered OAuth clients. Created and migrated at startup.

Scripts belong to the OAuth client that registered them, that is, the client_id your MCP client got from /register. Another client, even your own second client, does not see them. With sign-in they belong to the signed-in user instead, from any client, at 50 per user, and scripts from before it stay out of reach until the operator names who inherits them (ADR-0044). The stdio transport (--mcp) has no user: it lists the tools but cannot store scripts, and it charts built-ins only.

PARAMS = [
{"name": "length", "type": "int", "default": 14, "min": 2, "max": 200, "desc": "RSI length"},
{"name": "smooth", "type": "int", "default": 5, "min": 1, "max": 50, "desc": "Signal EMA"},
{"name": "ob", "type": "float", "default": 70.0, "desc": "Overbought"},
{"name": "os", "type": "float", "default": 30.0, "desc": "Oversold"},
]
META = {"title": "RSI + signal", "overlay": False, "description": "RSI with an EMA signal and band crosses"}
def compute(ohlcv, params, chart):
r = ta.rsi(ohlcv.close, params["length"])
sig = ta.ema(r, params["smooth"])
chart.line(r, title = "RSI", color = "purple")
chart.line(sig, title = "Signal", color = "orange", width = 1)
chart.fill(r, sig, color = "green", color_below = "red", alpha = 0.15)
chart.dot(ta.crossover(r, params["os"]), r, color = "lime", size = 5, label = "rsi_oversold_exit")
chart.dot(ta.crossunder(r, params["ob"]), r, color = "red", size = 5, label = "rsi_overbought_exit")
chart.hline(params["ob"], color = "gray")
chart.hline(params["os"], color = "gray")
chart.set_y_range(0, 100)

Register it, then chart it next to built-ins and override its params like any other indicator:

{ "name": "register_indicator", "arguments": { "name": "rsi_bands", "source": "PARAMS = [...]..." } }
{ "name": "generate_chart", "arguments": {
"ticker": "BTCUSDT", "format": "series",
"indicators": [{ "name": "rsi_bands", "length": 21 }, "macd"] } }

register_indicator answers with the normalised parameter schema:

{
"ok": true, "name": "rsi_bands", "title": "RSI + signal", "overlay": false,
"replaced": false, "shadows_builtin": false,
"configurable_params": [
{ "name": "length", "type": "integer", "default": 14, "min": 2, "max": 200, "description": "RSI length" },
...
]
}

A script defines three things at the top level:

  • PARAMS: a list of parameter specs. Each entry has name, type (int, float, bool or string), a default of that type, and optional min, max, desc, and options (a list of allowed strings, for string params). Chart requests are validated against it, like the built-ins’ parameters. Use PARAMS = [] for none. A param cannot be called name, id, hidden or style: those are keys of an indicator entry on the wire and in the web app (ADR-0028).
  • META: a dict with title (the panel label, default: the name), overlay (True draws on the price chart, default False) or category ("overlay" / "panel"), and an optional description.
  • def compute(ohlcv, params, chart): draws the indicator and returns nothing. params is a dict of the resolved values: request overrides over defaults, with float params always floats.

Module-level constants and helper defs are allowed. A top-level name must not shadow a builtin (ta, len, range, …).

Every price input and every ta.* result is a series: one float per bar, aligned with the chart bars. nan is Pine’s na (warmup, division by zero).

ExpressionMeaning
ohlcv.open .high .low .close .volumePrice series
ohlcv.timeBar open time, unix seconds (nan for the synthetic demo data)
ohlcv.hl2 .hlc3 .ohlc4 .hlcc4Composite price sources
a + b, a - b, a * b, a / b, -aElement-wise; either side may be a number (1 - close, 100 / close). x / 0 is nan.
close[1], close[k]The series k bars ago, as in Pine (nan for the first k bars)
a > b, <, >=, <=, ==, !=A bool series (1.0 / 0.0). A comparison with nan is false, as in Pine.
c1 & c2, c1 | c2, c1 ^ c2, ~cElement-wise and / or / xor / not on bool series
len(s)Number of bars
s.get(i)The value at bar i as a float (negative counts from the end)
s.list()All values as a list of floats, for per-bar loops
ta.series([...])A series from a list of numbers (None is nan)

and, or, not and if work on plain values only: a series is always truthy, so if close > open: does not test each bar. Use a bool series with chart.dot(cond, ...), or loop over .list():

def compute(ohlcv, params, chart):
out = []
streak = 0
closes = ohlcv.close.list()
for i in range(len(closes)):
if i > 0 and closes[i] > closes[i - 1]:
streak += 1
else:
streak = 0
out.append(streak)
chart.bars(ta.series(out), color = "teal")

Loops run in the interpreter and are slower than ta.*, which is native, vectorized code. Prefer series math where you can.

They use the same Pine v5 code as the built-ins (ADR-0018): SMA-seeded EMA/RMA, warmup nan, and windows that skip nan. Lengths must be between 1 and 10 000.

FunctionPineNotes
ta.sma(src, length)ta.sma
ta.ema(src, length)ta.emaSeeded with the SMA of the first length values
ta.wma(src, length)ta.wma
ta.rma(src, length)ta.rmaWilder’s smoothing
ta.rsi(src, length)ta.rsi
ta.stoch(src, high, low, length)ta.stochZero range is nan
ta.tr(ohlcv)ta.tr(true)True range of the chart bars
ta.atr(ohlcv, length)ta.atr
ta.macd(src, fast=12, slow=26, signal=9)ta.macdReturns (macd, signal, hist)
ta.highest(src, length), ta.lowest(src, length)ta.highest, ta.lowest
ta.stdev(src, length)ta.stdevPopulation (biased)
ta.change(src, length=1)ta.changesrc - src[length]
ta.roc(src, length)ta.rocPercent
ta.crossover(a, b), ta.crossunder(a, b)ta.crossover, ta.crossunderBool series; b may be a number
ta.pivot_high(src, left, right), ta.pivot_low(...)ta.pivothigh, ta.pivotlowValue on the confirming bar, nan elsewhere. Tie rule unverified against TradingView.
ta.nz(src, replacement=0), ta.na(src), ta.fixnan(src)nz, na, fixnan
ta.add/sub/mul/div(a, b) and *_scalar—Function forms of the operators
ta.max(a, b), ta.min(a, b), ta.pow(a, b)math.max, math.min, math.pownan if either side is nan
ta.abs(x), ta.sqrt(x), ta.log(x), ta.exp(x)math.*Work on series and numbers
ta.hl2(ohlcv), ta.hlc3(ohlcv), ta.ohlc4(ohlcv)—Same as ohlcv.hlc3 etc.
ta.nannaA float nan

Each method adds one element to the indicator’s output (the same PanelResult the built-ins produce), so PNG, summary and series all show it. Series arguments may also be plain numbers (a constant line).

MethodDraws
chart.line(s, title="", color="#2962ff", width=2, alpha=0.9)A line
chart.fill(a, b, color="#2962ff", alpha=0.2, color_below=None)A shaded band; color_below applies where a < b
chart.bars(s, color="#26a69a", colors=None, alpha=0.9, bottom=0.0)A histogram; colors is one color per bar
chart.dot(x, y, color="#2962ff", size=4, label=None, alpha=1.0)A dot at bar x (int) and value y, or, with x a bool series, a dot on every true bar at y (series or number). label is a signal name.
chart.hline(y, color="#787b86", alpha=0.5)A horizontal reference line
chart.hbar(y, height, width, offset=0.0, color="#2962ff", alpha=0.5, left=False)A horizontal bar at a price (volume-profile style); width and offset are fractions of the chart width
chart.divline(x1, y1, x2, y2, color="#787b86", alpha=0.9, dashed=False)A straight segment between two bars
chart.set_y_range(lo, hi)Fixed y-axis range
chart.set_label(text)Panel label (default META["title"])

Colors are "#rrggbb", "#rrggbbaa" (its alpha overrides alpha) or a Pine color name: aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, orange, purple, red, silver, teal, white, yellow.

fork_indicator returns the Starlark source of a built-in that has a reference implementation. Edit it and register it. Keep the built-in’s name to replace it for your account only (other users still get the built-in), or pick a new name.

{ "name": "fork_indicator", "arguments": { "builtin_name": "wavetrend" } }
→ { "name": "wavetrend", "source": "PARAMS = [...] ...", "configurable_params": [...] }

Forkable today: wavetrend. Its source, src/scripting/refimpl/wavetrend.star, is tested to match the Rust indicator within 1e-9. It is a good example of Pine-style series code:

ap = ohlcv.hlc3
esa = ta.ema(ap, params["ch_len"])
d = ta.ema(ta.abs(ap - esa), params["ch_len"])
ci = (ap - esa) / (0.015 * d)
wt1 = ta.ema(ci, params["avg_len"])
wt2 = ta.sma(wt1, 3)
up = (wt1[1] < wt2[1]) & (wt1 >= wt2)
chart.dot(up & (wt2 <= -53), wt2, color = "#3fff00", size = 6, label = "cross_up_os")

register_indicator checks a script in four steps and stops at the first failure. The error comes back with isError: true:

{ "ok": false, "errors": [{ "step": "dry_run", "line": 4, "message": "..." }] }
stepChecks
parseSyntax; source size (64 KiB)
staticNo load(); no shadowed builtins; no banned methods; every name defined; the top level runs
presencePARAMS, META and compute exist and are well-formed
dry_runcompute runs on 100 synthetic bars, with defaults, within 200 ms

A script that passes registration can still fail on a real chart, for example on more bars or other params. Then only that indicator fails: it is left out of indicators, the rest of the chart renders, and the response carries indicator_errors: {"<name>": {"step": "runtime", "line": 7, "message": "..."}}.

For an authenticated client with scripting on, two more cases fail only their indicator, with line: null: a name that is neither your script nor a built-in ("step": "unknown": it may be a script deleted since, or saved under an earlier client), and params your script no longer accepts ("step": "params"). Bad params of a built-in still fail the whole request, and so does an unknown name on the stdio server or with scripting off.

A chart that uses your scripts is never pushed: subscribe_chart answers not pushable, and clients poll generate_chart, which runs your scripts. See the MCP reference.

Each compute call runs under these limits; a detected violation returns an indicator error. Limits are best effort, not a guarantee against crashes (see ADR-0024):

LimitValue
Wall clock1 s per chart request, shared by all its scripts (200 ms for the register dry run)
Scripted indicators per chart3
Steps (function calls + loop iterations)20 million
Call depth (recursion)64
Script heap64 MiB
Memory held by one evaluation (heap, dicts, series, strings)256 MiB
One string, list, tuple, dict or range20 000 elements
A seriesexactly one value per bar (ta.series included)
Integers64-bit; overflow and larger literals are errors
Top-level values (module constants)1 MiB
Concurrent evaluations4 on the server, 1 per user (others wait, then “server busy”)
Plot objects64 lines, fills, bar series or hlines; 10 000 dots, hbars or divlines
Scripts per user50; names ^[a-z][a-z0-9_]{0,47}$

Not available: load, print, file or network access, getattr, and the methods .join, .format, .replace, .extend, .update and .setdefault, whose output can outgrow their input many times over in one step. Build strings with + or %, lists with + or .append, and dicts with d[k] = v. Augmented assignment (+= etc.) needs a plain name: write x[i] = x[i] + 1, and assign list or dict items one at a time.

if, and, or, not, x if c else y and comprehension filters are rejected when applied directly to a series (if ohlcv.close > ohlcv.open:), because a series is always truthy. The check only sees expressions it can recognise as series; one stored in a variable first is not detected.

The limits make runaway scripts fail cleanly. They are not a security boundary against deliberately hostile code (ADR-0024), so even a trusted deployment should run chartgen under an OS memory limit (cgroup MemoryMax, a container limit).

ToolDoes
register_indicator(name, source)Validate and store, or replace a script with the same name
list_my_indicators()Your scripts with params and timestamps
get_my_indicator(name)The stored source of one of your scripts
delete_indicator(name)Remove one; a built-in it shadowed is visible again
fork_indicator(builtin_name)The source of a forkable built-in

list_indicators lists your scripts next to the built-ins, tagged "source": "user".