Skip to content
Terminal

Alert schema

One alert is the object terminal.alert.v1. The events feed, GET /v1/alerts/{id}, a terminal webhook, and a test built from a real alert all use it. sequence, sent_at, and the via on links.alert are what change between copies. On a read or a feed event, sequence is null and via is api. On a webhook, via is webhook.

Times are UTC, ISO 8601, with milliseconds and Z. A missing price is null. Null means unavailable. It does not mean zero. Prices are US dollars.

The labeled example further down uses fixed figures so you can see the shape. Those figures are not a live quote. A live read of your own alert follows the same field names.

Price

A Price is an object.

Event

Rule and condition

Requests and responses use the public condition names.

Measured

percent_change and the move half of unusual_move:

unusual_move also has range_pct (percent), sigma_pct (percent), and samples (integer count of earlier windows).

price_above uses high (Price) and from_minute (time). price_below uses low (Price) and from_minute.

volume_spike:

A minute the feed did not record is left out. It is not counted as zero.

Context

Note

A fresh alert with no note request has status none. A webhook often leaves while the note is pending. Read GET /v1/alerts/{alert_id} for the later state. note_facts on that response is null unless status is ready and a fact sheet was stored. When it is set, it is { "at": time, "lines": [ ... ] }.

Receipts

The object always has the keys 1h, 4h, 24h, and 7d.

Receipts are a price record. Terminal does not score them or rank them.

The record

GET /v1/rules/{id}/record lists alerts for one rule inside the plan's history. summary is null while summary totals are off. Each horizon count has recorded, pending, and missing. next_before is an alert id when another page exists, otherwise null.

Names Terminal does not write

Terminal does not put these names on an object it writes: action, side, signal, recommendation, target, confidence, bullish, bearish.

Strings Terminal writes do not tell you to buy, sell, or hold. Text you wrote yourself is kept as you wrote it: a rule name, a destination label, and a template stored as a string. The notice is the product sentence on Notice and terms.

Example

Example. These are not live prices.

{
  "schema": "terminal.alert.v1",
  "id": "alert_9001",
  "type": "alert.fired",
  "alert_id": 9001,
  "sequence": 42,
  "fired_at": "2026-10-12T14:03:00.000Z",
  "sent_at": "2026-10-12T14:03:01.215Z",
  "rule": {
    "id": 41,
    "name": "SOL falls 5% in 1 hour",
    "kind": "percent_change",
    "scope": "symbol",
    "condition": { "threshold_pct": 5, "window": "1h", "direction": "down" },
    "cooldown_seconds": 3600
  },
  "service": null,
  "asset": { "symbol": "SOL", "name": "Solana" },
  "price": { "value": 142.5, "currency": "USD", "source": "coinbase", "at": "2026-10-12T14:02:59.412Z" },
  "measured": {
    "change_pct": -5.0,
    "from": { "value": 150, "currency": "USD", "source": "coinbase", "at": "2026-10-12T13:03:00.000Z" },
    "to": { "value": 142.5, "currency": "USD", "source": "coinbase", "at": "2026-10-12T14:02:59.412Z" }
  },
  "headline": "Solana (SOL) fell 5.0% in 1 hour.",
  "context": {
    "change_pct": { "15m": -1.2, "1h": -5.0, "4h": -6.1, "24h": -4.0 },
    "volume_1h": { "ratio": 2.13, "window_volume": 210000, "window_minutes": 60, "baseline_per_minute": 1640, "baseline_days": 20 },
    "market": {
      "BTC": {
        "price": { "value": 100000, "currency": "USD", "source": "coinbase", "at": "2026-10-12T14:02:58.100Z" },
        "change_pct": { "15m": -0.3, "1h": -1.8, "4h": -2.0, "24h": -1.1 }
      },
      "ETH": null
    }
  },
  "note": { "status": "pending", "text": null, "ai_written": false, "label": null, "reason": null },
  "receipts": {
    "1h": { "status": "pending", "due_at": "2026-10-12T15:03:00.000Z", "price": null, "change_pct": null, "recorded_at": null },
    "4h": { "status": "pending", "due_at": "2026-10-12T18:03:00.000Z", "price": null, "change_pct": null, "recorded_at": null },
    "24h": { "status": "pending", "due_at": "2026-10-13T14:03:00.000Z", "price": null, "change_pct": null, "recorded_at": null },
    "7d": { "status": "pending", "due_at": "2026-10-19T14:03:00.000Z", "price": null, "change_pct": null, "recorded_at": null }
  },
  "links": {
    "alert": "https://terminal.tokensmarketcap.com/app/alerts/9001?via=webhook",
    "api": "https://terminal.tokensmarketcap.com/v1/alerts/9001",
    "share": null,
    "proof": null
  },
  "notice": "Terminal reports market events for conditions you set. It does not tell you to buy, sell, or hold, and it does not place trades.",
  "terms": { "version": "2026-10-draft", "url": "https://terminal.tokensmarketcap.com/api-terms" }
}

Read one alert

A live read wraps the event in alert and adds note_facts. The note on an alert with no note request is none.

Example. These are not live prices.

GET /v1/alerts/$ALERT_ID HTTP/1.1
Authorization: Bearer $TERMINAL_API_KEY

HTTP/1.1 200 OK
{
  "alert": {
    "schema": "terminal.alert.v1",
    "type": "alert.fired",
    "sequence": null,
    "fired_at": "2026-10-12T14:03:00.000Z",
    "headline": "Solana (SOL) fell 5.0% in 1 hour.",
    "service": null,
    "asset": { "symbol": "SOL", "name": "Solana" },
    "price": { "value": 142.5, "currency": "USD", "source": "coinbase", "at": "2026-10-12T14:02:59.412Z" },
    "rule": {
      "name": "SOL falls 5% in 1 hour",
      "kind": "percent_change",
      "scope": "symbol",
      "cooldown_seconds": 3600,
      "condition": { "threshold_pct": 5, "window": "1h", "direction": "down" }
    },
    "note": { "status": "none", "text": null, "ai_written": false }
  },
  "note_facts": null
}

Read the record

Example. These are not live prices.

GET /v1/rules/$RULE_ID/record HTTP/1.1
Authorization: Bearer $TERMINAL_API_KEY

HTTP/1.1 200 OK
{
  "record": {
    "summary": null,
    "fired": 1,
    "first_fired_at": "2026-10-12T14:03:00.000Z",
    "last_fired_at": "2026-10-12T14:03:00.000Z",
    "horizons": {
      "1h": { "recorded": 0, "pending": 1, "missing": 0 },
      "4h": { "recorded": 0, "pending": 1, "missing": 0 },
      "24h": { "recorded": 0, "pending": 1, "missing": 0 },
      "7d": { "recorded": 0, "pending": 1, "missing": 0 }
    },
    "alerts": [
      {
        "headline": "Solana (SOL) fell 5.0% in 1 hour.",
        "asset": { "symbol": "SOL", "name": "Solana" },
        "price": { "value": 142.5, "currency": "USD", "source": "coinbase" }
      }
    ],
    "next_before": null
  }
}

Create a free account

All developer pages

Terminal reports market events for conditions you set. It does not tell you to buy, sell, or hold, and it does not place trades.