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 asseries[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:
oncePerBarfires the first time on each bar.oncePerBarClosefires only when the bar is confirmed.everyTimefires on every call, subject tocooldownMsand the rate limit.
Firing alerts
ctx.alert('key'),ctx.alert('key', 'custom text')orctx.alert('key', { message, price, severity, data }).ctx.alert.message(text, opts?)fires an ad-hoc alert with keydefault, once per bar.dataholds 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:
export function midpoint(a: number, b: number): number { return (a + b) / 2;}
// Indicators/MyIndicator.tsimport { midpoint } from '../Libraries/MathUtils';Compiling a library with F5 republishes every indicator that imports it.