BullAlert API & MCP

The current ranked candidate list, recomputed each 5-min cycle and projected to a minimal, stable shape.

Query parameters

curl -H "x-ba-api-key: ba_live_..." \
  "https://api.bullalert.ai/v1/watchlist?as_of=2026-05-19T18:30:00Z&limit=25"

Response

{
  "data": {
    "watchlist": [
      { "rank": 1, "ticker": "WOLF", "score": 95, "status": "momentum" },
      { "rank": 2, "ticker": "AMD",  "score": 72, "status": "momentum" },
      { "rank": 3, "ticker": "TSLA", "score": 64, "status": "watch" }
    ]
  },
  "meta": {
    "timestamp": "2026-05-28T18:05:32Z",
    "api_version": "v1",
    "algorithm_version": "v1.1.0",
    "session": "market",
    "count": 3,
    "momentum_count": 2,
    "data_freshness_seconds": 23,
    "mtf_enabled": true,
    "rate_limit_remaining": 59,
    "rate_limit_reset": "2026-05-28T18:06:00Z"
  }
}

v1 row shape is intentionally minimal — rank + ticker + score + status. Session-aware, recomputed each 5-min cycle. We give you the ranked tickers, the score, and the current state; for prices, % moves, charts, and news, plug in the market-data API of your choice.

Every row carries a status: momentum (met all admission criteria as of this 5-min refresh) or watch (on the universe pool, criteria not all met this refresh — informational fill-back). The list is sorted momentum-first, so every momentum row outranks every watch row regardless of raw score. Pass ?status=momentum to narrow the response to the strict cohort. meta.momentum_count tells you how many of meta.count rows are momentum without scanning the array.

Outside trading hours (weekends, holidays, overnight 8 PM – 4 AM ET) the response returns data.watchlist: [] plus meta.market_status: "closed" and a human-readable meta.message. Cached longer in that state.

Field reference

rank

1-based ranking. Rank 1 is the strongest pick in the response.

ticker

US small-cap symbol. Every ticker returned has cleared the full BullAlert pipeline — 20 hard gates plus a momentum check by our proprietary algorithm. One row per ticker per response (deduped across internal lists).

score

Composite on a normalized 0–100 scale, produced by our proprietary algorithm.

status

"momentum" (green) — the row met all admission criteria as of this 5-min refresh. "watch" (yellow) — on the universe pool but criteria not all met this refresh; informational. The list is sorted momentum-first, so every momentum row outranks every watch row regardless of raw score. Filter to one cohort with the ?status query param.

meta.timestamp

UTC ISO8601 timestamp the response was computed.

meta.algorithm_version

Version of the underlying algorithm. Bumps when we ship improvements.

meta.session

Resolved session — what "current" turned into, or what you asked for. Can also be "closed" when the market is shut.

meta.count

Number of rows actually returned (≤ limit).

meta.momentum_count

How many of the count rows have status="momentum". meta.count − meta.momentum_count = the number of watch rows. Useful for routing without scanning the array.

meta.data_freshness_seconds

Age in seconds of the freshest data sample used by the momentum eval. Typical calls are 30–90s; null when market is closed.

meta.mtf_enabled

True when the engine ran the 5-min multi-timeframe context primitives in addition to the 1-min baseline.

meta.rate_limit_remaining

Calls left in your current per-minute window (mirrors the X-RateLimit-Remaining header). Per-day and per-month budgets are reported on the X-RateLimit-Daily-* and X-RateLimit-Monthly-* response headers.

meta.rate_limit_reset

UTC ISO8601 timestamp at which the per-minute window resets. Mirrors X-RateLimit-Reset. After this point, your per-minute budget refills.

meta.market_status (optional)

Present only when the market is closed. Value: "closed".

meta.message (optional)

Human-readable explanation, present only on market-closed responses.