Recorder
flowscope-recorder records markets around the clock and serves their history; the data hub runs it for every Flowscope client.
flowscope-recorder is a small native service. It runs the Flowscope engine headless on the live venues for a list of markets, around the clock, writes their history as day segments and serves them read-only over HTTP.
Flowscope clients do not read it directly. They take every market from the Flowscope data hub (flowscope-hub), which runs this same recorder inside, takes the same options and serves the same history paths. Clients take all their history from the hub: bars, footprints, the heatmap and context are built from what it recorded, never from a venue’s candles or trade history, so history begins where the recording does. A bare recorder is for operators and for tools that only want its files.
Why run one
Flowscope’s history is what was recorded, nothing else:
- No venue publishes historical order books, so heatmap history exists only where something recorded it.
- Bars, footprints, delta and CVD are built from recorded trades, not from a venue’s candles or trade pages. Before a market’s recording begins, a chart of it has no bars.
- Open interest and funding history are what was recorded, not a venue’s history.
- Hyperliquid maps built in-process see only a sample of trades, find accounts slowly and have no positioning footprints.
- Gamma exposure needs the whole option chain of a coin; the hub takes it from Deribit once a minute for every client, instead of every client asking Deribit.
A recorder, inside the hub, records all of it for the markets it records, around the clock. A client opening a 1-minute chart over a week of BTC downloads about 1.5 MB of footprints from it.
What it records
| Data | Stored as | Served at |
|---|---|---|
| Minute footprints with trade counts and size bands, minute context (open interest, funding, liquidations, depth) | One day segment per market and UTC day | /v1/segments/… |
| Hyperliquid take-profit, stop and liquidation levels | Level runs, appended per day per coin | /v1/hl/levels/… |
| Hyperliquid open-interest, net-long and net-short footprints | Footprint minutes, appended per day per coin | /v1/hl/footprint/… |
| BTC and ETH option chains on Deribit (every option’s open interest, mark volatility, underlying and net taker flow from the option trades), once a minute | Snapshots, appended per day per coin | /v1/options/… |
A client merges day segments with what its session saw live by one rule: the more complete minute wins.
It also serves hourly heatmap tiles of order-book liquidity and modeled liquidation levels (/v1/heatmap/…, /v1/liqmap/…).
How clients use it
Clients point at a hub, which records and serves the same history:
./target/release/flowscope-hub --open --markets BinanceUsdm:BTCUSDT --dir ./flowscope-data --listen 127.0.0.1:8790
FLOWSCOPE_HUB_URL=http://127.0.0.1:8790 ./target/release/flowscopeThe hub takes its own options first (--open: no keys, for local use), then every recorder option. The browser app reaches the hub through its website at /hub.
For every day a chart wants, the app asks the hub and re-asks today every two minutes. A minute the hub did not record stays Unavailable; nothing is fetched from the venue instead. See History and data.
The HTTP API is open to any client: CORS allows every origin. See the API reference.
Start here
The terminal has no market data without a hub (an empty FLOWSCOPE_HUB_URL): there is no mode on the venues directly. For development without one, use the simulator.