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

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.13macOS 14.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.12macOS 14.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.11macOS 14.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

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

File metadata

  • Download URL: flox_py-0.7.1.tar.gz
  • Upload date:
  • Size: 424.7 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.1.tar.gz
Algorithm Hash digest
SHA256 801d56d4cec63b635f5401113fa5841d6ad609acb79c52915f1652d58bb4173b
MD5 1a1e3e2f7a537cea19330927b9b835cd
BLAKE2b-256 29a175e343373d39e6ce20c34768c16175f1a0235c9f6e8285f1d165de31fa75

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.1-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.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 33ff72ce9f078e6e3f5641f50a3bb1defe5654e4ca5c3b0ec1f405cc52814141
MD5 1462d80500e44e1befe7b3ab2fb660f2
BLAKE2b-256 3115bea0bb232e4035ff2ba0ed2875b06f5eac694945c9753260bd48e049aa36

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 8977d2e624dbb7e31a20859c0a30b9527ff8ef14f49f3858130be0a5c46a5a01
MD5 69ccd4faabbec54532abf62f0e802b9d
BLAKE2b-256 27bc97afb928ce980648def9b04a6caba76792a30f4c2b5fe649f97ca70ad7e9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 33571daafe5c1e82815946158633057f04e5d4ff7d0ca39fa673c59f94263fc3
MD5 4f50ea0d442879e74c7a4fb9536e8b51
BLAKE2b-256 30293909687b9aef416a47567ee42dbae17bfc301d72cb44369f9d86e51b69d5

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.1-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.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 2e70d4f73b2ec230d6e35a89fb284e2df7d3f0d41c8680ead326582a0713a524
MD5 15ad0e919f8c16b06b361018dabe3a31
BLAKE2b-256 5a63adcdfcc4edec000c5a869f0cf16c28691059e5f5c053024a90e39a291915

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0136d5ddd4fea1f710737438fcb33d38fa08538d25faf1eb0b272f5bff896590
MD5 847f4315a6959c94089dc63938966b32
BLAKE2b-256 66a35e902f4447b091e8315df64d24b559acdd199b06764d1788b39da02fbd53

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a11278c646e811d96f16bbdd86f348cfba82a75805105b48fb1f9c1b4d9ea0a0
MD5 61dc4918e7f6bb2269b729f728a51e43
BLAKE2b-256 563b4cd3ea7365cb9b3c499c9d9fe523b57575e3ad46667d80c90c581f74859e

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.1-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.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 13b9dabb9222f46a0ddff93b14dcfcb22aafbdc0d148ee7fd1e6a95263c04b89
MD5 012e333549321370997cee511e82d8ae
BLAKE2b-256 17f973b0c88dc678ac0490a7bbe1925d0f7fda59d8005a682c838bdf1e9deaad

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d4360ebe6f21adb467800b2ac1f1fa07319173e8069304afe9145182d5fc9d38
MD5 3f59a03de8ad357ef95ea112c924bad0
BLAKE2b-256 e1f1810109b7773bcfd8a2098e5a133b4bf2c264ec28d60847279a2b98b799b3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 99ea3d9bc6557b972fd05cd5afa0bdeda76396e374ac0cb907b96ce2c13661d9
MD5 e5c15fcf73e92facae36129570c7539b
BLAKE2b-256 92ee23720a391b7c53f0f9b26d5384f2fba9b72354cca9918b8e991a7724b884

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.1-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.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 453a82fe5a83cb9c14ef774fb2c974744406bc44a1ea698f6d81b0830990a94c
MD5 5cfc39da63dd43d212bde64c2dabe006
BLAKE2b-256 02285480a6450b3cb3eb80a78e73a442c68426cb19d7ac886dee5b400827d983

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d8e041cc31391c2e02a59049682d471d66ddfb9f5ebb64c9f7485e068f3ca9c7
MD5 62192f6b01a477ab4b76b174e0dfb07c
BLAKE2b-256 eb045403c0fdca424aeb385bac26f777aaee8de2382883e1892391ab30e8f917

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.1-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 923ef8ea074e5448e9aecf29f4c1b53905029d02741cbad8e8f589d4f8b58142
MD5 7bc9ff88c648696ff66da025e69a764f
BLAKE2b-256 b8968b2200c89544c34bd6887348dc5e4958747c979ec8ee8e62f88c59f555d2

See more details on using hashes here.

Provenance

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