Alerts
Configure price and Pine Script® alerts, handle notification callbacks and webhooks, manage rules from code, and persist alerts to your server.
The Alerts module notifies users when market prices cross a target level or when an indicator or strategy raises a signal. It is enabled by default when you call enableVelaPro(), registering the alert editor dialog, interactive alert lines on the chart, and the Alerts side panel.
Key features include:
- Price alerts created from the chart or price-axis right-click menu, with Alt+A, from the Alerts panel, from a watchlist row, or from an order book price level. Active price alerts render on the symbol's chart as dashed lines with a bell label that users can drag to adjust the price, click to edit, or dismiss with
✕. - Script alerts attached to any Pine Script® indicator or strategy via the bell button on its legend row.
- An Alerts side panel listing active, triggered, and paused rules alongside a chronological firing log, paired with an unread count badge on the side rail.
- Per-alert notification channels including an in-app toast card, an audio alert, and an optional webhook URL.
Configuration
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';
enableVelaPro({
alerts: {
webhooks: true,
onFire: (event, rule) => {
void fetch('/api/notifications', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ title: rule.name, body: event.message, symbol: event.symbol }),
});
},
},
});
const workspace = new VelaWorkspace('#chart', {
layout: false,
symbol: 'BTCUSDT',
live: true,
providers: { binance: () => new BinanceProvider() },
persist: true,
});Pass enableVelaPro({ alerts: false }) to disable the module.
Options
| Option | Default | Description |
|---|---|---|
backend | new LocalAlertsBackend() | AlertsBackend adapter for persisting rules and firing history. Defaults to localStorage under the key vela-pro.alerts. |
onFire | None | Callback invoked with (event, rule) on every firing after built-in notifications run. Use this to forward alerts to email, push notifications, or your backend. |
webhooks | false | Enables the webhook URL field in the alert dialog so firings can POST to an HTTP endpoint. |
contextMenu | true | Adds "Add alert" to the chart and price-axis right-click context menus. |
shortcut | true | Enables the Alt+A keyboard shortcut to open the alert dialog at the latest price. |
legendAction | true | Displays a bell action button on the legend row of script indicators. |
topbarBell | false | Retains an Alerts bell button in the topbar. Disabled by default because the side rail includes an Alerts entry. |
Alert conditions are evaluated client-side against live chart updates. An alert can fire only while the page is open and a chart initialized with live: true is streaming its symbol. Charts in bar replay mode do not evaluate alerts. For continuous server-side alerting when the browser is closed, persist rules through backend and evaluate them on your backend.
Price alerts
Each price alert defines a comparison condition, a firing frequency, a message template, and an optional expiration timestamp.
Condition (op) | Trigger condition |
|---|---|
'crossing' | Price crosses the target level in either direction |
'crossing-up', 'crossing-down' | Price crosses the target level upward or downward |
'greater-than', 'less-than' | Price trades strictly above or strictly below the target level |
'entering-channel', 'exiting-channel' | Price moves inside or outside the channel bounds |
'inside-channel', 'outside-channel' | Price trades within the channel bounds or outside them |
| Frequency | Behavior |
|---|---|
'once' | Fires once, then transitions the rule's status to 'triggered' |
'once-per-bar' | Fires at most once per bar as soon as the condition is met |
'once-per-bar-close' | Fires when a bar closes with the condition satisfied |
'every-time' | Fires on every live price tick where the condition holds |
Alert messages support the template variables {{ticker}}, {{symbol}}, {{close}}, {{price}}, {{time}}, {{interval}}, and {{name}}. Price alerts default to {{ticker}} {{name}} at {{close}}.
Script alerts
Script alerts subscribe to signals emitted by a Pine Script® indicator or strategy running on the chart. For each eligible script, the alert dialog lets the user select which events trigger the rule:
- Dynamic
alert()calls emitted by the script - A specific
alertcondition()declaration matched by title - Strategy order fills (when the script is a strategy)
- Any alert raised by the script
//@version=6
indicator("EMA cross", overlay = true)
fast = ta.ema(close, 9)
slow = ta.ema(close, 21)
plot(fast)
plot(slow)
alertcondition(ta.crossover(fast, slow), "Bullish cross", "Fast EMA crossed above slow EMA")
if ta.crossunder(fast, slow)
alert("Fast EMA crossed below slow EMA")For the script above, the alert dialog lists "Any alert of the script", "Its alert() calls", and "Bullish cross". Script alerts evaluate on live bars as the engine emits events. They default to 'once-per-bar' frequency and the {{message}} template, which expands to the message emitted by the script.
Charts automatically display a toast card whenever a running script calls alert(). Creating a script alert rule adds audio notifications, firing log entries, webhook delivery, and onFire callbacks.
Notifications
When an alert fires, Vela Pro runs four steps in sequence:
- Appends an
AlertEventto the firing log (retaining the 300 most recent events) and increments the unread badge count. - When
webhooks: trueis configured and the rule includes a webhook URL, sends a browserPOSTrequest to that URL with the serializedAlertEventas JSON. Cross-origin webhook endpoints must allow CORS requests from your application's origin. - Triggers the in-app toast card and audio cue if enabled on the rule.
- Calls your
onFire(event, rule)handler with the updated rule (fireCountandlastFiredAtalready incremented).
Use onFire to route notifications through server-side channels such as email, SMS, push notifications, or team chat.
Controller API
alertsController() returns the AlertsController instance once enableVelaPro() installs the module, or null beforehand.
import { alertsController } from '@luxalgo/vela-pro-alerts';
const alerts = alertsController();
if (alerts) {
const rule = alerts.create({
symbol: 'BTCUSDT',
name: 'BTC breakout',
condition: { kind: 'price', op: 'crossing-up', value: 80_000 },
frequency: 'once-per-bar-close',
message: '{{ticker}} closed above {{close}}',
expiresAt: Date.now() + 7 * 86_400_000,
});
// Channel conditions specify lower and upper bounds via `value` and `upper`.
alerts.create({
symbol: 'ETHUSDT',
condition: { kind: 'price', op: 'exiting-channel', value: 2_800, upper: 3_200 },
});
alerts.setPaused(rule.id, true);
alerts.onChange((what) => {
if (what === 'events') console.info(alerts.log()[0]);
});
}create populates omitted fields with defaults ('once' frequency for price alerts, toast and sound enabled, and expiresAt: null). Rule symbol strings are matched literally against the active chart symbol, so format them identically to workspace.context().symbol.
Additional controller members include rules(), rule(id), update(id, patch), remove(id), log(), clearLog(), markRead(), unreadCount, and onFire(listener). onChange notifies listeners with 'rules' or 'events'.
AlertsBackend port
Implement AlertsBackend to store alert rules and firing history on your server.
interface AlertsBackend {
load(): { rules: AlertRule[]; events: AlertEvent[] };
save(state: { rules: readonly AlertRule[]; events: readonly AlertEvent[] }): void;
}
interface AlertRule {
id: string;
name: string;
symbol: string;
condition: AlertCondition;
frequency: 'once' | 'once-per-bar' | 'once-per-bar-close' | 'every-time';
message: string;
notify: { toast: boolean; sound: boolean; webhook?: string };
status: 'active' | 'paused' | 'triggered' | 'expired';
expiresAt: number | null; // epoch ms, or null when the rule never expires
createdAt: number;
updatedAt: number;
lastFiredAt?: number;
fireCount: number;
}
interface AlertEvent {
id: string;
ruleId: string;
name: string;
symbol: string;
time: number;
message: string; // rendered template text
price?: number;
}load() is synchronous and runs once during module installation, so prefetch saved rules from your API before calling enableVelaPro(). save(state) is debounced and receives the complete { rules, events } snapshot after changes. Rule and event IDs remain stable across saves.
import { enableVelaPro } from '@luxalgo/vela-pro';
import { alertsController, type AlertEvent, type AlertRule, type AlertsBackend } from '@luxalgo/vela-pro-alerts';
interface KeptAlerts {
rules: AlertRule[];
events: AlertEvent[];
}
const res = await fetch('/api/alerts', { credentials: 'include' });
if (!res.ok) throw new Error(`Alerts: HTTP ${res.status}`);
const kept = (await res.json()) as KeptAlerts;
const backend: AlertsBackend = {
load: () => kept,
save: (state) => {
void fetch('/api/alerts', {
method: 'PUT',
credentials: 'include',
keepalive: true,
headers: { 'content-type': 'application/json' },
body: JSON.stringify(state),
});
},
};
enableVelaPro({ alerts: { backend } });
// Flush any pending debounced save when the page unloads.
window.addEventListener('pagehide', () => alertsController()?.flush());LocalAlertsBackend(key) is the default browser storage adapter, and MemoryAlertsBackend keeps alerts in memory for the current session only.
Widgets
createAlertsList(props) mounts the Alerts panel as a standalone component outside a workspace (see Standalone widgets).
| Prop | Description |
|---|---|
controller | Required. AlertsController managing rules and firing events. |
symbol | Default symbol preselected when clicking "New alert". |
host | Portal container for menus and overlays. Defaults to the widget's root element. |
active | Whether the widget is visible. When visible on the log tab, unread firings are marked read. |
onOpenAlert | Callback invoked with an alert seed when the user clicks "New alert", clicks a rule row, or selects Edit. When omitted, the list supports viewing and pausing rules only. |
onNotify | Callback invoked with (message, kind) to surface status messages. |
Pass openAlertDialog(ctx, controller, seed) to onOpenAlert to reuse the built-in alert editor dialog when a workspace context is available. The seed object includes symbol plus price (new price alert at that level), indicatorId (new script alert), or rule (existing rule to edit).
When running outside a workspace, feed live prices to the controller manually by calling controller.notePrice(symbol, price, barTime) on each tick. barTime is the opening timestamp of the current bar and is used to evaluate 'once-per-bar' and 'once-per-bar-close' frequencies.
Keyboard shortcuts
| Keys | Action |
|---|---|
| Alt+A | Opens the new-alert dialog for the active chart's symbol at the latest price |
Keyboard shortcuts do not trigger while focus is inside an editable input. Pass shortcut: false to disable Alt+A.