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

Uploaded CPython 3.13Windows x86-64

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

Uploaded CPython 3.13macOS 14.0+ ARM64

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

Uploaded CPython 3.12Windows x86-64

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

Uploaded CPython 3.12macOS 14.0+ ARM64

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

Uploaded CPython 3.11Windows x86-64

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

Uploaded CPython 3.11macOS 14.0+ ARM64

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

Uploaded CPython 3.10Windows x86-64

flox_py-0.8.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.8.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.8.0.tar.gz.

File metadata

  • Download URL: flox_py-0.8.0.tar.gz
  • Upload date:
  • Size: 425.0 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.8.0.tar.gz
Algorithm Hash digest
SHA256 d5ceaaebeb5e9ef49dd9790f93b7bcf4d4f13e11b13388dc64e2757badebf3db
MD5 6d0c052e8202f369b906093c921d0724
BLAKE2b-256 fdde226df7005d3ff2533a9f73ce4b34961b096c86f03adc3b032137dfb49656

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.8.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.8.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 a2ed25ad3b1edaca51958f1b5b052da23400e29559f420fa71eac7a507e408c4
MD5 5b8e1a02b65712c1a83bc60353c9e7af
BLAKE2b-256 aa74b78712cc396e849d9468dae1f8af99a8d81c74f47a780f782707a9c05ae0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 26e77e12a07e2ab8736e1f9ee5d0d74242026ca178e30a085f1ef821b69e7821
MD5 c6f069b626cce44e11b9d4080c862494
BLAKE2b-256 827ccafbd9f51e356e624cc8b8a3f4b809a8d08bbc7ef588f0210b6f51cd919d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp313-cp313-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 d996face0be104f8039da42f03577ba9caf5631e9ae6e996a7295c5d27e26b05
MD5 cccace9260ebd9e505a2046365b7b338
BLAKE2b-256 2728c51cd16ddece4cc1896ad9cd770794e4c52422c8a9dbecba3b22ce6c5454

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.8.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.8.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 2c2d0d8f0b41a3f1de681bb68469912567174245ad354a8f1f3d74118d5e0b3d
MD5 7bcff8c021cb395f3f8e135fc27a3837
BLAKE2b-256 1b93bd5e49bfa2bd08e0cdc9ec06834583e454783a809b78609a628281790901

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d4a889eb6bc753c5af52d357d6ad0f2ac78af0ab1d4f8586c36c48bdf8d3f096
MD5 a26b98da481f7ead3aaf54706bb73d95
BLAKE2b-256 4948de3b780482ddaedc84cd72a54d57982c8a69be1aaf7386fed3050fece5ca

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp312-cp312-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 4ab022598831aeb8970abb91fd028925ecf757fa7bf7b8d01a60b6de657abd03
MD5 6976e233d5b7b3d98e0c624c92ec58c5
BLAKE2b-256 5c4853d14553be053f498da30d879a38d271ddaea9253d6cb95c30983378c84e

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.8.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.8.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 cf7b4e39f526fcbda7cea331035ddb5ae7266a3edb655e9b50831aebc59d72a2
MD5 613cfd1ac271f54de64cc13e64e9fe20
BLAKE2b-256 9d86f739ae11a991800a027af06f14990053fb3b43420373fcb2fb8407507d16

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d771784c7fddb98a929e92e31d906796427cb66a8b5b796720ad1b6bb9a16964
MD5 3d1c226e30fe1a2984ea79c11cb1c392
BLAKE2b-256 1bbe55bb744c6ed55f7129bb2c37284088966b3b16ac82824890c1afaa696437

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp311-cp311-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 a765fc2d64b6a0da4cc3348dcd63279d11225469e8fe4acaf7707d6fa882dfff
MD5 de34be2ad53ebe94c666d62b8aea7d2c
BLAKE2b-256 226056abd876a54f3f5eff98905eb1b5d1e9d4d26175b67dcf91e261f1659660

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: flox_py-0.8.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.8.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 132fdf3e50b3d41fc54d02de82d720406b10eda488748d0e0b587071d176e599
MD5 0d7fb41c7e8198b5d4b87a78c4874ecb
BLAKE2b-256 0545b2e8e07ae3616749b74dc9de28babb172f877b3f189744e0ef3380bbee72

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 ba4f08d21e55cabea25fbf34667809754d709dfe895031bc2e7b1da0eb86d178
MD5 f0e61c3b2759a26b3e79b6d2a2b5831a
BLAKE2b-256 81b915196876eb6e4537f3157314dc2cf0f066c968d1951fb924c519c8a4c4cd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for flox_py-0.8.0-cp310-cp310-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 79a05f94e8b590fcfd8937f82a419676ec96f4220a973c06087d9b9bf455b935
MD5 cb5810b05acb8756bead79b00bff459a
BLAKE2b-256 31bca7e8bc3edd7f6c0735b92f68086381e15a1a16eae74d50f03056306af445

See more details on using hashes here.

Provenance

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

Release history Release notifications | RSS feed

This release

0.8.0 This release

13 files

0.7.2

13 files

0.7.1

13 files

0.7.0

13 files

0.6.8

13 files

0.6.7

13 files

0.6.6

13 files

0.6.5

13 files

0.6.4

13 files

0.6.3

13 files

0.6.2

13 files

0.6.1

13 files

0.6.0

13 files

0.5.6

13 files

0.5.5

13 files

0.5.3

13 files

0.5.2

13 files

0.5.1

13 files

0.5.0

13 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page