mmflow Charts

Bounded recent trade replay

Fetch normalized recent Hyperliquid trades from an archive-first route and convert them into replay events. Phase 11 is bounded and recent by design; it is not a full historical tick warehouse.

Archive-first

The trade route reads hourly KV archive buckets first, then uses a bounded recent-trades source only for uncovered recent ranges.

Explicit coverage

meta.archive distinguishes checked empty ranges from cold archive gaps. Recent source fallback only writes empty coverage when it can prove the checked range.

Replay conversion

historyTradesToReplayEvents converts normalized trade rows into ReplayTradeEvent objects for cursor-synced tapes and markers.

History trades API

Use from and to as inclusive unix millisecond timestamps. Optional side and minUsd filters apply after archive/source coverage is evaluated, so a fully covered range can still return zero filtered trades.

REST response

GET /api/v1/history/trades?symbol=BTC&venue=hl&from=1730000000000&to=1730003600000&limit=1000

{
  "data": {
    "symbol": "BTC",
    "venue": "hl",
    "from": 1730000000000,
    "to": 1730003600000,
    "limit": 1000,
    "trades": [
      {
        "version": 1,
        "id": "trade:hl:BTC:1730000100000:buy:65000:1:65000:0",
        "ts": 1730000100000,
        "symbol": "BTC",
        "venue": "hl",
        "side": "buy",
        "price": 65000,
        "size": 1,
        "notionalUsd": 65000,
        "source": "hyperliquid:recentTrades",
        "sourceQuality": "confirmed"
      }
    ]
  },
  "meta": {
    "fetchedAt": 1730003601000,
    "source": "mmflow:history-trades",
    "historySource": "mixed",
    "partial": true,
    "warnings": ["Requested trade range extends before Hyperliquid recentTrades retention; older coverage is unavailable."],
    "archive": {
      "available": true,
      "requestedFrom": 1730000000000,
      "requestedTo": 1730003600000,
      "returnedTrades": 1,
      "coveredFrom": 1730000100000,
      "coveredTo": 1730003600000,
      "missingRanges": [],
      "wroteThrough": true
    }
  }
}

SDK replay integration

The simple SDK helper returns an array of trades. Use the response helper when you need coverage metadata or archive/source warnings.

SDK usage

import {
  createReplaySession,
  historyTradesToReplayEvents,
} from "@mmflow/charts";
import { fetchHistoryTradesResponse } from "@mmflow/sdk";

const response = await fetchHistoryTradesResponse({
  symbol: "BTC",
  venue: "hl",
  from,
  to,
  limit: 1000,
  minUsd: 100000,
});

const replay = createReplaySession({
  events: historyTradesToReplayEvents(response.data.trades),
  speed: 10,
});

Try it in the playground

Enable historical replay, then turn on the trade tape. Candle replay continues even when recent trade coverage is unavailable.

Open trade tape replay Replay event overlays Replay sessions Footprint replay Data feeds

Current limitations

Phase 11 provides a bounded recent HL trade archive MVP. Coverage starts when the archive/write-through path is used and depends on recent source retention. Phase 12 can derive short-window footprint bars from those trades, but this route is not retroactive full tick history, not L2/orderbook replay, not a footprint warehouse, and not warehouse-backed ClickHouse/Redpanda infrastructure. History status probes trades over a small recent window with a 5-minute freshness threshold and reports partial when source coverage is mixed, capped, or warning-bearing.