Skip to content

SDK reference

This page documents the @tickmint/sdk module that every MintScript imports. It is based on the declaration file the Script Editor type-checks against (packages/script-sdk/generated/tickmint-sdk.d.ts), which also powers the editor’s SDK panel.

import { defineIndicator, input, plot, alert, theme, color, math, na, isNa, nz } from '@tickmint/sdk';

defineIndicator

A script’s default export is the result of defineIndicator(def).

export default defineIndicator({
id: 'tm_myindicator_x1y2z3',
name: 'My Indicator',
overlay: true,
inputs: { /* input.* builders */ },
plots: { /* plot.* builders */ },
onBarUpdate(ctx) { /* runs per bar */ }
});
Field Type Default Notes
id string required Stable id, a string literal starting with tm_. Charts store it, so don’t change it.
name string required Name shown in the Indicators dialog and the legend.
shortName string Compact legend label.
description string
apiVersion 1 1 SDK major version the script targets.
overlay boolean true true draws on the price pane; false draws in its own sub-panel.
calculate 'onBarClose' · 'onEachTick' · 'onPriceChange' 'onBarClose' When onBarUpdate runs for the newest bar. See below.
inputs object User settings. See Inputs.
plots object Output series. See Plots.
scale { min?, max? } auto Sub-panel vertical bounds.
levels Level[] Horizontal reference lines, e.g. { value: 70, style: 'dashed' }.
requires { footprint?: boolean } Set footprint: true to get per-price detail from ctx.orderflow.footprint().
alerts object Declared alerts. See Alerts.
setup(ctx) function Runs once after inputs are known, before the first bar. ctx has inputs, symbol and log.
onBarUpdate(ctx) function required Runs for every bar. See The bar context.

Calculate modes

Mode Behaviour for the newest bar
onBarClose Once per bar, after it closes. The forming bar is not calculated.
onEachTick On every update of the forming bar.
onPriceChange On updates that change the forming bar’s close.

Series

Prices and calculation results are series indexed by bars ago:

  • ctx.close[0] is the bar being calculated.
  • ctx.close[1] is the previous bar.
  • series.get(n) is the same as series[n].

Reading before the first bar, or a bar without a value, returns NaN. Test for it with isNa() or replace it with nz().

Inputs

Inputs appear in the indicator’s settings dialog. Their values arrive in ctx.inputs with full typing.

Builder Value in ctx.inputs Options
input.int(default, opts?) number (rounded) min, max, step
input.float(default, opts?) number min, max, step
input.bool(default, opts?) boolean
input.string(default, opts?) string
input.color(default, opts?) string Hex, rgba or a theme.* token.
input.source(default?, opts?) Series Source names are listed below.
input.select(default, options, opts?) string options is a list of values or { value, label } objects.

Every input also accepts label (defaults to the key), tooltip (help text) and group (settings heading).

Source names: open, high, low, close, volume, hl2, hlc3, ohlc4, delta, buyVolume, sellVolume.

inputs: {
length: input.int(20, { min: 1, max: 500, label: 'Length' }),
source: input.source('close'),
mode: input.select('ema', [{ value: 'ema', label: 'EMA' }, { value: 'sma', label: 'SMA' }], { group: 'Smoothing' })
}

Plots

Builder Draws
plot.line(opts?) Line
plot.step(opts?) Step line
plot.histogram(opts?) Histogram from the baseline (default 0)
plot.area(opts?) Filled area
plot.columns(opts?) Columns from the baseline (default 0)
plot.dots(opts?) Dots
plot.cross(opts?) Crosses
plot.band({ upper, lower, fill?, label? }) Fill between two other plots, given by key. You don’t set it per bar.

Plot options: color, width, style ('solid', 'dashed' or 'dotted'), label, baseline, and axisLabel (shows the last value on the price axis; default true).

Set a value each bar with ctx.plot.<key>(value, color?). Passing null or NaN leaves a gap. The optional color colors that bar only.

plots: {
upper: plot.line({ color: theme.neutral }),
lower: plot.line({ color: theme.neutral }),
fill: plot.band({ upper: 'upper', lower: 'lower', fill: color.withAlpha(theme.accent, 0.1) })
}

The bar context (ctx)

Member Description
ctx.inputs Input values. Source inputs are series.
ctx.plot.<key>(v, color?) Sets a plot value for the current bar.
ctx.open, high, low, close, volume Price series.
ctx.hl2, hlc3, ohlc4 Derived price series.
ctx.time Bar open time in Unix ms, as a series.
ctx.barIndex / ctx.barCount Index of the current bar (0 = oldest loaded) and the number of loaded bars.
ctx.isLastBar / ctx.isConfirmed isLastBar is true for the newest bar. isConfirmed is false only for the forming last bar.
ctx.symbol { symbol, tickSize, pointValue }
ctx.session isNewSession (first bar after 17:00 America/Chicago), isRth (bar opens 08:30–15:00 CT), key (trading day YYYY-MM-DD).
ctx.ta Technical analysis functions. See ctx.ta.
ctx.draw Tag-based drawing. See ctx.draw.
ctx.orderflow Delta and volume data. See ctx.orderflow.
ctx.alert Raises alerts. See Alerts.
ctx.var(name, initial) Returns a persistent value: read and write .value. It carries over from the previous bar and is rolled back when a bar is recalculated, so keep values primitive.
ctx.series(name) Returns a series you write with .set(v). You can feed it to ctx.ta.*.
ctx.plotSeries(key) One of your own plots, read as a series.
ctx.bgcolor(color | null) Sets the background color of the current bar.
ctx.indicator(id, inputs?) Another published indicator by its literal id. Read its output with .plot(name), which returns a series. Nesting is limited to 8 levels.
ctx.log(...args) Writes to the editor’s Output tab.

ctx.ta

Each call is cached by function, source and parameters. Call them on every bar with the same arguments: changing length creates a new series. Results match TickMint’s built-in indicators. EMA seeds with the first value, and RSI and ATR use an expanding average before Wilder smoothing.

Function Returns
sma(src, len), ema(src, len), wma(src, len) Series
rma(src, len) Wilder’s moving average (RMA/SMMA)
stdev(src, len) Population standard deviation
highest(src, len), lowest(src, len), sum(src, len) Series
cum(src) Cumulative sum since the first bar
change(src, len = 1) src[0] - src[len]
roc(src, len) Rate of change in percent
tr(), atr(len) True range, average true range
rsi(src, len) Series
macd(src, fast?, slow?, signal?) { macd, signal, hist }
bb(src, len?, mult?) { upper, middle, lower }: SMA ± mult × stdev
vwap(src?) Session-anchored VWAP (session starts 17:00 CT)
crossover(a, b), crossunder(a, b) boolean. a and b can be series or numbers.
rising(src, len), falling(src, len) boolean
barsSince(name, condition) Bars since condition was last true (NaN if never)

ctx.draw

Drawing is tag-based: drawing again with the same tag replaces the object. Objects stay until you remove them, and drawings from recalculated bars are rolled back automatically. Each instance can have up to 5000 objects; the oldest are evicted first.

An anchor is { price } plus exactly one of bar (absolute index), barsAgo or time (ms).

Method Key options
line(tag, { from, to, color?, width?, style?, extend? }) extend: 'none', 'left', 'right' or 'both'
hline(tag, { price, color?, width?, style?, label? })
vline(tag, { bar | barsAgo | time, color?, width?, style? })
rect(tag, { from, to, fill?, border?, width? })
text(tag, { at, text, color?, size?, align?, baseline?, background? }) Default size 11 px
marker(tag, { at, shape, color?, size?, text?, position? }) Shapes: arrowUp, arrowDown, triangleUp, triangleDown, circle, square, diamond. position: 'above', 'below' or 'at'.
remove(tag) / clear() Removes one object, or everything this script drew.
if (ctx.ta.crossover(ctx.close, ctx.ta.vwap())) {
ctx.draw.marker(`x${ctx.barIndex}`, { at: { barsAgo: 0, price: ctx.low[0] }, shape: 'triangleUp', color: theme.bull, position: 'below' });
}

ctx.orderflow

Member Description
available false when the chart’s bars carry no order-flow data. All the series below then read NaN.
delta, buyVolume, sellVolume Per-bar series
minDelta, maxDelta Intrabar delta extremes
pocPrice, trades Bar point of control and trade count
footprint(barsAgo?) { tickSize, baseTick, bid[], ask[], trades[] } or null. Row i is at price (baseTick + i) * tickSize. bid is aggressive sell volume and ask is aggressive buy volume. Needs requires: { footprint: true }.

Cumulative delta that resets each session (from Examples/ExampleCVD.ts):

import { defineIndicator, input, plot, theme } from '@tickmint/sdk';
export default defineIndicator({
id: 'tm_example_cvd',
name: 'Example: Cumulative Delta',
overlay: false,
calculate: 'onEachTick',
levels: [{ value: 0, color: theme.grid }],
inputs: { resetEachSession: input.bool(true, { label: 'Reset each session' }) },
plots: { cvd: plot.columns({ color: theme.neutral }) },
onBarUpdate(ctx) {
if (!ctx.orderflow.available) return;
const total = ctx.var('cvd', 0);
if (ctx.inputs.resetEachSession && ctx.session.isNewSession) total.value = 0;
total.value += ctx.orderflow.delta[0] || 0;
ctx.plot.cvd(total.value, total.value >= 0 ? theme.bull : theme.bear);
}
});

Alerts

Declare alerts with alert.define() so that users can enable and configure them in the indicator settings under Alerts. Fire them with ctx.alert.

import { alert, defineIndicator, input, plot, theme } from '@tickmint/sdk';
export default defineIndicator({
id: 'tm_emax_ab12cd',
name: 'EMA Cross',
overlay: true,
inputs: { fast: input.int(9), slow: input.int(21) },
plots: { fast: plot.line({ color: theme.bull }), slow: plot.line({ color: theme.bear }) },
alerts: {
crossUp: alert.define({
label: 'Fast crosses above slow',
message: '{{symbol}} cross UP at {{price}}',
frequency: 'oncePerBarClose',
severity: 'warning',
sound: 'up'
})
},
onBarUpdate(ctx) {
const fast = ctx.ta.ema(ctx.close, ctx.inputs.fast);
const slow = ctx.ta.ema(ctx.close, ctx.inputs.slow);
ctx.plot.fast(fast[0]);
ctx.plot.slow(slow[0]);
if (ctx.ta.crossover(fast, slow)) ctx.alert('crossUp', { data: { fast: fast[0], slow: slow[0] } });
}
});

alert.define options

Option Values Default
label string The alert key
description string
message Template string with placeholders
severity 'info', 'warning', 'critical' 'info'
frequency 'oncePerBar', 'oncePerBarClose', 'everyTime' 'oncePerBar'
cooldownMs number 0
sound 'default', 'chime', 'bell', 'alarm', 'up', 'down', 'none'
enabled boolean true

The frequencies work like this:

  • oncePerBar fires the first time on each bar.
  • oncePerBarClose fires only when the bar is confirmed.
  • everyTime fires on every call, subject to cooldownMs and the rate limit.

Firing alerts

  • ctx.alert('key'), ctx.alert('key', 'custom text') or ctx.alert('key', { message, price, severity, data }).
  • ctx.alert.message(text, opts?) fires an ad-hoc alert with key default, once per bar.
  • data holds primitive values only, up to 2 KB as JSON. It is forwarded to webhooks.
  • Placeholders: {{symbol}}, {{price}}, {{open}}, {{high}}, {{low}}, {{close}}, {{volume}}, {{time}}, {{indicator}}, {{key}}.

Helpers

Export Description
theme.bull, bear, accent, text, textMuted, grid, background, neutral, warning Theme tokens. They resolve to the user’s current chart theme when drawn.
color.rgba(r, g, b, a?) Builds an rgba string.
color.withAlpha(color, alpha) Applies an alpha from 0 to 1 to a hex color, rgb color or theme token.
color.gradient(value, min, max, from, to) Linear blend between two hex colors.
math.clamp(v, min, max), math.round(v, decimals?), math.roundToTick(price, tickSize), math.avg(...values)
na Missing value (NaN).
isNa(v) True for null, undefined or NaN.
nz(v, replacement = 0) Returns the value, or replacement when it’s missing.

Libraries

Put shared code in Libraries/. Library files don’t call defineIndicator. Import them with a relative path:

Libraries/MathUtils.ts
export function midpoint(a: number, b: number): number {
return (a + b) / 2;
}
// Indicators/MyIndicator.ts
import { midpoint } from '../Libraries/MathUtils';

Compiling a library with F5 republishes every indicator that imports it.