Script hooks and trigger lines

A T0 script can be started by the terminal itself, not only by you pressing Run: hooks run a script when something happens (the terminal starts, a symbol changes, an order fills …), and trigger lines are two drawings that run a script when the market crosses them. Both read what happened with event.current() (host API 0.1.5, event 0.1.0; host-api.md §5.7).

requires "event" ">=0.1.0, <0.2.0";

fn main() {
    let e = event.current();
    print(e.kind);                 // "symbol_changed"
    for line in e.data { print(line); }   // "from=BTCUSDT", "to=ETHUSDT", "chart=0"
}

Examples: examples/24–28.

Script Hooks window#

Open it from the command palette (Open Script Hooks), or from the T0 Editor's View ▸ Script Hooks…. Events are listed by category; under each one, + Add script opens the script browser (it lists control programs, .tzc, and plain .tz files, from your scripts folder or from the whole machine) and attaches the file. + Add webhook attaches a built-in post instead (below). Each attached script has:

• an on/off switch;
• Symbol starts with — only events about a symbol with that prefix (BTC matches BTCUSDT);
• Runs in — Live, Replay or Both (Live by default);
• May: — the permissions it runs with (below), none by default;
• Run now — runs it once with a manual event;
• the result of its last run, and how many times it was skipped.

The Log tab keeps the last 200 runs with what each printed. The table is saved in ~/.config/ttt/t0/hooks.json; the script file is read every time it runs, so editing it takes effect at once.

Events#

kind	when	data
app_start	the first frame after the terminal starts	version
app_exit	the terminal closes (it gets up to 3 s; it cannot change the workspace)	—
symbol_changed	a chart shows another symbol	from, to, chart
timeframe_changed	a chart changes timeframe	from, to, chart
chart_opened / chart_closed	a chart appears / goes	chart, symbol
feed_connected / feed_disconnected	the live feed comes or goes	reason
replay_started / replay_stopped	an instrument's replay starts / ends	— (the symbol is the event's)
order_filled / order_rejected / order_cancelled	orders of the Demo or Live account (grouped as the sounds are)	side, count, leg (entry, stop_loss, take_profit), account
price_alert_fired	a price alert fires	level, from (below, above, at)
flow_alert_fired	a market-flow alert fires	name, headline
workspace_loaded	a saved workspace is loaded	name
timer	every N seconds (5 at least; set per hook)	every_s
drawing_trigger	a trigger line fires (not in the table: the line has its own script)	drawing, level, direction
strategy_signal	a strategy running live gives a signal (an order, a stop, or a notice of its own: Act.Notify)	strategy, signal, detail; the symbol and price are the event's
playbook_changed	a playbook's manager changed who is on	playbook, state, from_state, why, on, off, risk, portfolio, cause (decision or fault); the symbol and price are the event's
indicator_signal	a custom indicator (.tzi) gives a signal	indicator, signal, value, why; the symbol and price are the event's
script_run	another script started this one with script.run (not in the table: it is the script's own start)	caller, depth, and the words passed
manual	Run now	—

event.symbol, event.timeframe and event.price are set when the event has them.

Webhooks and indicators#

A hook can be a webhook instead of a script: a kind (Discord, Telegram, JSON), an address and a message template ({event}, {symbol}, {timeframe}, {price}, {time} and the name of any key=value the event carries; a name the event lacks is left as written, so a typo shows), with an optional source filter (only the indicator or strategy with that name). It goes through the same guards as alert.webhook -- https only, no private addresses, one message a second and 20 a minute per address, 1900 characters -- and five failures switch it off. It is the way to be told when a strategy running live signals without writing a script.

The Indicators tab keeps the custom indicators (.tzi, at most 8): each is looked at about once a second on the market in hand, and its signals become indicator_signal. Its line (Output.values, one number for each of the last closed candles) is also drawn on the charts of the instrument and timeframe it reads, as a drawing of its own that every look replaces (switch it off per indicator with Draw its line on the charts; it comes off the charts when the indicator is switched off or removed). They are saved in ~/.config/ttt/t0/indicators.json.

Each card has a Settings button: the dialog where the indicator's parameters are adjusted with controls (// @param comments in the script give the labels, ranges and choices; see language/script-kinds.md). The Advanced box is the same configuration as JSON.

What a hook may do, and how it is kept in check#

• Permissions are the hook's own, ticked by you in the window and saved with the hook; nothing a program does can change them. They are limited to market.read, analytics.run, research.submit, workspace.read, workspace.write, external.access and script.run (start other scripts, at most three deep): a hook can never run a backtest or touch an account or an order. A script that needs a permission its hook lacks is refused with E-PERM-DENIED, and the log says so. The permissions of the editor's own Run (granted for the session) are separate and unchanged.
• At most 4 hooks run at once; a hook is not started again while its last run goes on; at most 30 starts a minute for one hook; a run is stopped after 30 s.
• Five failures in a row switch a hook off, with the reason shown beside it; switching it on again clears it.
• What a program caused does not start hooks. If a script opens a chart, the chart_opened that follows is marked as the script's and no hook runs for it: a hook on "symbol changes" that changes the symbol cannot loop.

Trigger lines#

Two tools in the Lines group of the drawing rail:

• Price Trigger Line — a horizontal line that runs its script when the price crosses it. A crossing is a change of side (or touching the line), as with price alerts: a market already above the line fires nothing, a jump over it fires, and the first price ever seen never does.
• Time Trigger Line — a vertical line that runs its script when the market clock reaches it: the wall clock in the live feed, the cursor in a replay (so in a replay it fires when the replay's time gets there).

Their properties have a Trigger page: the script (Choose… opens the script browser), Once or Every time (with a cooldown), the direction for a price line (either, up, down), where it is active (Live by default), the permissions the script may use (the same five as a hook, none by default), Re-arm and Run now (a test). The line wears a badge: run <script>, run: no script, or ran <script> once a one-shot has fired. The event the script reads is drawing_trigger, with drawing (its place in the chart's list), level and direction (up, down, forward). What a line remembers (which side the market was on, whether it has fired) is saved with the drawing.

A fired trigger plays the market-alert chime and counts in the alerts' unread number. Hidden lines are still watched.

Scripts folder and the browser#

Choosing a scripts folder (T0 Editor: File ▸ Choose Scripts Folder…, or the Explorer) makes the editor save there: Save on a new program asks only for a name and writes <folder>/<name>.tz. The script browser (T0 Editor: Ctrl+P, File ▸ Open Script…; and wherever a script is chosen) shows only .tz files, from that folder or from the whole machine; the machine-wide index is built in the background (it skips system folders, hidden folders, target, node_modules and .git, stops at 50 000 files or 15 s, and is cached in ~/.cache/ttt/t0/tz-index.json; Reindex repeats it).