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

Uploaded CPython 3.13Windows x86-64

flox_py-0.6.7-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.7-cp313-cp313-macosx_14_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.13macOS 14.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

flox_py-0.6.7-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.7-cp312-cp312-macosx_14_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.12macOS 14.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

flox_py-0.6.7-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.7-cp311-cp311-macosx_14_0_arm64.whl (1.7 MB view details)

Uploaded CPython 3.11macOS 14.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

flox_py-0.6.7-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.7-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.7.tar.gz.

File metadata

  • Download URL: flox_py-0.6.7.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.7.tar.gz
Algorithm Hash digest
SHA256 c7ea90af4884a6437ad87353d145e84d982bccf497f2b11dbf9e41adcea82608
MD5 20fc5c3ab057dd8c34b15c683299c2ce
BLAKE2b-256 dafbebb5e0783dc040035079a85f9570455cde31ab1ec231b741e2d72748a71b

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.6.7-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.7-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 7889a04d749c41e6c2e4bcaaeea08c9a44e6cc2f7bcfb690f8c92cab530c4f08
MD5 bc63e713bac691ef0232a3517f89aa76
BLAKE2b-256 f64967ec22d8e3059c51a6e6ca2d6f2dbdb1caea310e307ac9b8f9165b5dab7c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b3a9ec87d62a858dc182eba8a2eafa20f1688849683511ee098c3a7fa31f1193
MD5 4ebb0ac0ad5ff081f4b464e502e03219
BLAKE2b-256 48268e461e787f2183d82dbbd333639283c0f30279b62a7d4a335c157927f5a2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 835d262c86e6093a8c6d7b0731402d2b310a7d155be03fa63354709a919c0433
MD5 b4d33ffea0b200b258b2f93973f3e3c0
BLAKE2b-256 a91496ce63ca3a14dc64437104e42b8b078261698a925ee97ccff02051f00957

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.6.7-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.7-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 41a1eb387e58e488a53d01ad8db2500e75abf7ea30016c79bb6bbbcea0a2a31b
MD5 81547a6824a60f115351036a266aeccc
BLAKE2b-256 b3a36903ce87108b35ad050e801f26f1d7cb3c0fad6c002e06c1db53c72a90a6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a5f93f9398639339742dd53f2a0ae7646770c47158753152610495e14a0d7c02
MD5 739679c3a5f79dc3821ef777571ae840
BLAKE2b-256 4e699602526bae9ea6becd8b9dcad3e73d28d42bdc3da07ff96fbe493fc39720

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 74238a7cf4e12e577b35ab468db3df3a641d26e2008742bdb29f02d0ba50db14
MD5 8ba681b4593d0f8b5cbc57f52bddb68e
BLAKE2b-256 23ddf6feafd3ac10a04f1d300d04cf3059f088354920d7332144676f66d84b6e

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.6.7-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.7-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 90af7d085d4f33719196514e3804e25bcfec532228e0b5407ac63f16b47d98a4
MD5 a1c2e2dd67e142f71575bfa0a6e3d81b
BLAKE2b-256 7c81610baeb766c854c80e481f7760d4290280781b12588ef11b07f573ad5f91

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 a63616d182576e2ddcd7331f7b74733ce331967e8f17e1c1f5b1799860b3a663
MD5 b35a37fe75a06a96c32b326a0742f3c0
BLAKE2b-256 18ce642701b9f8d449c8285259ef157c04796d9b3e9862c8dc915386f8cdb83b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 fbaf89e01d6d5581c6533d0e5e18a36deda7b83f1e92428cb6fcc091572ddcf3
MD5 ef0213c51d9b0734aaade90f9715b9b3
BLAKE2b-256 13b26fa8e5875d3e2ed0dc5237f0805b458f2aee6e23e2832da1467e7f8c7180

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.6.7-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.7-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 f719551651171599a282d8ca097363100863fc81f582659f530d4bacac6abb82
MD5 c7f7e5d7654d787f55e18579f831129f
BLAKE2b-256 f6850f6f6df92b1b76d10a9d9bccb65df39d51a4ea33fda0df9d770caf424a71

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e978f971518bf7f6d2f2619c41f195f2cc68492cf9dc8d3bdff01905da3e36bb
MD5 88496c37ad0ed64db2e0b5e7b360bb2e
BLAKE2b-256 c46cd2b8618812c4d26c5d3fd9de65d296120715866a864e6d3b736ea9b61d34

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.6.7-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 05025d71f2c2839fdf993635d98b82abb03e95ea19e109de3d4e3bd8b035c8ac
MD5 8f403ecde8239df2d16de69e0a02f6d4
BLAKE2b-256 a7fb423948a204c515d89b4b2c5ae999c11240b8f875c3ab2b60e8c4c49857d0

See more details on using hashes here.

Provenance

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