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.7.0.tar.gz (424.2 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.7.0-cp313-cp313-win_amd64.whl (1.5 MB view details)

Uploaded CPython 3.13Windows x86-64

flox_py-0.7.0-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.7.0-cp313-cp313-macosx_14_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

flox_py-0.7.0-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.7.0-cp312-cp312-macosx_14_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

flox_py-0.7.0-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.7.0-cp311-cp311-macosx_14_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

flox_py-0.7.0-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.7.0-cp310-cp310-macosx_14_0_arm64.whl (1.8 MB view details)

Uploaded CPython 3.10macOS 14.0+ ARM64

File details

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

File metadata

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

File hashes

Hashes for flox_py-0.7.0.tar.gz
Algorithm Hash digest
SHA256 70ac29a6cb761b5f0b1cb7eef2606375b7ba8f84b95226f727dacb108dcaf18a
MD5 ef3e32af5b27f0266ac19501c62184ab
BLAKE2b-256 55b2da7060685cfd6771a87ae952767d9d7bc59639fa9f3a182aaf576103e4d8

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0.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.7.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.7.0-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/7.0.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.7.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 a76bdbafc3cbbc743b6aa7f15b1988fc256e214da2d6b501a0d7fdabe018b88e
MD5 1099b1708fc99d648cbc39e112095e66
BLAKE2b-256 556f7b483ff9291fd3d8918ba35ec6b0fadf28c3e4733c0e7bd0f23170a29a35

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 acdd3dc1533d6ad16709f081b4bcd3a511cead98cf5ba8290a22eca8e2eed186
MD5 abc554e06951cfb9ead46fc47bc6ba5e
BLAKE2b-256 a031395501b827886814169b1e144c41d57c9d0d91607437019a0d67e749b415

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp313-cp313-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 9dd340a02ade80c9986ea0e7938804faa125b89579aaed8688ea5bf526ebe184
MD5 4f9e3a16c0254ac7cb56133311badedd
BLAKE2b-256 62db2ed883a734b4bcca98949867108e7b00f451924e47f2e93a248cfcdb0ae5

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.7.0-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/7.0.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.7.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 b8e45b5c8411eb34fe3e73cf32a9ab7855a0bcdb7b77e1bb39d99cdf6910b347
MD5 089919330443174f192b9a4275c17015
BLAKE2b-256 8b12ddbf4725483a0f91df0182801754b8588447e80ccb71dd6e551d7687399f

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 89b42af8e3564359b752210c12bd65739a5aaf0a03961e3c3af3420d4c8edf64
MD5 a7245bb4a5dd0b452abb64625a9d8c00
BLAKE2b-256 e46ef67a8e86729db32c95af7e87dd0926a88ab09ec370e0f5f951565694bca4

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp312-cp312-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 3d627df2ca5e012152f28146a4a1ce381ad67f073315f4ea926b39a1f75c6064
MD5 b0e8cf7120b77537a1f633865882765e
BLAKE2b-256 f0de888f5a3f2bf9da2140b38bccaf0eb0cfbd5babf92483ad9c168729447623

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.7.0-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/7.0.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.7.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 ea0fd8a7a55b28d0b26db591d4a358d61759f3d743c660e41222f167a13c2a2c
MD5 a53d2152087c43d9561848f0f0c37abd
BLAKE2b-256 77527750088e83668949e5542559fbb39f827989eb31a0c2f5a2e68220f9f69b

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 48bbbd7c7f14f2f8f5d0bcb90107566d2ab4873629b1bf42861c61236fa681fd
MD5 eec830318507b73f9367114c6727ada8
BLAKE2b-256 31ee85a9ee8217836dd2d546f59411a02e77ed58efec972e59aa51839151a39d

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp311-cp311-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 f51a899b3733fa556e11dfe45a685b0c205c377975f7ab43902e6f040bffc267
MD5 d29f43cea3fcb3f210759e5e5f31e1ed
BLAKE2b-256 fecb2652860edec59fa22f2c33aaa98710496530e8c5fe15af3e80799b36e5fb

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: flox_py-0.7.0-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/7.0.0 CPython/3.13.14

File hashes

Hashes for flox_py-0.7.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 f0bc936cc7463aa64d9fc3bbca882862ce3baa9b621659e5d3c03ee497210eb3
MD5 b59b987788b6b9bd0093364053b91d08
BLAKE2b-256 5bb7ecda691508da27c7deb766269f7690482b8e5f63537970acefa70e7a6160

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 8d3c1c6f905f3492931f9b7a7aed2fb1ef9c6129e655fafb62d90fe27bed3f74
MD5 14c85ac84c456418fc7a71a08b8cc7aa
BLAKE2b-256 69176c86a61850b40c6ae9a1606728ea0bef36eff2e32caf49be7f7a1e19bb38

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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.7.0-cp310-cp310-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for flox_py-0.7.0-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 f4a614f2059c9ad265d95a53a3b64565475f081aa341916fbac9548a81e3837c
MD5 d855ca79518468a65aeef8c41e069ee9
BLAKE2b-256 8f174943319e9e58fd843212712f4a366f514e034258f4f3499d6a428b1b792b

See more details on using hashes here.

Provenance

The following attestation bundles were made for flox_py-0.7.0-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