simoncoombes/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
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
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:
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
| | |
|---|---|
| engine.truth() | why each price moved: twelve factors that sum to the mispricing's move, to 1e-16 |
| engine.prints() | how each trade price came about: the shock, and the order book depth that absorbed it |
| counterfactual TCA | your trading cost, from the same seed run with your orders and without them |
| tf.rank | many seeds, paired sign tests |
| RunManifest | what a reader needs to replay a run, checked by reproduce() |
| World / compare | fork a running experiment, change one variable, and measure where the two came apart |
| scenarios | seven packaged shocks, and a file format for your own |
| MCP server | nineteen tools for a coding agent, thirteen of them read-only, with scenarios, any shipped preset, a shipped population of background traders, and market sessions you step, fork and rewind |
| more | a Gymnasium environment, Arrow output, checkpoints, SEC EDGAR data, simulated rate indices, a browser build |