# 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:

```bash
./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/flowscope
```

The 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](/docs/app/history-and-data#hub).

The HTTP API is open to any client: CORS allows every origin. See the [API reference](/docs/api).

## Start here

```cards
[Quickstart](/docs/recorder/quickstart) Build it, run it and serve it to the desktop through a hub in five minutes.
[Configuration](/docs/recorder/configuration) Every flag and FLOWSCOPE_RECORD_* variable with defaults.
[Hyperliquid](/docs/recorder/hyperliquid) Record measured TP, SL and liquidation maps and positioning footprints.
[Storage](/docs/recorder/storage) Directory layout, file formats and retention.
[Deployment](/docs/recorder/deployment) systemd, a caching reverse proxy and sizing.
[Architecture](/docs/recorder/architecture) How it works today and where it is going.
[API](/docs/api) The read-only HTTP endpoints.
```

> [!NOTE]
> 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](/docs/app/install#simulator).