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
- Run a scenario: score an agent with and without a shipped scenario on the same seeds.
- Test an LLM agent: PydanticAI, the OpenAI Agents SDK, LangGraph or a plain function, with its answers recorded.
- Use a decision engine: ask an engine such as TypeSafe's Jev typed questions, act on its answers and confidence in code, and record them.
- Record and replay: run a recorded LLM agent again without calling the model.
- Reproduce or publish an experiment: what fixes a market, saving a run as a manifest, and what to report (Citing tradefloor).
- Train an RL policy: a Gymnasium environment whose reward includes the cost of the policy's own trading.
- Connect through MCP: a local server that lets a model build markets, score strategy specs and explain price moves.
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
act(obs)evaluate, ranktf.Engine(seed=..., universe=..., model=...) runs the order book, the companies' fair values and the economy, and returns Arrow tables of what happened. Enginetf.Universe.random(n, seed=...) makes made-up companies, and Universe.from_edgar reads real ones. UniverseUniverse.random has a separate seed that picks the companies. Seedact(obs) method. Strategies, LLM agents and RL policies all trade through it. Write an agentNone. What act returnstf.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 strategiesRunManifest holds the version, preset, seed, universe, scenario and order log of a run, and rebuilds the market from them. ReproducibilityIn 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).