Alerts

Alerts let a script expose named alert conditions. A user selects one alert definition, then the runtime sends a trigger event when that selected alert fires.

alert.define

const handle = alert.define(key, options?)

Defines an alert at top level and returns a handle with trigger(payload?).

const crossUp = alert.define("cross.up", {
  title: "Fast EMA crossed up",
  description: "Fast EMA crossed above slow EMA",
  fields: [
    { key: "price", type: "number" },
    { key: "fast", type: "number" },
    { key: "slow", type: "number" }
  ]
});

key must be 1-80 characters and can contain letters, numbers, ., _, :, and -. Keys must be unique within a script.

Options:

Option	Type	Default	Description
`title`	`string`	`key`	Display name for the alert
`description`	`string`	`""`	Longer explanation for the alert
`fields`	`Array<{ key, type? }>`	`[]`	Optional payload schema

Field type can be string, number, or bool. If omitted, it defaults to string. Field keys use the same character and length rules as alert keys.

alert.trigger

handle.trigger(payload?)

Triggers the alert handle returned from alert.define.

crossUp.trigger({
  price: candles.close(),
  fast,
  slow
});

Triggers only emit while the runtime is evaluating realtime alert mode. Calls during history warmup, normal indicator rendering, or for alerts other than the selected alert are ignored.

When fields are declared, the payload must exactly match the field list:

no missing fields
no unknown fields
number fields must be finite numbers
bool fields must be booleans
string fields must be strings

When no fields are declared, the payload can be any flat object whose keys use alert-key characters and whose values are strings, finite numbers, booleans, or null.

If trigger() is called with no payload, declared fields receive defaults: "" for strings, 0 for numbers, and false for booleans. Alerts without fields emit {}.

Only one alert trigger can be emitted per script evaluation. Invalid trigger payloads are rejected as recoverable runtime warnings.

Webhook Body Templates

Use templates to turn an alert into a message for Discord, Telegram, Slack, or any webhook that accepts JSON or text. Anything inside {{ }} is replaced when the alert fires.

{
  "content": "{{alert.name}} on {{market.exchange}} {{market.symbol}} at {{num payload.price 2}}"
}

For JSON webhooks, place template expressions inside string values. This keeps the body valid JSON.

Available values:

Path	Description
`alert.name`	Alert name
`alert.key`	Alert key
`alert.triggerMode`	Trigger mode
`market.exchange`	Exchange
`market.symbol`	Market symbol
`market.timeframe`	Timeframe in seconds
`event.unix`	Alert time
`bar.unix`	Bar time
`bar.open`	Bar open
`bar.high`	Bar high
`bar.low`	Bar low
`bar.close`	Bar close
`bar.volume`	Bar volume
`bar.buyVolume`	Bar buy volume
`bar.sellVolume`	Bar sell volume
`bar.buyCount`	Bar buy trade count
`bar.sellCount`	Bar sell trade count
`payload.<field>`	A custom field from your alert script

Formatting helpers:

Helper	Example	Description
`num`	`{{num payload.price 2}}`	Show a number with fixed decimals. Decimals can be `0`-`8`.
`int`	`{{int payload.count}}`	Show a number without decimals.
`time`	`{{time event.unix}}`	Show a readable UTC time.
`upper`	`{{upper payload.direction}}`	Make text uppercase.
`lower`	`{{lower market.symbol}}`	Make text lowercase.

In JSON, write "price": "{{num payload.price 2}}", not "price": {{num payload.price 2}}.

Discord embed example:

{
  "embeds": [
    {
      "title": "{{alert.name}}",
      "description": "{{market.exchange}} {{upper market.symbol}}",
      "fields": [
        { "name": "Price", "value": "{{num payload.price 2}}", "inline": true },
        { "name": "Fast EMA", "value": "{{num payload.fast 2}}", "inline": true },
        { "name": "Slow EMA", "value": "{{num payload.slow 2}}", "inline": true },
        { "name": "Time", "value": "{{time event.unix}}", "inline": false }
      ]
    }
  ]
}

Telegram JSON example:

{
  "chat_id": "<chat_id>",
  "parse_mode": "Markdown",
  "text": "*{{alert.name}}*\n{{market.exchange}} {{upper market.symbol}}\nPrice: `{{num payload.price 2}}`\nTime: `{{time event.unix}}`"
}

Limits

Alert definitions per script: 32
Fields per alert: 32
Pending trigger events per evaluation: 32
Rejection warnings per evaluation: 8

Alerts

alert.define

alert.trigger

Webhook Body Templates

Limits

On this page