mmflow Charts

Replay event overlays

Add timestamped market-event overlays to candle replay using the durable event archive with existing source adapters as write-through fallback. Phase 10 supports whale, inferred liquidation, and funding-change overlays without claiming full tick or L2 replay.

Archive-first

The history events route reads the replay event archive first, then falls back to existing timestamped sources only for uncovered ranges.

Source quality labels

Whale prints are observed HL trade records, Hyperliquid liquidation markers are inferred, and funding markers are snapshot-derived.

Synchronized replay

Non-candle ReplayEvent rows sort into the same deterministic cursor as candle replay sessions.

History events API

Request whale, liquidation, funding, or marker. Marker is recognized but API-unavailable unless a real marker archive exists; synthetic playground markers are never returned by the public API. Unknown types such as trade, book, orderbook, or footprint return 400.

REST response

GET /api/v1/history/events?symbol=BTC&venue=hl&types=whale,liquidation,funding&from=1730000000000&to=1730003600000

{
  "data": {
    "symbol": "BTC",
    "venue": "hl",
    "from": 1730000000000,
    "to": 1730003600000,
    "types": ["whale", "liquidation", "funding"],
    "events": [
      {
        "version": 1,
        "id": "whale:BTC:hl:1730000100000:buy:65000:1000000",
        "type": "whale",
        "ts": 1730000100000,
        "symbol": "BTC",
        "venue": "hl",
        "source": "hyperliquid:whale-archive",
        "sourceQuality": "confirmed",
        "side": "buy",
        "price": 65000,
        "notionalUsd": 1000000
      }
    ]
  },
  "meta": {
    "fetchedAt": 1730003601000,
    "source": "mmflow:history-events",
    "historySource": "mixed",
    "partial": true,
    "warnings": ["Hyperliquid liquidation events are inferred from archived sweep heuristics, not venue-confirmed liquidations."],
    "archive": {
      "available": true,
      "requestedFrom": 1730000000000,
      "requestedTo": 1730003600000,
      "returnedEvents": 1,
      "coveredFrom": 1730000000000,
      "coveredTo": 1730003600000,
      "eventFrom": 1730000100000,
      "eventTo": 1730000100000,
      "missingRanges": [],
      "missingTypes": [],
      "unavailableTypes": [],
      "wroteThrough": true
    }
  }
}

SDK replay integration

Convert history events into replay events and merge them with candle events before constructing a session.

SDK usage

import {
  createReplaySession,
  candlesToReplayEvents,
  historyEventsToReplayEvents,
  historyTradesToReplayEvents,
} from "@mmflow/charts";
import {
  fetchHistoryCandles,
  fetchHistoryEventsResponse,
  fetchHistoryTradesResponse,
} from "@mmflow/sdk";

const [candles, eventResponse, tradeResponse] = await Promise.all([
  fetchHistoryCandles({
    symbol: "BTC",
    venue: "hl",
    resolution: "1m",
    from,
    to,
  }),
  fetchHistoryEventsResponse({
    symbol: "BTC",
    venue: "hl",
    from,
    to,
    types: ["whale", "liquidation", "funding"],
  }),
  fetchHistoryTradesResponse({ symbol: "BTC", venue: "hl", from, to }),
]);

const replay = createReplaySession({
  events: [
    ...candlesToReplayEvents(candles, { symbol: "BTC", venue: "hl" }),
    ...historyEventsToReplayEvents(eventResponse.data.events),
    ...historyTradesToReplayEvents(tradeResponse.data.trades),
  ],
  speed: 10,
});

Try it in the playground

Enable replay, then turn on replay events to see a cursor-synced event tape and chart markers. Historical event archive coverage may be sparse or outside source retention; synthetic mode uses local demo markers only.

Open synthetic event replay Replay basics Replay sessions Trade replay Footprint replay Orderbook replay Data feeds

Current limitations

Phase 10 archives sparse replay event overlays first. It does not provide full historical tick history, historical orderbook/L2 delta reconstruction, durable footprint storage, a full trade/event warehouse, cloud replay sessions, alerts, backtesting, or strategy execution. Short-window footprint replay is derived from bounded available trades, and orderbook replay is sparse snapshot playback. Some sources may be partial, inferred, unavailable, or limited by KV retention. The history status endpoint reports sparse event coverage as healthy only when the checked range has explicit archive/source coverage; otherwise it returns partial, unavailable, or unknown instead of pretending no event happened.