Skip to content

FLOX

Strategy & Runner

FLOX-Foundation/flox

Strategy, Runner¶

const { SymbolRegistry, Runner } = require('@flox-foundation/flox');

SymbolRegistry¶

const registry = new flox.SymbolRegistry();

Method	Returns	Description
`addSymbol(exchange, name, tickSize)`	`Symbol`	Register a symbol
`symbolCount()`	`number`	Number of registered symbols

Symbol¶

Returned by addSymbol. Coerces to a number wherever a symbol ID is expected.

Property	Type	Description
`id`	`number`	Numeric symbol ID
`name`	`string`	Symbol name
`exchange`	`string`	Exchange name
`tickSize`	`number`	Tick size

const btc = registry.addSymbol('binance', 'BTCUSDT', 0.01);

btc.id         // 1
btc.name       // "BTCUSDT"
Number(btc)    // 1
btc + 0        // 1
btc.toString() // "Symbol(binance:BTCUSDT, id=1)"

Strategy object¶

A plain JavaScript object with callback properties.

const strategy = {
    symbols: [btc],   // array of Symbol or number

    onStart() {},
    onStop() {},

    onTrade(ctx, trade, emit) { ... },
    onBookUpdate(ctx, emit) { ... },
    onBar(ctx, bar, emit) { ... },
};

BarData (`bar`)¶

Property	Type	Description
`open`, `high`, `low`, `close`	`number`	OHLC prices
`volume`, `buyVolume`	`number`	Total / buy-side volume
`startTimeNs`, `endTimeNs`	`number`	Bar window timestamps (nanoseconds)
`barType`, `barTypeParam`	`number`	0=Time, 1=Tick, ... + interval/threshold
`closeReason`	`number`	0=Threshold, 1=Gap, 2=Forced, 3=Warmup

SymbolContext (`ctx`)¶

Property	Type	Description
`position`	`number`	Current position quantity
`symbolId`	`number`	Symbol ID
`lastTradePrice`	`number`	Last trade price
`bestBid`	`number`	Best bid
`bestAsk`	`number`	Best ask
`midPrice`	`number`	Mid price

TradeData (`trade`)¶

Property	Type	Description
`price`	`number`	Trade price
`qty`	`number`	Trade quantity
`isBuy`	`boolean`	Buy-side aggressor
`side`	`string`	`"buy"` or `"sell"`
`timestampNs`	`BigInt`	Timestamp (nanoseconds)

emit methods¶

Method	Description
`emit.marketBuy(qty)`	Market buy
`emit.marketSell(qty)`	Market sell
`emit.limitBuy(price, qty)`	Limit buy
`emit.limitSell(price, qty)`	Limit sell
`emit.cancel(orderId)`	Cancel order
`emit.closePosition()`	Close position (reduce-only)

Runner¶

Synchronous strategy host. Strategy callbacks fire in the caller's thread before the push call returns.

const runner = new flox.Runner(registry, onSignal);        // synchronous
const runner = new flox.Runner(registry, onSignal, true);  // Disruptor background thread

In threaded mode, events are published to a lock-free ring buffer and callbacks fire in a background C++ thread.

Method	Description
`addStrategy(strategy)`	Register a strategy object
`start()`	Start the runner
`stop()`	Stop and clean up
`onTrade(symbol, price, qty, isBuy, tsNs)`	Inject a trade tick
`onBookSnapshot(symbol, bidPrices, bidQtys, askPrices, askQtys, tsNs)`	Inject an L2 snapshot
`onBar(symbol, { open, high, low, close, volume?, ... })`	Inject a closed OHLC bar

symbol accepts a Symbol object or a raw number.

Signal callback¶

function onSignal(sig) {
    // sig.side       — "buy" | "sell"
    // sig.quantity
    // sig.price      — 0 for market orders
    // sig.orderType  — "market" | "limit" | "stop_market" | ...
    // sig.orderId
}