Skip to the page

Overview

tradefloor is a simulated stock market, with a limit order book and an economy, for testing trading strategies and AI agents. Run a market again with the same inputs and you get the same market. An agent's orders move the prices it trades at.

Start with a task

New to tradefloor

Run your first market. Install, run a five-company market for 20 days, score an agent and read the result, in five minutes.

Building an agent

Write an agent. The act(obs) method, the orders it can return, sizing to a target weight and what the agent can see.

Evaluating strategies

Compare strategies. Against buy-and-hold on one market, then across many seeds, and by what each one's trades cost.

Testing counterfactuals

Fork a market. Copy a running market, change one input in one copy, and measure what the change did.

More workflows

Longer walk-throughs, each with a script you can run, live on the product site under Guides: a decision engine on markets where the regime is known, a bot against a crash, an LLM agent without look-ahead bias, skill or luck, the cost of your own orders and a risk gate in CI.

Concepts

UniversePresetScenarioSeed
Enginethe market: order book, companies, economy
observation →← orders
Agentact(obs)
Runthe engine stepped through trading days
Scoreevaluate, rank
Checkpoint, then forktwo futures from one past
Manifest, then reproduceinputs, version and orders, saved
EngineOne market. tf.Engine(seed=..., universe=..., model=...) runs the order book, the companies' fair values and the economy, and returns Arrow tables of what happened. Engine
UniverseThe companies a market trades, in order. Changing the order changes the market. tf.Universe.random(n, seed=...) makes made-up companies, and Universe.from_edgar reads real ones. Universe
PresetA named, frozen set of model coefficients, such as pt-v22, the default. Its values don't change after it ships. ModelParams
SeedThe integer behind all of the engine's random draws. Universe.random has a separate seed that picks the companies. Seed
ScenarioA named set of changes to the economy or the market on given days, such as a rate shock, with the assumptions behind them stated. Run a scenario
AgentAny object with an act(obs) method. Strategies, LLM agents and RL policies all trade through it. Write an agent
Observation and actionAt each decision step the agent receives an observation (prices, its portfolio, the clock) and returns an action: orders, as shares per ticker, or None. What act returns
RunAn engine stepped through trading days. With an agent in it, the run also depends on the agent's orders, because they fill against the book and move prices.
Scoretf.evaluate runs each agent on its own copy of one market and returns a Scorecard. tf.rank repeats that over many seeds and counts which agent did better. Compare strategies
ForkA copy of a running market. Change one input in one copy and any later difference comes from that change. Fork a market
ManifestA RunManifest holds the version, preset, seed, universe, scenario and order log of a run, and rebuilds the market from them. Reproducibility

In code, the smallest complete run is a universe, an agent and a score:

import tradefloor as tf

universe = tf.Universe.random(5, seed=11)      # the companies, in order
agent = tf.baselines.BuyAndHold()              # act(obs) returns orders

# One engine per agent, on the default preset, seed 42, for 20 trading days
scores = tf.evaluate({"hold": agent}, seed=42, universe=universe, days=20)
print(scores["hold"])
Scorecard('hold', pnl=5,913, return=+0.59%, trades=5, impact=+0.13bps, sharpe=+0.59, vol=14.3%, in_market=100%, exposure=0.94x)

Reference

The recommended API is the short list of classes and functions most code needs. The complete index lists every export with its tier. The model is documented in How prices are made, its coefficients in Model parameters, and what has been checked against real markets in How it is measured. Support policy says which releases get fixes and what a patch release may change.

The hosted app at app.tradefloor.dev is documented separately under Hosted (preview).