MM Flow

mmflow Charts

Footprint replay

Derive bounded footprint bars from normalized recent trade history. Phase 12 is a short-window replay surface, not a durable footprint warehouse or full tick/L2 archive.

Trade-derived

The history-footprint route imports the Phase 11 trade history service directly and aggregates normalized trades. It does not HTTP self-fetch history routes or call live SSE streams.

Base-volume delta

Footprint volume uses trade size in base units. Delta is buy volume minus sell volume; unknown-side trades add to total volume but not delta.

Replay-ready

historyFootprintToChartBars converts the REST/SDK footprint bars into the stable VolumeFootprintLayer shape for replay previews.

History footprint API

Use from and to as inclusive unix millisecond timestamps. limit means maximum footprint bars, not trades or cells. If the requested range exceeds the bar limit, the route clamps from forward to the most recent allowed window.

REST response
GET /api/v1/history/footprint?symbol=BTC&venue=hl&resolution=1m&from=1730000000000&to=1730003600000&priceStep=10

{
  "data": {
    "symbol": "BTC",
    "venue": "hl",
    "resolution": "1m",
    "from": 1730000000000,
    "to": 1730003600000,
    "priceStep": 10,
    "bars": [
      {
        "time": 1730000040000,
        "open": 65000,
        "high": 65020,
        "low": 64990,
        "close": 65010,
        "volume": 3,
        "buyVolume": 2,
        "sellVolume": 1,
        "delta": 1,
        "trades": 2,
        "cells": [
          {
            "price": 65000,
            "buyVolume": 2,
            "sellVolume": 1,
            "volume": 3,
            "delta": 1,
            "trades": 2
          }
        ]
      }
    ]
  },
  "meta": {
    "fetchedAt": 1730003601000,
    "source": "mmflow:history-footprint",
    "historySource": "mixed",
    "partial": true,
    "warnings": ["Some trades have unknown side; delta excludes unknown volume."],
    "trades": {
      "returnedTrades": 2,
      "historySource": "mixed",
      "partial": true
    }
  }
}

SDK and chart integration

The simple SDK helper returns bars. Use the response helper for underlying trade-source metadata and partial coverage warnings.

SDK usage
import {
  historyFootprintToChartBars,
} from "@mmflow/charts";
import { fetchHistoryFootprintResponse } from "@mmflow/sdk";

const response = await fetchHistoryFootprintResponse({
  symbol: "BTC",
  venue: "hl",
  resolution: "1m",
  from,
  to,
  priceStep: "auto",
});

const chartBars = historyFootprintToChartBars(response.data.bars);
const source = response.meta.trades?.historySource;

Try it in the playground

Enable replay, switch to historical source, and turn on footprint replay. Candle replay continues if footprint coverage is unavailable.

Open footprint replayTrade replayReplay eventsReplay sessionsOrderbook replay

Current limitations

Phase 12 derives footprint bars from bounded available trades. It does not provide full historical footprint coverage, full tick history, historical L2 delta/orderbook reconstruction, footprint persistence, backtesting, or warehouse-backed ClickHouse/Redpanda infrastructure. Sparse orderbook snapshot replay is separate from full book-delta replay. Footprint status is derived from bounded trade status by default, so stale or partial trades make footprint status stale or partial without running an expensive duplicate aggregation.