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

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.13macOS 14.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.12macOS 14.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.11macOS 14.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

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

File metadata

  • Download URL: flox_py-0.7.2.tar.gz
  • Upload date:
  • Size: 424.8 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.2.tar.gz
Algorithm Hash digest
SHA256 535fa3ede85dcf1b8b9ba8ac0ff048961c3a5470ed74a1db0ff24804c827470d
MD5 9467098b0949acd1e770d00f77e326d0
BLAKE2b-256 f60b88ffe42a35c46ae97249aa12658702418df0412455d9589b4949b195123d

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.2-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.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 999d3b7ddb46e77ba631cb611ef83f8aa75a8e8ff74a85368b15427782d8d53e
MD5 e91f28a1bf41b4c6d020b8b35b0857bc
BLAKE2b-256 7802299328479123595f25a50203ae15ac82e7316f8285f2f2baf1f352215d4c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2ce29898cdea0677d831cc9d54cd05c722ca5f03ea83a69ad1879c65b9de2766
MD5 a30cf5af8c2c30b7cf81fc8cae372e13
BLAKE2b-256 d9c7cafaef05462b44785ecea49a34b08db45000987fe8ea515467f5627b0ef3

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 38df5582acf3800005f0e994e8091917e702e931f835fa16ac32fc0633052a3f
MD5 bc4eab3f70d86764c24c2f8c85a25698
BLAKE2b-256 5a6a653011c4e37ebfd7ee8e28e3e943df02e8fbd7d1fdd7ab382f3cf4205a65

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.2-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.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 4e6a779b29d9f52808d3508d5e2c041c8868ef091a922f76b13fee319a200e74
MD5 bf11076277491ec32c874eb477b996d0
BLAKE2b-256 3e0375449805552b68d76b8f96ed6e640acc4bc909f2f8de1a8f02b06d45e03e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0c1e1d604008fb159db3cc04fe3420360539b48f29b775d368c979a9feacd3c2
MD5 6590807c79816407823112c48cb3a2af
BLAKE2b-256 6a84f2a42c222116926367487280e642a6ae99b7f87db6a8f66f5b536db6d587

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a45934b602e19df707c45f94380ab57846ac36bc5e7148b679a1d9d51f5320b0
MD5 0ffd6830349d63c5d659394d76ffde8a
BLAKE2b-256 016b10ee91263d11f3c0fd1f8f85203fffd0416d7551147a7081265d90b17ee5

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.2-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.2-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 a7c5d46fd337ad8dcff0a3d0bb9362444554b326d1d046c586d6eb65f5c5fc1e
MD5 c8039e1eb310343e25a8c8664ccadafe
BLAKE2b-256 eed650712b8f8dfcea1a5e2bdf66b3d4cae8ff9da45bbc142e5d891c27036123

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 61c6e6f4fab3c36c49ce11cb7d2bb7c3f6b4eac450a5562d875d323ff083d144
MD5 ad7e406a1a725569c792149766f9aa96
BLAKE2b-256 dba12801ea2fa12ce438050be097dd55bf9ed1420b0783f202db4a76d2e89cab

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 886deff8c2108e5802fc6dc71a981c550f3e66ee2f60fe49e25fdf6f619c4927
MD5 75928e1aecedd917a13dfb41dd84fe07
BLAKE2b-256 ea9bb9154aefee58aaf610ff46fa3559b852f4f6fe28565f8a74c72aa6d11ba6

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.7.2-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.2-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 5ba216770994d0bb618c3cac3ff13509456852a8ef391da7dcc90631ca08353e
MD5 c214e8b714cbaf48d06b324bf4248588
BLAKE2b-256 ff0ce63bc653659dbdeceaaf0846d02dd6ec4e333df0f40777e5c2ac0841daa2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 3257162a7284d5f03dedd06e5346e692a56f55b8153fca0875ab49c57beefc02
MD5 a879034c61a2095c67f36e101fd605f6
BLAKE2b-256 4f35246b7fe2c023232132d8edb05f805e6c580bafc89db06b22f12d3596ac21

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.7.2-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 f3f774ed0af2f0f534e49c5754a0778e827f882c2120b86504bd0ead146a625d
MD5 9e93b4b1fd6a0903794fdee75efec2b7
BLAKE2b-256 f0a5860a0ee186da2fdea7851c11562fb3f4e96207d00a5ed3273d7cb4a2b12e

See more details on using hashes here.

Provenance

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