Configuration · Recorder

Every command-line flag and FLOWSCOPE_RECORD_* environment variable of the recorder, with defaults.

The recorder takes its settings from command-line flags, then from FLOWSCOPE_RECORD_* environment variables, then from built-in defaults. A flag always wins over its variable.

Options

Flag	Environment variable	Default	Meaning
`--markets`	`FLOWSCOPE_RECORD_MARKETS`	`Aggregate:BTC,Aggregate:ETH`	Markets to record, comma-separated `Venue:SYMBOL`; an `Aggregate:COIN` records the coin over all its venues and each venue’s market too
`--dir`	`FLOWSCOPE_RECORD_DIR`	`flowscope-data`	Data directory; created if missing
`--listen`	`FLOWSCOPE_RECORD_LISTEN`	`127.0.0.1:8787`	Address and port of the HTTP server
`--retention-days`	`FLOWSCOPE_RECORD_RETENTION_DAYS`	`90`	Days of history kept; minimum 1
`--save-secs`	`FLOWSCOPE_RECORD_SAVE_SECS`	`60`	Seconds between saves of changed day segments and Hyperliquid day files; minimum 5
`--hl-coins`	`FLOWSCOPE_RECORD_HL_COINS`	`BTC,ETH,SOL,HYPE`	Hyperliquid coins whose positions are recorded; empty turns it off
`--options-coins`	`FLOWSCOPE_RECORD_OPTIONS_COINS`	`BTC,ETH`	Coins whose Deribit option chains are recorded once a minute, for gamma exposure; only `BTC` and `ETH` (upper case) have options, other coins are ignored; empty turns it off
`--hl-state-per-min`	`FLOWSCOPE_RECORD_HL_STATE_PER_MIN`	`600`	Hyperliquid request weight per minute for position reads; 0 to 100 000
`--hl-orders-per-min`	`FLOWSCOPE_RECORD_HL_ORDERS_PER_MIN`	`1200`	Hyperliquid request weight per minute for order reads; 0 to 100 000

Values outside a minimum or range are clamped, not rejected. RUST_LOG sets the log filter and defaults to info.

Syntax

Flags take their value as the next argument or after =:

Terminal

flowscope-recorder --retention-days 365
flowscope-recorder --retention-days=365

Every argument must be a flag. The recorder exits with status 2 and a message on:

an unknown flag (unknown option --wat),
a flag without a value (--dir needs a value),
a value that is not a number where one is expected (retention-days: not a number: a year),
a market that does not parse (bad market `Nope:X` (want Venue:SYMBOL)),
an empty market list (no markets to record).

It exits with status 1 if it cannot create the data directory or bind the listen address.

Markets

A market is Venue:SYMBOL, in the venue’s own symbology:

Venue name	Venue	Symbol examples
`BinanceSpot`	Binance spot	`BTCUSDT`, `ETHUSDT`
`BinanceUsdm`	Binance USDⓈ-M futures	`BTCUSDT`, `SOLUSDT`
`Bybit`	Bybit linear perpetuals	`BTCUSDT`
`Okx`	OKX perpetual swaps	`BTC-USDT-SWAP`
`Hyperliquid`	Hyperliquid perpetuals	`BTC`, `HYPE`

Venue names are case-insensitive, and spaces around commas are ignored. Aggregated markets cannot be recorded directly; record their components instead, and clients sum them.

Terminal

--markets "BinanceUsdm:BTCUSDT, bybit:BTCUSDT, Okx:BTC-USDT-SWAP"

On disk and in the API a market is named by its key, <Venue>_<SYMBOL>, for example BinanceUsdm_BTCUSDT or Okx_BTC-USDT-SWAP.

Retention

--retention-days applies to every kind of data:

Day segments older than the retention are pruned by the engine.
Hyperliquid day files older than the retention are deleted once an hour.
Option chain day files older than the retention are deleted once an hour.

No backfill

The recorder records only what arrives live. Nothing is backfilled from venue trade history: minutes missing after a start or a disconnect stay unrecorded, and clients show them as Unavailable.

--backfill-hours (backfill_hours in a config file) has been removed. A recorder or hub given it exits at start with a message; remove the option.

Changed day segments are written every --save-secs seconds. The heatmap snapshot is not served, so the recorder writes it only on exit. Hyperliquid level runs and footprint minutes that closed since the last save are appended to their day files on the same interval.

Option chains are not held back for a save: each chain is appended to its day file as soon as it is taken, once a minute.

On SIGINT the recorder ends every open Hyperliquid run, saves everything and exits.

Hyperliquid budgets

Hyperliquid documents a limit of 1 200 request weight per minute per IP. A position read (clearinghouseState) weighs 2 and an order read (frontendOpenOrders) weighs 20.

Budget	Default	Reads
`--hl-state-per-min 600`	600 weight per minute	5 position reads per second
`--hl-orders-per-min 1200`	1 200 weight per minute	1 order read per second

The defaults are about a third of what passed in measurements. A refusal (HTTP 429) empties the affected budget and pauses it for 60 seconds. See Hyperliquid.

Caution

Raise the budgets only if the recorder has its own IP. Other Flowscope clients on the same IP share Hyperliquid’s limit.

Examples

Record ETH on three venues for a year, reachable from the network:

Terminal

flowscope-recorder \
  --markets BinanceUsdm:ETHUSDT,Bybit:ETHUSDT,Okx:ETH-USDT-SWAP \
  --dir /var/lib/flowscope \
  --listen 0.0.0.0:8787 \
  --retention-days 365 \
  --hl-coins ETH

The same with environment variables, for a service manager:

Terminal

FLOWSCOPE_RECORD_MARKETS=BinanceUsdm:ETHUSDT,Bybit:ETHUSDT,Okx:ETH-USDT-SWAP
FLOWSCOPE_RECORD_DIR=/var/lib/flowscope
FLOWSCOPE_RECORD_LISTEN=0.0.0.0:8787
FLOWSCOPE_RECORD_RETENTION_DAYS=365
FLOWSCOPE_RECORD_HL_COINS=ETH

Record markets without Hyperliquid positions:

Terminal

flowscope-recorder --markets BinanceUsdm:BTCUSDT --hl-coins ""

Record only BTC’s option chain, or none:

Terminal

flowscope-recorder --options-coins BTC
flowscope-recorder --options-coins ""

Warning

The HTTP server has no authentication and no TLS. Bind it to 127.0.0.1 and put a reverse proxy in front if clients connect over a network. See Deployment.