# Polymarket Python 盘口回测教程

这个例子从一个真实 BTC 5 分钟市场开始，读取 CSV、检查报价与深度，再模拟一次买入 UP、持有 60 秒后卖出的过程。脚本只用 Python 标准库，不需要安装 pandas 或其他依赖。

[下载数据样例](/samples/polymarket-btc-5m-20261008-1500.zip) · [下载教程脚本](/tutorial/backtest_sample.py) · [查看实测输出](/tutorial/example-result.json)

## 运行方法

把样例解压到 `sample` 文件夹，将教程脚本放在同级目录。使用已有 Python 虚拟环境，或按下面的方式新建。创建虚拟环境不会为本教程安装第三方依赖。

```sh
python3 -m venv .venv
source .venv/bin/activate
python backtest_sample.py --data-dir sample --output result.json
```

Windows 虚拟环境的激活命令为 `.venv\Scripts\activate`。`--data-dir` 指向含 ticks.csv、depth.csv、outcomes.csv 和 manifest.json 的目录。

脚本核对行数和市场标识，拒绝重复关联键、无效价格及无法关联到报价的深度记录。输出保留输入 CSV 的 SHA-256，便于复查是否使用了同一份文件。

## 决策与时间

示例在正式市场窗口内收到第一条可用报价后决定买入，不读取 winner_side 或 target 来选择方向。订单延迟默认 250 毫秒。

在模拟到达时间，脚本选择接收时间不晚于到达时间的最后一份已保存盘口。源时间较早、接收时间较晚的记录不会提前参与计算。选中盘口超过 2 秒未更新时，示例直接报错，不填补空白。

保存的盘口只是模拟订单到达时市场状态的近似。这个例子没有真实网络往返记录，也没有交易所撮合记录，不能证明历史上实际能够成交。

## 按价格和数量模拟

买入逐档消耗 UP 卖盘，价格从低到高。卖出消耗 UP 买盘，价格从高到低。默认只使用每档展示数量的 50%，不足部分保留为未成交数量。

进入后持有 60 秒，再加入一次订单延迟发出卖出。卖出的请求数量只等于模拟买入数量。卖出不足时，输出保留剩余持仓，现金流不会被标成已平仓盈亏。

```sh
python backtest_sample.py --data-dir sample --quantity 100 --latency-ms 250 --hold-seconds 60 --size-fraction 0.5 --max-staleness-ms 2000 --fee-bps 0 --output result.json
```

fee-bps 是对模拟成交金额收取的演示费用参数，默认 0 不代表平台实际费率。真实研究须按当时市场的费用规则替换。多档成交价格已反映可见深度造成的价差，额外市场冲击与挂单排队没有建模。

## 这份样例的运行结果

默认参数下，示例模拟买入 100 份 UP，均价 0.39 美元；卖出 100 份，均价 0.217 美元。卖出使用两档，分别为 0.22 美元的 70 份和 0.21 美元的 30 份。按演示零费率计算，已平仓盈亏为负 17.30 美元。

这是一组固定参数下的单次教学输出。只有一个市场，没有训练与测试划分，没有统计显著性，也没有可交易收益结论。更改参数后，请以本次运行的 JSON 为准。

样例的 552 条报价中有 207 条在开盘前。最后一条盘中观测在 `15:04:25.770 UTC` 收到，未覆盖到正式窗口结束。相邻盘中保存记录的最大间隔为 91.498 秒，不能把这份文件当成连续完整盘口。

## 换成完整历史之前

按 event_slug 分市场，核对每个归档版本的时间字段、断线与重复记录。跨 UTC 零点的市场要拼接相邻日包，所有分包一起读取。接收时间缺失时明确披露近似方法。

outcomes 只能用于事后评估。预测特征要排除 winner_side、target 及未来收到的信息。多市场策略还需要样本外检验、费用和延迟情景，以及剔除市场的数量和原因。

Predict.fun 的原始观测为 YES 盘口，DOWN 为互补推导；本教程仅针对该 Polymarket CSV 样例，不能直接当作 Predict.fun 的执行模型。底层 BTC 价格需要按供应商与通道另行关联。

[数据规格与采集方式](/datasets/polymarket-btc-5m/) · [字段与时间口径](/schema/) · [底层价格口径研究](/research/bolt-price-semantics/) · [历史文件目录](/downloads/)
