Alert

Overview

Alert includes 1 tool for this workflow area.

Available tools: manage_alerts.

Use the parameter tables and examples below as the canonical request contract.

manage_alerts

Manages persistent server-side alerts, evaluated every ~30 seconds while the terminal is connected (not tick-precise), dispatched by action. Available at Pro+ tier. An alert is evaluated against the terminal this session is bound to.

action=create: registers an alert. Types and conditions:

• price {symbol, operator above|below, price}
• indicator {symbol, timeframe, indicator, operator above|below|crosses_above|crosses_below, value, params?}
• position_event {event sl_hit|tp_hit|position_closed, ticket?}
• margin_level {operator "below", percent}
• position_r_reached {ticket, r, r_basis_sl?}: fires when the open position reaches r multiples of its initial risk (r is a multiple, e.g. 2). Risk is measured from the stop-loss in force when the alert is created, or r_basis_sl (a price) if given; moving the stop later does not change it. A position without a stop needs r_basis_sl. Cancelled by itself if the position closes first.
• position_closed {ticket?}: fires when a position (that ticket, or any) disappears; the event carries ticket, symbol, side, volume, entry_price, last_seen_price, sl, tp and detected (sl_hit|tp_hit|position_closed).
• structure_break {symbol, timeframe, kind "BOS"|"CHoCH"}: fires when a new break of that kind is confirmed on a closed bar (same detection as detect_structure). Breaks already present when the alert is first evaluated are ignored.
• equity_drawdown {percent}: fires when equity is at least percent below balance, (balance - equity) / balance * 100. Floating loss against balance, not a peak-to-trough drawdown.
• spread_spike {symbol, spread_points | multiplier}: give exactly one. spread_points is an absolute spread in points; multiplier fires when the spread exceeds that multiple of the recent median (needs about 5 minutes of samples after a restart).
• terminal_disconnected {grace_seconds?}: fires when this terminal has been disconnected for grace_seconds (10 to 3600, default 60). A quick reconnect does not fire. It cannot fire if the whole server is down.
• heartbeat_expired {owner?}: fires when a heartbeat owner (see the heartbeat tool) expires, for any owner or only the named one; this is how an expiry reaches a webhook. The event carries owner, ttl_sec, last_seen, on_expire and the per-position results. mode=once fires a single time; mode=recurring re-arms after cooldown_seconds. Fired events are always queued durably for action=poll. Active-alert caps by tier: Pro 10, Team 50, Enterprise 200. Requires type and condition. dry_run=true (default false) validates everything, including the webhook address, and shows what would be created without creating it.

Webhook delivery: add delivery {webhook_url, secret, include_snapshot?} to also push each fired event. webhook_url must be https on the default port 443, use a fully qualified host name, and resolve to a public address (internal, loopback and private addresses are refused; redirects are not followed). The URL and the secret (16 to 128 characters of your choosing) are stored encrypted and never shown again; lists show only the host. The gateway POSTs a JSON body {event_id, event_type, alert_id, fired_at (UTC), terminal_id, note, condition, context, snapshot?} with headers X-MTContext-Signature: sha256=<hex HMAC-SHA256 of the raw body keyed with the secret>, X-MTContext-Event-Id (the same on every retry: use it to ignore duplicates) and X-MTContext-Delivery-Attempt. Receivers should compare the signature in constant time and reject a fired_at older than about 40 minutes (the retries span 36), so a captured request cannot be replayed later. A 2xx response counts as delivered; anything else is retried up to 5 attempts in total, waiting 10 seconds, 1 minute, 5 minutes and 30 minutes. include_snapshot=true adds the account and open positions at fire time as snapshot. Webhooks need a server-side encryption key; without one create fails with WEBHOOKS_UNAVAILABLE.

action=list: lists all alerts for this license with status (active/fired/cancelled), condition, mode, fire count, delivery (webhook_host, include_snapshot, secret_set; never the secret) and last_evaluated_at (stale while the terminal is disconnected — evaluation pauses).

action=cancel: cancels an active alert by alert_id (from a prior action=create or action=list). Returns ALERT_NOT_FOUND if the alert does not exist, already fired, or was already cancelled. Requires alert_id.

action=poll: drains undelivered fired-alert events (oldest first) and marks them delivered. Each event carries event_id, the alert's condition echo, the triggering values, and the fired timestamp. Events are retained 7 days; pass include_delivered=true to see the retained history. Call this periodically — alerts are pull-based unless a webhook is configured.

action=deliveries: the webhook delivery log, newest first. Optional alert_id, status (pending|delivered|failed) and limit (1-100, default 20). Each item has delivery_id, alert_id, event_id, status, attempts, next_attempt_at, created_at, delivered_at, last_status_code, last_error and attempt_log (attempt, at UTC, status_code, error, duration_ms). Kept for 7 days.

Parameters

Example Request

{
  "tool": "manage_alerts",
  "arguments": {
    "action": "create",
    "dry_run": false
  }
}

Usage Notes

• Keep dry_run: true until you have validated symbol, lot size, and expected execution behavior.