tradefloor

tradefloor

tradefloor 是一个可供你运行策略的市场模拟器。它拥有 Rust 核心和 Python API。

提供一个种子和一份公司列表，它就会向前运行市场：价格、限价订单簿、成交，以及每天变动的经济。你的订单会与订单簿深度撮合，因此你的交易会影响价格。

真实市场数据无法告诉你，如果采用不同的交易方式会发生什么，也无法告诉你价格变动的原因。tradefloor 可以，因为每个价格都是它计算出来的。你可以分叉一个正在运行的市场，在一个分支中改变一件事（加息、流动性危机、换一个 Agent），然后衡量两个分支从何处分道扬镳。engine.truth() 会将价格与模型公允价值之间的差距拆分为十二个因素，engine.explain(ticker, day) 则会解析成交价格的变动；这两项记录是任何历史数据集都不具备的。

文档位于 https://docs.tradefloor.dev。

安装

pip install tradefloor

提供适用于 Linux、macOS 和 Windows 的 CPython 3.11+ wheel，且没有依赖项。同一引擎也是一个 Rust crate（cargo add tradefloor）。可选扩展还提供 MCP 服务（tradefloor[mcp]）、Arrow 输出（tradefloor[arrow]）、Gymnasium 环境（tradefloor[rl]），以及针对各个 Agent 框架的扩展。

1.0 之前，API 可能会发生变化。模型变更会作为新预设发布，因此在没有 Agent 订单的市场中，后续版本仍会使用指定预设精确重放。tradefloor 在 0.5.0 之前名为 pretium。最高至 0.4.3 的版本仍以该名称安装，使用这些版本记录的结果也仍可重放。

首次运行

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

该结果来自一个随机市场，因此它反映的既有策略表现，也有种子的影响。tf.rank 会运行多个种子，并使用配对符号检验比较策略。将 tf.baselines.reference_agents() 加入参赛者后，tf.versus_buy_and_hold(scores) 会将每项得分与同一市场中的买入并持有策略进行比较。

Python Agent 可以是任何带有 act(obs) 方法并返回订单的对象：市价单的股数、tf.Limit(quantity, price) 或 tf.Cancel()。它可以查看市场及自身投资组合的只读视图，obs.history 则保存每个标的的每日 K 线。K 线的收盘价是当天最后一笔成交价。在 pt-v21 中，收盘价随后会重新标记每个标的的价格，下一交易日开盘前还会发生隔夜变动，因此次日开盘时的价格会偏离前一笔成交价：在包含 20 个标的的组合中，收盘价与该成交价的中位数相差 11 个基点，开盘价与收盘价相差 25 个基点。 docs/AGENTS.md 介绍了视图包含的内容、交易如何收费、框架适配器（OpenAI Agents SDK、PydanticAI、LangGraph、FinRobot），以及评分方式。

演示

示例位于此仓库中，而不在软件包里，因此请先克隆仓库：

git clone https://github.com/simoncoombes/tradefloor
cd tradefloor
python examples/rate-shock/counterfactual.py

它会在受控市场中运行一个 Agent，保存世界检查点并分叉，在其中一个分支中将利率提高 200 bp，然后比较同一个 Agent 接下来会怎么做。它会打印九项检查，验证两个分支的起点完全相同，指出 Agent 行为发生变化的步骤，并并排展示两个分支。整个运行消耗的 CPU 时间不到五秒，无需密钥，也无需联网。请参阅演练 你的第一个反事实实验。

内容

engine.truth()	价格变动的原因：十二个因素之和精确到 1e-16，等于错误定价的变动幅度
engine.prints()	每笔交易的价格如何形成：冲击，以及吸收冲击的订单簿深度
反事实 TCA	你的交易成本：使用相同的随机种子，分别在有和没有你的订单时运行
tf.rank	多个随机种子，配对符号检验
RunManifest	读者重现运行所需的信息，由 reproduce() 检查
World / compare	分叉正在运行的实验，更改一个变量，并测量两个分支从何处开始出现差异
场景	七种打包的冲击，以及供你自定义的文件格式
MCP 服务	为编码 Agent 提供十九种工具，其中十三种为只读；包含场景、所有随附预设、随附的背景交易者群体，以及可逐步推进、分叉和回退的市场会话
更多	Gymnasium 环境、Arrow 输出、检查点、SEC EDGAR 数据、模拟利率指数、浏览器构建版

通过 Agent 操作

pip install "tradefloor[mcp]"
claude mcp add tradefloor -- tradefloor-mcp

tradefloor-mcp 通过 stdio 使用 MCP 通信，而 tradefloor mcp 会启动相同的服务。策略、市场范围和场景都是数据，因此工具参数无法执行代码。每项结果都附带自身的注意事项。会话会在服务端的多次调用之间保留一个市场，因此 Agent 可以逐步下单、分叉市场来尝试两种操作，并回退。请参阅 MCP 页面。

场景

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

场景是一个文件，其中包含对市场及其背后假设的更改。每项更改都针对引擎读取的一个字段，而该文件会将冲击与其假设会随之产生的连带影响区分开来：

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 从应用场景的第一天起计算天数，因此在分支上会从分支开始计算。大多数打包文件会在第 50 天首次触发。若要让场景在分叉后的第一天触发，请使用 scenario.starting_at(0)，或在 World 上使用 world.apply(scenario, at=0)。事件之间的间隔保持不变，运行记录会保留打包文件的指纹以及每个事件触发的日期。

tradefloor 不会预测战争、选举、石油冲击或经济衰退会对市场造成什么影响。由你陈述假设，它负责衡量 Agent 在这些假设下的行为。tradefloor scenario list 会列出七种打包场景，tradefloor scenario targets 会列出场景可以更改的所有字段。

可复现性

在任何平台上，相同的种子都会生成相同的市场。tradefloor 自带 exp、log、pow、sin 和 cos，因此系统的数学库不会改变结果；每个版本都会在五个平台上运行固定模拟，如果任何结果不同，就会停止。

已发布的预设永不改变，因此在其中没有 Agent 订单的市场，在所有后续版本中使用其指定预设重放时都完全一致。每个版本都会通过为每个预设计算摘要来检查这一点。包含 Agent 订单的运行在同一版本中重放时完全一致。对于跨版本重放，我们的保证范围更窄。0.8.5 改变了 Agent 成交传递到市场的方式，影响所有预设，因此在 0.8.5 之前记录的交易运行会一直匹配到首笔交易，此后则会不同。默认预设为 pt-v21，也可以指定任何更早的预设：

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

如需让读者重新运行某个结果，请发布其 RunManifest。它记录版本、预设、种子、市场范围、宏观状态和情景；如果不匹配，reproduce() 就会停止。清单会检查市场，但不包含分数。其 result 块包含市场的 digest、days 数量和 draws_consumed。tf.evaluate 和 tf.rank 不会写入清单，因此要核验已发布的分数，必须重新运行。 docs/REPRODUCIBILITY.md 包含完整的保证条款，包括恢复已保存引擎状态时的保证，以及 docs/SUPPORT.md 说明了长期研究应固定使用哪个版本。

真实性

tradefloor 使用三组有名称的统计数据，将其市场与真实市场进行核验，详见 docs/STATISTICS.md。 在 pt-v21（自 0.10.0 起的默认版本）上，一年期表格中的全部 19 项统计数据（波动率、肥尾、股票联动程度、VIX 在下跌后跳升的幅度）都落在真实市场一年内的范围中，符合规定的区间。指数收益率以及指数单日下跌 3% 或以上的比例，按照长期标准的读取方式，基于 360 个种子读取：指数有 0.98% 的交易日下跌 3% 或以上，而真实范围为 0.64 至 2.34。两年期面板中的全部 15 项统计数据都落在各自的两年期范围内。长期标准涵盖 21 年中的 40 项指标，包括崩盘深度、恐慌持续时间、每十年的熊市次数、2008 年和 2020 年的重演、指数的利率，以及账簿中的规模成本。pt-v21 在 270 段历史数据上读取时，满足全部 40 项标准。

请谨慎解读这些结论：

• 一年期的统计结果是基于汇总的 30 个种子数据（指数收益率和 3% 跌幅指标则为 360 个种子）作出的判断。单个种子的一年数据常常无法满足部分 14 项形态统计指标。在种子 101 至 116 中，16 个种子里有 8 个的全部 14 项指标都在范围内，其中一个种子有 11 项达标。如果每种条件只运行一个市场，请使用 tf.envelope.intervals() 查看每项统计数据在不同种子间的分布。
• 形态统计数据的范围取自 35 个真实的一年期窗口的中位数，加减 2.1 倍截尾标准差，因此通过单项指标只能算弱证据。波动率聚类就是一个例子。abs_return_acf5 的读数为 0.020，低于 2015 至 2025 年所有真实窗口（最低为 0.034），但由于其范围下限低于这些窗口的读数，所以仍然达标。
• VIX 的持续性高于真实市场：其日间持续性读数为 0.956，而市场记录为 0.930；用于评定它的符号检验未通过。
• pt-v21 保留的许多系数是在参考一年期表格后选定的，因此留出检验采用新的种子，以及在其上重复运行面板的新公司集合。
• 一年是经过验证的时间跨度。两年依据两年期面板进行评定，更长的运行则只依据长期标准。
• 驱动场景会让价格朝正确方向变动，幅度约为真实市场的二分之一至五分之四。可用场景检测市场反应，但不要将其幅度视为预测。
• 波动率记忆在滞后 1 时读数为 0.095，真实值为 0.107，之后衰减得快得多：滞后 20 时不到真实值的二十分之一。65 分钟步长以下的内容均未经过校准。
• 默认情况下，没有其他交易者会对你作出反应，因此不会出现流动性螺旋或掠夺性交易。填充模式会加入交易你的信号并抢先交易可预测流量的背景交易者，但他们会让可预测的计划多付约 2.4%，远低于真实市场的水平。

tf.envelope.check(horizon_days=...) 会拒绝超出测量范围的问题。 docs/REALISM.md 列出了这些结论所依据的全部数据，以及完整的限制范围表。

发布结果之前

• 如果 Agent 因判断出每一天走势背后的因素而得分，就会获得 explanation_accuracy。在 pt-v21 上，即使答案始终不变，得分也会在 0.70 到 0.95 之间，因此请引用 explanation_edge，也就是准确率减去该基准值，绝不要只引用准确率。
• 同一次 tf.evaluate 或 tf.rank 调用中的 Agent 会在同一个 Python 进程、同一个种子下依次运行。较早运行的 Agent 可以将价格路径留在类变量中，供之后运行的 Agent 使用。恶意编写的 Agent 还可以通过 sys._getframe 从运行框架的帧中读取种子，并提前运行一份市场模拟。这两种情况都不会触发任何警报。只读市场视图只能防止意外，因此请让每个非自行编写的 Agent 都在独立进程中通过 MCP 服务运行。
• 每次 evaluate 和 rank 运行都会从第 0 天开始，因此，需要 20 天价格数据的规则会在最初 20 天按兵不动，而买入并持有策略则一直持仓。传入 history_days=20，即可先运行 20 天市场，期间不进行任何交易。
• 在包含多个 Agent 的 World 中，同一步下达的订单会在整个运行期间按标签顺序执行，顺序为字母顺序。若要在同一市场中比较不同 Agent，请在各次运行中轮换标签。
• 没有佣金，做空不收借款费用，也没有止损单。你在每一步检查的止损单，在每天运行六步的情况下，成交价中位数会比止损价位差 26.5 bp。未投资的现金不会产生收益，除非传入 cash_interest=True；负现金余额则按政策利率付息，该利率低于经纪商的保证金利率。

docs/AGENTS.md 列出了这些数据背后的测量结果。

示例

这 12 个编号的 examples/ 按阅读顺序排列，测试套件也会运行这些示例：

00-a-year-in-one-market	从这里开始：一家公司的 1 年、两场危机和一张图表
01-first-simulation	市场范围、引擎、订单簿、确定性
02-evaluating-a-strategy	规格、基线、跨随机种子的排名
03-why-did-the-price-move	价格偏离变动由 12 个因素共同构成
04-how-realistic-is-this	真实度面板及其局限
05-training-an-agent	Gymnasium 环境，以及规模带来的成本
06-execution-and-impact	TCA 和反事实运行
07-research-workflow.py	用一个文件完成一项完整研究。需要约 40 秒 CPU 时间，并且需要 tradefloor[arrow]
08-claude-agent.py	一个通过运行框架进行市场交易的大模型 Agent
09-a-pandemic-shaped-market	真实的 2020-21 宏观路径，以及哪些字段会传递影响。固定使用 pt-v12，其 QE 通道承载估值路径；最后还会在默认版本 pt-v21 上使用相同路径
10-forking-a-market	复制一个市场，在其中一个分支上调高利率，并比较未来走势
11-scenario-fork.py	将情景文件应用于分支的一个分支，并了解其成本

rate-shock/ 研究就是上面的演示，而 integrations/ 则通过各个 Agent 框架运行同类实验，无需联网，也无需 API 密钥。

文档

https://docs.tradefloor.dev 涵盖安装、API、指南以及模型的测量方式。本仓库中的这些页面详细介绍了上述各部分：

• docs/MODEL.md： 以方程形式呈现模型，列出默认预设中每个系数的值及其来源
• docs/STATISTICS.md： 各组具名的真实度统计数据
• docs/REALISM.md： 真实度结果和每项测量限值
• docs/REPRODUCIBILITY.md： 在不同平台、发行版本和恢复状态下，哪些内容可以精确重放
• docs/AGENTS.md： 编写、评分和比较 Agent
• docs/SUPPORT.md： 哪些发行版本系列会获得修复，以及支持期限
• docs/EMBEDDING.md： 如何从游戏或其他宿主驱动 Rust 引擎，以及模型本身会产生多少交易流

贡献与支持

CONTRIBUTING.md 介绍如何构建和测试项目。其主要原则是，对模拟轨迹的任何更改，无论多小，都属于破坏性更改，因此模型更改会以新预设的形式发布。RELEASING.md 是发行检查清单。

请通过 GitHub 的 安全公告表单 报告漏洞，不要通过公开议题报告。 SECURITY.md 说明了受理范围。错误和问题请提交到 GitHub 议题。

0.8.5 及其后续的 0.8 补丁属于长期支持系列，将提供 24 个月的错误和安全修复。 docs/SUPPORT.md 说明了支持系列的承诺，以及长期研究应固定使用哪个发行版本。

引用 tradefloor

请引用你运行的版本并注明预设。同一版本可以运行多个预设，结果取决于所用预设。

@software{tradefloor,
  author  = {Coombes, Simon},
  title   = {tradefloor: a deterministic market simulator with a limit order book},
  version = {0.10.2},
  year    = {2026},
  url     = {https://github.com/simoncoombes/tradefloor},
  note    = {Model preset pt-v21}
}

CITATION.cff 包含相同的详细信息，GitHub 的“引用此仓库”按钮会读取该文件。

在正文中说明你使用的模型，例如：“tradefloor 0.10.2，预设 pt-v21，详见其 docs/MODEL.md”。 docs/REPRODUCIBILITY.md 说明如何发布结果以便读者重现，以及如何证明某个分数并非针对其种子调优所得。

许可证

tradefloor 根据 MIT OR Apache-2.0 许可协议授权，你可以任选其一。请参阅 LICENSE-MIT 和 LICENSE-APACHE。 GitHub 侧边栏显示 Apache-2.0，因为其许可证检测只选择一个文件，然后便停止。适用的授权是双重授权，已在 pyproject.toml、rust/Cargo.toml 和本节中说明。