tradefloor

tradefloor

tradefloor is a market simulator you can run a strategy against. It has a Rust core and a Python API.

Give it a seed and a list of companies. It runs a market forward: prices, a limit order book, fills, and an economy that moves each day. Your orders match against the book's depth, so your trades move the price.

Real market data can't tell you what would have happened if you had traded differently, or what caused a move. tradefloor can, because it computed every price. You can fork a running market, change one thing in one branch (a rate rise, a liquidity crisis, a different agent), and measure where the two branches came apart. engine.truth() splits each move in the gap between a price and the model's fair value into twelve factors, and engine.explain(ticker, day) breaks down the move in the traded price, two records no historical dataset carries.

Documentation is at https://docs.tradefloor.dev.

Install

pip install tradefloor

There are wheels for Linux, macOS and Windows on CPython 3.11+, and no dependencies. The same engine is a Rust crate (cargo add tradefloor). Optional extras add the MCP server (tradefloor[mcp]), Arrow output (tradefloor[arrow]), the Gymnasium environment (tradefloor[rl]) and one extra per agent framework.

The API may change before 1.0. Model changes ship as new presets, so a market with no agent orders in it replays exactly on its named preset in later releases. tradefloor was called pretium until 0.5.0. Versions up to 0.4.3 still install under that name, and results recorded with them still replay.

A first run

import tradefloor as tf

universe = tf.Universe.random(40, seed=111)

spec = tf.StrategySpec.momentum(lookback_days=1.0, top_k=5) scores = tf.evaluate({"mine": spec}, seed=7, universe=universe, days=10)

scores["mine"].return_pct # what it made scores["mine"].impact_bps # what its own footprint cost scores["mine"].strategy_fingerprint # sha256, cite this scores["mine"].errors # each step that raised or was refused scores["mine"].sharpe # annualised, from the daily closes scores["mine"].time_in_market # share of steps holding a position

That result comes from one random market, so it says as much about the seed as about the strategy. tf.rank runs many seeds and compares strategies with a paired sign test. Add tf.baselines.reference_agents() to the entrants and tf.versus_buy_and_hold(scores) reads each score against buy-and-hold on the same market.

A Python agent is any object with act(obs) that returns orders: a number of shares for a market order, tf.Limit(quantity, price) or tf.Cancel(). It sees a read-only view of the market and its own portfolio, and obs.history holds a daily bar per name. A bar's close is the day's last print. On pt-v21 the close then re-marks every name and the next session opens after an overnight move, so the next day starts away from that print: the close sits 11 bp from it at the median on a 20-name roster, and the open 25 bp from the close. docs/AGENTS.md covers what the view holds, how trades are charged, the framework adapters (OpenAI Agents SDK, PydanticAI, LangGraph, FinRobot) and how scoring works.

The demo

The examples are in this repository and not in the package, so clone it first:

git clone https://github.com/simoncoombes/tradefloor

cd tradefloor python examples/rate-shock/counterfactual.py

It runs an agent in a controlled market, checkpoints the world and forks it, raises rates by 200 bp in one branch, and compares what the same agent does next. It prints nine checks that the two branches started identical, the step at which the agent's behavior changed, and the two branches side by side. The run takes under five seconds of CPU and needs no keys and no network. The walkthrough is Your first counterfactual experiment.

Contents

Drive it from an agent

pip install "tradefloor[mcp]"

claude mcp add tradefloor -- tradefloor-mcp

tradefloor-mcp speaks MCP over stdio, and tradefloor mcp starts the same server. Strategies, universes and scenarios are data, so a tool argument cannot reach code. Each result carries its own caveats. A session keeps one market in the server between calls, so an agent can place orders a step at a time, fork the market to try two actions, and rewind. See the MCP page.

Scenarios

engine = tf.Engine(seed=42, universe=universe)

engine.run_days(20) # a shared history first scenario = tf.Scenario.load("liquidity_crisis") # ships with the package

control, stress = tf.branch(engine, 2) for day in range(80): scenario.apply(stress, day) ... # run both branches

A scenario is a file of changes to the market and the assumptions behind them. Each change targets a field the engine reads, and the file keeps the shock apart from the knock-on effects you assume follow it:

tradefloor scenario show oil_price_spike

Exogenous shocks

---

day 50+ commodity.oil x1.4

Assumed transmission

---

day 55..74 ramp macro.inflation +1.50pp day 55+ macro.corporate_yield +0.50pp

at in a scenario counts days from the first day it is applied, so on a branch it counts from the branch. Most packaged files first fire on day 50. To fire one on the first day after a fork, use scenario.starting_at(0), or world.apply(scenario, at=0) on a World. The gaps between its events stay the same, and the run's record keeps the packaged file's fingerprint and the days each event fired.

tradefloor does not predict what a war, an election, an oil shock or a recession will do to markets. You state the assumptions and it measures how an agent behaves under them. tradefloor scenario list names the seven packaged scenarios, and tradefloor scenario targets lists every field a scenario can change.

Reproducibility

The same seed gives the same market on every platform. tradefloor ships its own exp, log, pow, sin and cos, so the system's math library cannot change a result, and each release runs a fixed simulation on five platforms and stops if any result differs.

A shipped preset never changes, so a market with no agent orders in it replays exactly on its named preset in every later release. Each release checks that with a digest per preset. A run with agent orders in it replays exactly on the same release. Across releases the promise is narrower. 0.8.5 changed how an agent's fills reach the market, on every preset, so a traded run recorded before 0.8.5 matches up to its first trade and differs after it. The default preset is pt-v22, and pt-v21 or any other shipped one can be named:

eng = tf.Engine(seed=42, universe=u, model="pt-v10")

pt-v22 lists index, rate and oil futures and options on every name. It is the default from this release, so a run that left model out on an earlier release gives a different market here.

To let a reader rerun a result, publish its RunManifest. It records the version, preset, seed, universe, macro state and scenario, and reproduce() stops on a mismatch. A manifest checks the market and carries no score. Its result block holds the market's digest, the number of days and draws_consumed. tf.evaluate and tf.rank write no manifest, so a published score has to be rerun to be checked. docs/REPRODUCIBILITY.md has the full contract, including what a saved engine state promises when it is restored, and docs/SUPPORT.md says which release to pin for a long study.

Realism

tradefloor checks its market against real ones with three named sets of statistics, listed in docs/STATISTICS.md. On pt-v22, the default, 19 of the 19 statistics of the one-year table (volatility, fat tails, how much stocks move together, how far the VIX jumps after a fall) are inside the range real markets show over a year. pt-v22's long-run criteria are 190 rows over 21 years, covering crash depth, how long fear lasts, bear markets per decade, the 2008 and 2020 replays, the rate indices, the cost of size in the book, strategies built to find an edge, and the futures, options and margin (docs/MODEL.md). pt-v22 meets all 190, read on 270 histories. Two more rows are shown for comparison and not counted. On pt-v21 (the default from 0.10.0 to 0.10.2), all 19 one-year statistics are inside their ranges, on the ruled bands. The index's return and the share of days it falls 3% or more are read over 360 seeds, as the long-run criteria read them: the index falls 3% or more on 0.98% of days, against a range of 0.64 to 2.34. All 15 statistics of the two-year panel are inside their two-year ranges. pt-v21 meets all 40 of the long-run rows it was graded on, read on 270 histories.

Read those claims narrowly:

• The one-year count is a verdict on figures pooled over 30 seeds (360 for the index's return and 3% falls). One seed's year often misses some of its 14 shape statistics. On seeds 101 to 116, all 14 were in range on 8 of the 16, and one seed had 11 of 14. If you run one market per condition, read tf.envelope.intervals() for each statistic's spread across seeds.
• A shape statistic's range