# Alerts (/vela-pro/modules/catalog/alerts)



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 [#configuration]

```ts
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 [#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.                                                  |

<Note>
  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.
</Note>

## Price alerts [#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]

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

```js
//@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 [#notifications]

When an alert fires, Vela Pro runs four steps in sequence:

1. Appends an `AlertEvent` to the firing log (retaining the 300 most recent events) and increments the unread badge count.
2. When `webhooks: true` is configured and the rule includes a webhook URL, sends a browser `POST` request to that URL with the serialized `AlertEvent` as JSON. Cross-origin webhook endpoints must allow CORS requests from your application's origin.
3. Triggers the in-app toast card and audio cue if enabled on the rule.
4. Calls your `onFire(event, rule)` handler with the updated rule (`fireCount` and `lastFiredAt` already incremented).

Use `onFire` to route notifications through server-side channels such as email, SMS, push notifications, or team chat.

## Controller API [#controller-api]

`alertsController()` returns the `AlertsController` instance once `enableVelaPro()` installs the module, or `null` beforehand.

```ts
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 [#alertsbackend-port]

Implement `AlertsBackend` to store alert rules and firing history on your server.

```typescript
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.

```ts
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 [#widgets]

`createAlertsList(props)` mounts the Alerts panel as a standalone component outside a workspace (see [Standalone widgets](/vela-pro/modules/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 [#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.

## Related [#related]

* [Watchlist](/vela-pro/modules/catalog/watchlist) and [Order book](/vela-pro/modules/catalog/order-book)
* [Pine Script® with PineTS](/vela-pro/indicators/pine/runtime)
* [API reference: Alerts](/vela-pro/api/alerts)
