Skip to content

How-To Guides

Solve specific problems. Assumes you know the basics.

Project setup

Guide Problem
Scaffold a project (flox new) Bootstrap research / live / indicator-library projects from a template
Project layout What a scaffolded project contains and where each piece belongs
Strategy classes Structure strategy code idiomatically
Strategy hot-reload Swap a strategy at runtime without dropping connections
TypeScript strategy authoring Write strategies as TS classes with @strategy / @onTrade decorators
CCXT adapter Connect to an exchange via the CCXT bridge

Backtesting and analysis

Guide Problem
Backtesting Run strategy backtests on historical data
Realistic backtest in one call Venue-typed factory that wires executor, account, fees, funding, liquidation, and rate limits
Backtest recipes Runnable end-to-end recipes for the common backtest assembly patterns
Sweep a signal over a tape Monomorphic replay for indicator studies and parameter sweeps
Realistic fills Slippage, queue position, partial fills
Record and replay tapes Capture live market data to .floxlog, replay deterministically
Run a paper engine (flox engine sim) Replay a tape through a strategy behind a control server an agent can drive
Merge multiple tapes on read Cross-exchange research over N tapes with symbols rekeyed into one global id space
Aggregate tape events in a single pass Run a panel of streaming aggregators over a tape without materialising it
Import Binance public archives Convert data.binance.vision aggTrades zips into a .floxlog tape
Import Binance book archives Convert bookTicker / bookDepth zips into delta-encoded book events on the same tape
Import multi-exchange archives Binance / Bybit / OKX / Bitget / Deribit public archive importers
Iterate the order book from a tape Reconstruct ladder state per bucket or at a chosen instant for offline book analysis
Rolling top-K thresholds Vectorized sliding K-th-largest for extreme-event filters at any timeframe
Cross-sectional panel builder Aligned (T × S) close / OHLC / returns panel over N floxlog tapes
Delta book compression Shrink L2 tapes 10-30x by emitting only the changed levels
Record a strategy run as .floxrun Capture signals, orders, and fills as a per-run trace alongside the tape
Capture a strategy run automatically with .floxrun TraceSignalHandler + TraceExecutionListener adapters; no per-strategy instrumentation
Inspect a tape and run in the replay viewer Single-page UI for scrubbing through a captured tape and strategy trace
HTML report Render an equity curve + trade table to one HTML file
Interactive backtest Inspect state mid-run from a notebook
Grid search Sweep parameters over a backtest
Walk-forward Out-of-sample validation with rolling / anchored folds
Heatmap SVG heatmap from a 2D parameter sweep
White's reality check Multiple-comparison-aware significance test
Log to MLflow Send a backtest run + artifacts into an MLflow tracking server
Backtest an LP position Run a concentrated-liquidity position through a pool tape
Choose a matching model FIFO, pro-rata, pro_rata_with_fifo, TOP-PRO-LMM, and priority-weighted matching
Read queue position from a strategy Queue-ahead / queue-total events off the backtest queue tracker
Estimate queue position from live events LiveQueuePositionEstimator over live trade + book feeds
Calibrate the live queue estimator Fit half-life and shrink factor against observed fills
Attribute hidden / iceberg flow Stop counting hidden fills as cancellations in the queue estimate
Detect an empty price level Fire when a resting order is alone at its level
Track a resting order's market position Categorical best / behind-best / mid-spread / crossed transitions
Read maker / taker on a fill Fill-role classification and why it drives the fee ladder
Per-stage order timestamps Submitted / accepted / first-fill / cancelled / rejected snapshot per order
Record and analyse order journeys OrderJourneyTracer for post-trade latency and cancel-race forensics
Apply a named latency profile Canned per-venue ack-latency defaults
Ack-latency distributions Lognormal / empirical draws with burst correlation instead of a scalar
Model submit-side ack latency Defer ACCEPTED so the submit race is reproducible
Model cancellation ack latency Reproduce the lost-to-fill cancel race
Model order replace acknowledgement The three-event async replace sequence and the late-replace race
Simulate venue downtime Maintenance windows, random disconnects, and buffered request flush
Model venue rate limits Per-endpoint budgets and rejection behaviour
Model volume-tiered fees 30-day rolling VIP ladder for maker / taker rates
Model perpetual funding Funding schedules, per-symbol tapes, and settlement bookkeeping
Model liquidation and ADL Cascades, insurance fund, ADL ranking, mark impact
Cross-margin accounts Shared-equity account with per-symbol marks and maintenance margin
Self-trade prevention STP modes and account groups in the simulator
Price options and back out IV Black-Scholes, implied vol, SVI surfaces, and the vol cone
Compute option greeks First- and second-order greeks

Live trading

Guide Problem
Advanced orders Stop-loss, take-profit, brackets
Submit a native bracket order One entry plus linked TP / stop children with OCO semantics
Submit a native iceberg order Visible slice, hidden remainder, refresh latency and size randomisation
Extended TIF and reduce-only ioc / fok / gtd / post_only and the reduce-only flag
Replace a leg of an active OrderGroup Re-price one basket leg without tearing down the group
Multi-exchange trading Aggregate books and route across venues
Price a DEX swap Constant-product and concentrated-liquidity quote maths
Route, arb, and ingest DEX pools Multi-hop routing, arb detection, and pool-tape replay
Price and backtest DEX pools on Node The same AMM surface from the Node binding
Inspect a running engine over MCP Read positions / PnL / kill-switch from a running engine via an AI client
Paper trading Drive a strategy off live data but route orders to a simulator
Reproducibility bundles Pack strategy + tape + expected output into a single tarball; replay byte-for-byte
Control a running engine over MCP Send place / cancel / flatten / kill-switch from an AI client over a token-scoped HTTP control plane
Live engine analytics over MCP Read-only introspection of a running engine: list strategies, walk causal chains, replay-with-overrides
Lookahead-bias detector Static-analysis lint that flags .shift(-N), forward-index arithmetic, future-named attributes
Portfolio-level risk aggregator Combine PnL and exposure across N strategies; portfolio-level kill switch on drawdown / loss / gross / concentration
Backtest with latency Add feed / order / fill latency samples to a backtest for HFT-grade fill realism
Execution algorithms TWAP / VWAP / Iceberg / POV slicers that work on top of any executor
RL environment Gymnasium-compatible env over a flox tape for training RL agents

Indicators and aggregation

Guide Problem
Add an indicator Wire a custom indicator into a strategy
Indicator graph Compose indicators into a DAG
Multi-symbol indicators One indicator across many symbols
Cross-symbol indicators Indicators over two synchronised symbol streams — correlation, hedge ratios, benchmark regime filters
Read multi-timeframe context from a strategy last_closed_bar(symbol, tf) + last_n_closed_bars(...) ring helpers
Compose multi-symbol multi-TF entry conditions declaratively when(self, btc, H4).ema(50) > when(self, btc, H4).ema(200) composable DSL
Submit a multi-leg order group Bundle pair-trade / basket legs under one parent_signal_id with status + cancel
Wait for multiple feeds with a known staleness budget MultiFeedClock with WaitForAll / FireOnAny / LeaderFollower policies
Bar aggregation Pre-aggregate bars for fast backtesting
Custom bar policy Hand-roll a new bar aggregation rule
Volume profile Build a volume profile from trades

Performance and project

Guide Problem
Optimize performance Tune for minimum latency
CPU affinity Pin threads to isolated cores
Configuration Runtime configuration options
CI configuration Understand the CI pipeline
Custom connector Add a new exchange to the connector tree
Contributing Contribute to FLOX development

Prerequisites

These guides assume you've worked through the tutorials and understand the core FLOX concepts.