Skip to main content

flox-py

Python bindings for FLOX — an AI-native framework for building trading systems.

AI agents discover the surface and drive it end-to-end through an MCP control plane. One strategy class runs backtest, paper, and live.

Install

pip install flox-py

Scaffold a new project

flox new my-strategy                                   # research scaffold (default)
flox new my-bot --template=live                        # live trading via CcxtBroker
flox new my-indicators --template=indicator-library    # publishable indicator package
flox templates                                         # list templates

flox new ships with the wheel; see docs/how-to/flox-new.md for what each template lays down.

Quick start

import flox_py as flox

registry = flox.SymbolRegistry()
btc = registry.add_symbol("binance", "BTCUSDT", tick_size=0.01)

class SMACross(flox.Strategy):
    def __init__(self, symbols):
        super().__init__(symbols)
        self.fast = flox.SMA(10)
        self.slow = flox.SMA(30)

    def on_trade(self, ctx, trade):
        f = self.fast.update(trade.price)
        s = self.slow.update(trade.price)
        if f is None or s is None:
            return
        if f > s and ctx.is_flat():
            self.market_buy(0.01)
        elif f < s and ctx.is_long():
            self.close_position()

def on_signal(sig):
    print(sig.side, sig.order_type, sig.quantity, sig.price)

runner = flox.Runner(registry, on_signal)
runner.add_strategy(SMACross([btc]))
runner.start()
# feed market data:
# runner.on_trade(btc, price, qty, is_buy, ts_ns)
# runner.on_book_snapshot(btc, bid_prices, bid_qtys, ask_prices, ask_qtys, ts_ns)
runner.stop()

Run a paper engine in one command

For tier-5/6 control (live order placement, position queries, kill switch over HTTP), flox engine sim boots a Runner + SimulatedExecutor + ControlServer + state-snapshot writer:

flox engine sim --strategy strategy.py --tape ./tape

Prints the engine URL and a copy-pasteable flox-mcp init --engine-url URL --token T command for wiring into AI tools.

AI companion

flox-mcp is a Model Context Protocol server that gives coding agents (Claude Code, Cursor, Cline) grounded access to indicators, error codes, the C-API surface, and full-text doc search:

pip install flox-mcp
flox-mcp init           # writes ./.mcp.json for the current project

See the flox-mcp README for the tool list.

Symbol and SymbolRegistry

registry = flox.SymbolRegistry()
btc = registry.add_symbol("binance", "BTCUSDT", tick_size=0.01)

btc.id        # int, e.g. 1
btc.name      # "BTCUSDT"
btc.exchange  # "binance"
btc.tick_size # 0.01

int(btc)   # 1
print(btc) # Symbol(binance:BTCUSDT, id=1)
# Symbol objects work transparently as int anywhere an ID is expected

Strategy

Subclass flox.Strategy and override the callbacks you need.

class MyStrategy(flox.Strategy):
    def __init__(self, symbols):
        super().__init__(symbols)   # symbols: list[Symbol | int]

    def on_start(self): ...
    def on_stop(self): ...

    def on_trade(self, ctx, trade): ...      # ctx: SymbolContext, trade: TradeData
    def on_book_update(self, ctx): ...
    def on_bar(self, ctx, bar): ...

    # Order-event hooks (fires on the strategy's own emitted orders).
    def on_fill(self, ctx, ev): ...           # status PARTIALLY_FILLED or FILLED
    def on_order_update(self, ctx, ev): ...   # every status change including fills

Order emission (shorthand, uses first symbol by default)

Method Description
market_buy(qty, symbol=None) Market buy
market_sell(qty, symbol=None) Market sell
limit_buy(price, qty, symbol=None) Limit buy
limit_sell(price, qty, symbol=None) Limit sell
stop_market(side, trigger, qty, symbol=None) Stop market
close_position(symbol=None) Close position (reduce-only)

SymbolContext

Property Type Description
position float Current position quantity
last_trade_price float Last trade price
best_bid float Best bid
best_ask float Best ask
mid_price float Mid price
is_flat() bool No position
is_long() bool Long position
is_short() bool Short position

TradeData

Property Type Description
symbol int Symbol ID
price float Trade price
quantity float Trade quantity
is_buy bool Buy-side aggressor
timestamp_ns int Timestamp (nanoseconds)

OrderEvent (passed to on_fill / on_order_update)

Property Type Description
order_id int Engine order ID
status str "FILLED" / "PARTIALLY_FILLED" / "REJECTED" / "CANCELED" / ...
side str "buy" or "sell"
fill_qty float Last-fill quantity
fill_price float Last-fill price
reject_reason str | None Set when status == REJECTED

Runner

runner = flox.Runner(registry, on_signal)                  # synchronous
runner = flox.Runner(registry, on_signal, threaded=True)   # Disruptor background thread

runner.add_strategy(strategy)
runner.start()
runner.on_trade(btc, price, qty, is_buy, ts_ns)
runner.on_book_snapshot(btc, bid_prices, bid_qtys, ask_prices, ask_qtys, ts_ns)
runner.stop()

The on_signal callback receives Signal objects:

Property Type Description
side str "buy" or "sell"
quantity float Order quantity
price float Limit price (0 for market)
order_type str "market", "limit", etc.
order_id int Internal order ID

BacktestRunner

bt = flox.BacktestRunner(registry, fee_rate=0.0004, initial_capital=10_000)
bt.set_strategy(MyStrategy([btc]))

stats = bt.run_csv("data.csv")             # auto-detects symbol from registry
stats = bt.run_csv("data.csv", "BTCUSDT")  # explicit symbol name
stats = bt.run_tape("./tape")              # replay a recorded `.floxlog` directory

equity = bt.equity_curve()   # numpy arrays: timestamp_ns, equity, drawdown_pct
trades = bt.trades()         # numpy arrays: per-trade detail

from flox_py.report import write_html
write_html("report.html", stats=stats, equity_curve=equity, trades=trades)

The same risk-gate stack as the live Runner plugs into the backtest. Reduce-only / flatten orders bypass the gate by design (so a tightening cap cannot strand a position):

bt.set_risk_manager(my_risk_manager)        # IRiskManager: .allow(order)
bt.set_kill_switch(my_kill_switch)          # IKillSwitch: .check(order), .is_triggered()
bt.set_order_validator(my_validator)        # IOrderValidator: .validate(order, reason)
bt.set_pnl_tracker(my_pnl_tracker)          # IPnLTracker: .on_order_filled(order)

Stats dict

Key Description
return_pct Net return percentage
net_pnl Net P&L after fees
total_trades Round-trip trade count
win_rate Winning trade fraction
sharpe_ratio Annualized Sharpe ratio
max_drawdown_pct Peak-to-trough drawdown (%)

Walk-forward and grid search

wf = flox.WalkForwardRunner(
    registry, fee_rate=0.0004, initial_capital=10_000,
    mode="anchored", train_size=180, test_size=30,
)
wf.set_strategy_factory(lambda fold_idx: MyStrategy([btc]))
folds = wf.run_csv("data.csv", "BTCUSDT")

grid = flox.GridSearch()
grid.add_axis([5, 10, 20])    # fast period
grid.add_axis([30, 50, 100])  # slow period
def factory(params):
    fast, slow = params
    bt = flox.BacktestRunner(registry, fee_rate=0.0004, initial_capital=10_000)
    bt.set_strategy(MyStrategy([btc]))  # configure with fast / slow as needed
    return bt.run_csv("data.csv", "BTCUSDT")
grid.set_factory(factory)
results = grid.run()    # list of {index, params, stats}

Render a heatmap with flox_py.report.heatmap_html(...) / write_heatmap(...). Run a multiple-comparison-aware significance test with flox.whites_reality_check(returns, num_bootstrap=10_000).

MLflow

from flox_py import mlflow as flox_mlflow

flox_mlflow.log_backtest(
    stats, equity_curve=equity, trades=trades,
    params={"fast": 10, "slow": 30},
    run_name="sma-2025-01",
)

mlflow is optional — install with pip install mlflow.

Modules

Module Description
Strategy / Runner Event-driven live and backtest strategies
Engine Batch backtest engine (signal arrays, parallel runs)
Indicators EMA, SMA, RSI, MACD, ATR, Bollinger, ADX, Stochastic, CCI, VWAP, CVD, Correlation, AutoCorrelation, and more
Aggregators Time, tick, volume, range, renko, Heikin-Ashi bars
Order Books N-level, L3, cross-exchange CompositeBookMatrix
Profiles Footprint bars, volume profile, market profile
Positions Position tracking with FIFO/LIFO/average cost basis
Replay Binary log reader/writer, market data recorder

All compute-heavy operations release the GIL for true parallelism.

Full API reference at flox-foundation.github.io/flox/reference/python.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flox_py-0.6.8.tar.gz (420.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

flox_py-0.6.8-cp313-cp313-win_amd64.whl (1.5 MB view details)

Uploaded CPython 3.13Windows x86-64

flox_py-0.6.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

flox_py-0.6.8-cp313-cp313-macosx_14_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

flox_py-0.6.8-cp312-cp312-win_amd64.whl (1.5 MB view details)

Uploaded CPython 3.12Windows x86-64

flox_py-0.6.8-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

flox_py-0.6.8-cp312-cp312-macosx_14_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

flox_py-0.6.8-cp311-cp311-win_amd64.whl (1.5 MB view details)

Uploaded CPython 3.11Windows x86-64

flox_py-0.6.8-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

flox_py-0.6.8-cp311-cp311-macosx_14_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

flox_py-0.6.8-cp310-cp310-win_amd64.whl (1.5 MB view details)

Uploaded CPython 3.10Windows x86-64

flox_py-0.6.8-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (2.7 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

flox_py-0.6.8-cp310-cp310-macosx_14_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.10macOS 14.0+ ARM64

File details

Details for the file flox_py-0.6.8.tar.gz.

File metadata

  • Download URL: flox_py-0.6.8.tar.gz
  • Upload date:
  • Size: 420.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.6.8.tar.gz
Algorithm Hash digest
SHA256 3b04af7f56aa82e4319b5b09cb2e96871675ef0a34a2606711a17f112ea75b96
MD5 6ac583ccbe08f2da6bead4b3407d8665
BLAKE2b-256 5240e98586c56ddab39bbb4800fd429af578c7415661bea1514a218cb46fd10d

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8.tar.gz:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.6.8-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 1.5 MB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.6.8-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 4046c7aff4f1f3188785f20a9ab508bb4031b2d01b44400682f57522af19b84d
MD5 4051ac5c27d9078d4b75f0d4b22ba2f6
BLAKE2b-256 1d61eaeb95b5fb1ca78826acb906f0081d5ee4bca4086c0f06c228c361af0952

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp313-cp313-win_amd64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 cb2264bb6933e8e4473a750afe34684a6dae793b0a2a4d77b9d9da3dde83993b
MD5 bc486793281d15ea0df90c52d3b37c8b
BLAKE2b-256 d5591d28f5300e309cf6d742366e6f6be2d894b61753414513a753683d0e3ca8

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 1e3fc5f9ba3d0e22ea1a482099f1304714563dc71c8e6eaf5999f4927c27c5e6
MD5 eb093a8047b8451a29730d8d2cd2816f
BLAKE2b-256 5c03d42eae22aaaf5e4a9e9fbaa0bb59ffe875f6e2c3b9b64b16b8acb39f4c60

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp313-cp313-macosx_14_0_arm64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.6.8-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 1.5 MB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.6.8-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 acfcfb161ca0016f7ee339e6702e57bed1a3cfe1da685858e7c8aeaf416d929d
MD5 5ee8798fe55f4283dad0f042bbc93543
BLAKE2b-256 6cce71ec6ecfdb30fdc889678ce1eea9264e5d3d119ecd0298e709f76a45e5ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp312-cp312-win_amd64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b55117c4d4783b633ba0d1e1ee32ef549c3978add21e4060313765b3d3a5fd34
MD5 0861fe84afa5868d813ef5cc1ab5d17c
BLAKE2b-256 77092a9c4fa0ff3952a0a5dd4ea0c2a7a6d6699205b3effccd11b8fd6bd0ac18

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a94b5cc5571d6d454d4b0102e16c8308c0b729b7bd90d767b2a527a40eefe6e0
MD5 1324353b249e07cebafbffd8162040fa
BLAKE2b-256 c876d49df4f374cebd6ade28862a231dd57467851d80b360fa48058b659749d7

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp312-cp312-macosx_14_0_arm64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.6.8-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 1.5 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.6.8-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 a0d142dc51a842593c00699b7f70d3962e51b9a91921995aa18085d2ab630d40
MD5 19e1aba00c081fe2fbf748c22ab26b63
BLAKE2b-256 4894d27aa144cd5794109b989f4bd80b4aff01535e1c94bc95b5ef4745d64239

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp311-cp311-win_amd64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 ab7747d3567afb40534f358bd067cab662d57a7bb94fbaa33ca7d7d758bb9d47
MD5 21d2b6c7ac36ffd2081bc44ba83fab2e
BLAKE2b-256 640a0622cb8871428d50cde83fa3bee7e3562cc277424ce9fbf153778aa67fb7

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 209a21352f70759089a3b30e1256eb16b4cf708b351a87a91952c82f5ff0c5d0
MD5 c7b176f6443dc9191f524c543c8dd805
BLAKE2b-256 ff322d40b84f71280a4dabd1d7a0ced742ec0d836985e60fd5415d63f0bb1f46

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp311-cp311-macosx_14_0_arm64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.6.8-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 1.5 MB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.6.8-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 771be34ec87e39a3e8ae033c168525c66a08fa73a06dbabe63b3b06fe5fc688f
MD5 c822bba44da742bd5194fa3f72d043ea
BLAKE2b-256 fc0bb71dfc01943c528576f59f570f6de47f020fdf20d428f10ede6b57532adb

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp310-cp310-win_amd64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 32e22dce2b45e22b428c4a867db1f462a8c9ee8be6b776aa21b820e9b3b96480
MD5 399daa86bdf62a87d2c2d1dd3803c5ac
BLAKE2b-256 0ec46c9465fdd58967a2e2e9d1fa9fea0227bc95c743926ac1a7797f62b646f8

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flox_py-0.6.8-cp310-cp310-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.6.8-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 f1ad86ae35809b352f2c27c631f979bbeeb22f74825b4af887deddfe944fa5c1
MD5 003422980a318142d73b5f17daff5aca
BLAKE2b-256 3d5f13e394d4a377d6bd8e58f144175b5d4301937d68817ca6d501a69ce89d82

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.6.8-cp310-cp310-macosx_14_0_arm64.whl:

Publisher: python-wheels.yml on FLOX-Foundation/flox

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page