执行摘要与范围Executive Summary & Scope
When2Buy 需要可执行回测级别的美股期权历史数据：不仅是收盘价，而是能够重建任意历史时刻的完整报价、成交与希腊值状态。 本标准按 P0/P1/P2 三级优先级组织需求，便于 Bitget 分阶段评估自有数据能力或第三方供给能力。
P0 P0 · Must have
核心指数/ETF 期权 + VIX 家族指数，完整 0DTE 每日到期链，NBBO 报价、成交、希腊值与标的 OHLCV。这是可执行回测的最低闭环。
P1 P1 · High value
流动性较好的美股个股期权与更广泛的指数期权覆盖，扩展策略研究的标的池与截面广度。
P2 P2 · Nice to have
次要衍生指标（如 rho）、扩展的公司行为/参考利率细节，以及非核心交易所的补充覆盖。
覆盖范围 / 标的池Coverage & Universe
历史深度目标 2017 至今，最低可接受 2020 至今；需覆盖全部 0DTE 每日到期；tick 或 1 秒级原始数据优先，1 分钟衍生 K 线可接受；需明确区分正常/延长交易时段。
| Priority | Universe | Underlyings / 标的 | Granularity 要求 |
|---|---|---|---|
| P0 | US index/ETF options + VIX-family indices | SPX, SPY, QQQ, IWM · VIX, VIX1D, VIX9D + 对应标的 K 线 | Tick/1s 原始优先，1min 衍生可接受；含正常+延长时段标记 |
| P1 | Liquid single-stock options + index expansion | 流动性较高的美股个股期权；更多指数期权 | 同上，允许 1min 衍生为主 |
| P2 | Extended reference coverage | 次要交易所/长尾合约的参考数据 | EOD 级别即可 |
History target: 2017-present（理想）/ 2020-present（最低可接受）。Full 0DTE daily expiries required for in-scope underlyings.
数据产品Data Products
八类数据产品构成完整的期权历史数据基础设施，详细字段见下一节「字段字典」。
Contract Master P0
合约主数据/参考：instrument_id、option_symbol、到期日、行权价、乘数、行权方式。
NBBO Quotes P0
最优买卖报价事件（或 1 分钟报价 K 线）：bid/ask 价格与数量、报价交易所、序列号。
Trades P0
成交明细：价格、数量、交易所/条件码、更正标记。
Chain Snapshot P0
某一时刻的完整期权链快照，含标的价格联动。
Greeks & IV P0
希腊值与隐含波动率，附模型、无风险利率与股息假设等方法论元数据。
Underlying OHLCV P0
标的/指数 OHLCV，含正常/盘前盘后时段标记。
OI / Volume / EOD / Settlement P1
未平仓量、成交量、日终结算价与结算方法。
Corp Actions / Calendar / Rates / Dividends P1
拆股、分红、到期日历、参考利率曲线，用于历史行权价/价格调整。
字段字典 / 精确 SchemaExact Schemas & Data Dictionary
通用约定：时间戳统一使用 ISO-8601 UTC（如有条件精确到纳秒），并附带 exchange_tz，禁止使用无时区的本地时间；
option_symbol（人类可读）与 instrument_id（稳定内部 ID）并存；expiration_date 为 YYYY-MM-DD；
行权价为十进制 USD（如 552.50），非放大整数；价格为每股十进制 USD，contract_multiplier 显式给出；
隐含波动率为小数（0.2075 = 20.75%）；希腊值需注明符号约定、模型与计算时刻；报价需含条件码、交易所、买卖量、序列号与更正/撤销状态。
机器可读版本见 data/data-spec.json。
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| instrument_id | string | – | No | SPY-2026-07-29-C-552.50 | P0 |
| option_symbol | string | – | No | SPY260729C00552500 | P0 |
| underlying_symbol | string | – | No | SPY | P0 |
| asset_class | enum | – | No | ETF_OPTION | P1 |
| primary_listing | string | – | Yes | OPRA_CONSOLIDATED | P1 |
| expiration_date | date | YYYY-MM-DD | No | 2026-07-29 | P0 |
| strike_price | decimal | USD | No | 552.50 | P0 |
| option_type | enum | – | No | C / P | P0 |
| contract_multiplier | integer | shares/contract | No | 100 | P0 |
| exercise_style | enum | – | No | American | P1 |
| currency | string | ISO 4217 | No | USD | P1 |
| first_listed_date | date | YYYY-MM-DD | Yes | 2026-01-05 | P2 |
Sample: data/sample_contracts.csv（20 rows：10 strikes × C/P）
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| event_ts_utc | timestamp | ISO-8601 UTC, ns | No | 2026-07-29T13:35:00.050000000Z | P0 |
| exchange_tz | string | IANA tz | No | America/New_York | P0 |
| instrument_id | string | – | No | SPY-2026-07-29-P-548.00 | P0 |
| bid_price / ask_price | decimal | USD/share | Yes* | 0.08 / 0.12 | P0 |
| bid_size / ask_size | integer | contracts | Yes* | 12 / 12 | P0 |
| bid_exchange / ask_exchange | string | – | Yes | CBOE / ARCX | P1 |
| quote_condition | enum | – | No | REGULAR / CROSSED / LOCKED | P0 |
| sequence_number | integer | – | No | 1004 | P0 |
| is_correction | boolean | – | No | false | P0 |
*仅当单边市场时可为空。Sample: data/sample_quotes.csv（20 rows：4 legs × 5 checkpoints）
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| event_ts_utc | timestamp | ISO-8601 UTC, ns | No | 2026-07-29T13:35:00Z | P0 |
| instrument_id | string | – | No | SPY-2026-07-29-P-548.00 | P0 |
| trade_price | decimal | USD/share | No | 0.10 | P0 |
| trade_size | integer | contracts | No | 10 | P0 |
| exchange | string | – | No | CBOE | P0 |
| trade_conditions | string | – | Yes | REGULAR | P1 |
| sequence_number | integer | – | No | 5001 | P0 |
| is_correction | boolean | – | No | false | P0 |
Sample: data/sample_trades.csv（8 rows：4 legs × entry+exit）
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| snapshot_ts_utc | timestamp | ISO-8601 UTC, ns | No | 2026-07-29T13:35:00Z | P0 |
| underlying_price | decimal | USD | No | 552.47 | P0 |
| instrument_id / strike_price / option_type | mixed | – | No | …-C-552.50 / 552.50 / C | P0 |
| bid_price / ask_price / last_price | decimal | USD/share | Yes* | 0.53 / 0.63 / 0.58 | P0 |
| bid_size / ask_size | integer | contracts | Yes* | 25 / 25 | P0 |
| volume | integer | contracts | No | 940 | P0 |
| open_interest | integer | contracts | No | 11800 | P0 |
Sample: data/sample_chain_snapshot.csv（20 rows：full chain @ 09:35 ET）
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| as_of_ts_utc | timestamp | ISO-8601 UTC, ns | No | 2026-07-29T13:35:00Z | P0 |
| implied_volatility | decimal | annualized fraction | Yes | 0.150 (=15.0%) | P0 |
| delta | decimal | unitless | Yes | C∈[0,1], P∈[-1,0] | P0 |
| gamma / vega | decimal | unitless / USD per vol pt | Yes | 0.073 / 0.066 | P0 |
| theta | decimal | USD/day | Yes | -0.28 | P0 |
| rho | decimal | USD per rate pt | Yes | 0.0015 | P2 |
| model | string | – | No | black_scholes_1973_american_approx | P0 |
| risk_free_rate_ref / dividend_yield_input | string / decimal | – / fraction | No / Yes | US_SOFR_1M / 0.013 | P1 |
Sample: data/sample_greeks.csv（20 rows：full chain @ 09:35 ET）
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| bar_start_ts_utc / bar_end_ts_utc | timestamp | ISO-8601 UTC, ns | No | …13:35:00Z / …13:35:59.999999999Z | P0 |
| open / high / low / close | decimal | USD | No | 552.47 / 552.58 / 552.42 / 552.52 | P0 |
| volume | integer | shares | No | 193900 | P0 |
| session_flag | enum | – | No | REGULAR / PRE_MARKET / AFTER_HOURS | P0 |
Sample: data/sample_underlying_bars.csv（10 rows：1-min bars 09:30–09:39 ET）
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| trade_date | date | YYYY-MM-DD | No | 2026-07-29 | P0 |
| settlement_price | decimal | USD/share | Yes | 0.58 | P0 |
| settlement_method | string | – | No | OPRA_OFFICIAL_CLOSE | P1 |
| closing_open_interest / total_volume | integer | contracts | No | 11800 / 940 | P0 |
本草案未附带独立样例文件；未平仓量/成交量已作为字段包含在 sample_chain_snapshot.csv 中。No dedicated sample file in this draft.
| Field | Type | Unit | Nullable | Example | Priority |
|---|---|---|---|---|---|
| event_type | enum | – | No | CASH_DIVIDEND / SPLIT / MERGER | P0 |
| effective_date / ex_date | date | YYYY-MM-DD | No / Yes | 2026-09-19 / 2026-09-18 | P0 |
| cash_amount | decimal | USD/share | Yes | 1.72 | P1 |
| split_ratio / adjustment_factor | string / decimal | – / unitless | Yes | 2:1 / 1.0 | P1 |
| reference_rate_curve | string | – | Yes | US_SOFR | P2 |
单日 0DTE 示例不涉及公司行为事件，故本草案未附带样例文件。No sample file: the single-day example has no corporate action events.
可下载样例文件Downloadable Example Files
以下文件由 scripts/generate_data.py 本地生成，围绕一个 SPY 0DTE 铁鹰组合（iron condor）示例构造，8–20 行/文件，内部一致（bid ≤ ask、put-call delta 平价、跨文件 instrument_id 可关联）。所有数值均为示例/合成数据。
- sample_contracts.csv合约主数据 · 20 rowsDownload
- sample_quotes.csvNBBO 报价事件（4 腿 × 5 时间点）· 20 rowsDownload
- sample_trades.csv成交明细（4 腿开仓+平仓）· 8 rowsDownload
- sample_chain_snapshot.csv期权链快照 @ 09:35 ET · 20 rowsDownload
- sample_greeks.csv希腊值与 IV @ 09:35 ET · 20 rowsDownload
- sample_underlying_bars.csvSPY 1 分钟 K 线 09:30–09:39 ET · 10 rowsDownload
- sample_manifest.json不可变清单：dataset_version / schema_version / SHA-256Download
- data-spec.json机器可读字段字典（全部 8 类数据产品）Download
- README.md数据集说明、免责声明、复现方式Download
一键复制需求摘要One-click copy: concise requirements summary
When2Buy Options Data Standard v1.0 (draft, 2026-07-29) — requesting historical US options data: P0 = SPX/SPY/QQQ/IWM + VIX/VIX1D/VIX9D options and underlying bars, full 0DTE daily expiries, tick/1s raw preferred (1min derived acceptable), regular+extended session flags, history 2017-present (min. 2020-present). Required products: contract master, NBBO quotes, trades, chain snapshot, Greeks/IV (with model + as-of metadata), underlying OHLCV, OI/volume/EOD settlement, corporate actions/calendar/rates. Delivery: Parquet+ZSTD bulk, JSON/CSV samples, partitioned by venue/root/trade_date/expiration_date, UTC event time + exchange local date, schema_version + dataset_version, immutable manifests with SHA-256, daily incremental + historical backfill, no silent overwrite on corrections. Quality: unique event keys, monotonic sequencing, bid≤ask, referential integrity, freshness/missingness metrics, full-chain coverage at 09:35/10:00/10:30/12:00/15:30/15:55 America/New_York, proposed thresholds ≥99.9% file readability / ≥99.5% required-field completeness / ≥99% liquid-contract checkpoint coverage / exact checksum match / ≤0.001% duplicate rate. Open questions for Bitget: source/exchange coverage, OPRA/NBBO entitlement & redistribution rights, historical depth, granularity, quote size availability, correction handling, Greeks methodology, corporate action handling, delivery mechanism, and a sample week including one volatile day.
可视化 / 验收视图Visualization & Acceptance Views
期权链矩阵Chain matrix by strike
按行权价排列的看跌/看涨双侧 bid/ask、IV、delta；高亮铁鹰组合 4 条腿。
波动率微笑 / 偏斜Volatility smile / skew
按行权价绘制的隐含波动率曲线（put-call 平价下同一行权价单一 IV 值）。
买卖价差与报价新鲜度Bid/ask spread & quote freshness
4 条腿的最新价差（美元）与上次报价更新以来的秒数，双边报价覆盖情况。
日内标的走势与入场时点Intraday underlying with entry & legs
SPY 09:30–09:39 ET 分钟线，标注 09:35 入场时刻与 4 个行权价参考线。
数据完整性热力图Data completeness heatmap
按数据产品 × 每日检查点（09:35/10:00/10:30/12:00/15:30/15:55 ET）展示的示例完整性百分比。
交付与存储标准Delivery & Storage Standard
存储格式Format
- 批量数据：Parquet + ZSTD 压缩
- 样例/交互：JSON / CSV（仅样例，非批量交付格式）
- 分区方案：
venue=.../root=.../trade_date=.../expiration_date=...
版本与完整性Versioning & Integrity
- UTC event time + exchange local date 双时间字段
schema_version/dataset_version显式标注- 不可变 manifest 文件 + 每文件 SHA-256 校验和（见 sample_manifest.json）
更新节奏Cadence
- 每日增量交付 + 完整历史回补（backfill）
- 支持迟到更正/修订（late corrections/revisions）
不可覆盖原则No silent overwrite
- 任何更正需以新版本/新记录追加，禁止静默覆盖历史文件
- 更正记录需可追溯到被修正的原始事件（sequence_number / is_correction）
数据质量 SLA 与可执行验收测试Data Quality SLA & Executable Acceptance Tests
- 唯一性：无重复的事件主键（no duplicated event key）
- 单调序列：同一 instrument/venue/day 内 sequence_number 单调递增
- 价格合理性：bid ≤ ask；价格与数量非负；交叉/锁定盘口仅在带条件标记时保留
- 参照完整性：所有事件的 instrument_id 均可关联到 contract master
- 报价新鲜度与缺失率指标（quote freshness / missingness metrics）
- 关键检查点全链覆盖：09:35 / 10:00 / 10:30 / 12:00 / 15:30 / 15:55 America/New_York
- 公司行为一致性检查（corporate action consistency）
- 对账计数与校验和核对（reconciliation counts / checksums）
拟议验收阈值Proposed acceptance thresholds (not yet agreed)
| Metric | Proposed threshold |
|---|---|
| 文件可读性 File readability | ≥ 99.9% |
| 必填字段完整率 Required-field completeness | ≥ 99.5% |
| 流动性合约检查点覆盖 Liquid-contract checkpoint coverage | ≥ 99% |
| 校验和匹配 Checksum match | Exact match |
| 重复率 Duplicate rate | ≤ 0.001% |
| 时间戳精度 Timestamp accuracy | 需按数据源实际粒度另行约定 / to be agreed per feed granularity |
以上均为「拟议」阈值（proposed acceptance thresholds），尚未与 Bitget 或数据供应方最终确认。
Bitget 交接清单与待确认问题Bitget Handoff Checklist & Open Questions
以下问题需要 Bitget（或其数据供应方）在正式合作前给出明确答复：
- 数据源与交易所覆盖范围 Source / exchange coverage — 具体覆盖哪些交易所与整合商？
- OPRA / NBBO 授权与再分发权限 Entitlement & redistribution rights — When2Buy 是否可将数据用于内部回测、再加工或对外展示？
- 历史深度 Historical depth — 实际可提供的最早日期是多少？
- 数据粒度 Granularity — 是否支持 tick / 1 秒级，还是仅有 1 分钟及以上聚合？
- 报价数量 Quote size — NBBO 报价是否包含 bid/ask size，还是仅有价格？
- 更正机制 Corrections — 迟到更正/撤销如何标记与回填，是否保留原始事件？
- 希腊值方法论 Greeks methodology — 使用何种定价模型、利率曲线与股息假设？是否可自定义重算？
- 公司行为处理 Corporate actions — 历史行权价/价格是否已做拆股复权，复权方法是否可追溯？
- 交付机制 Delivery mechanism — API / 批量文件 / 对象存储直传？增量与回补的具体流程？
- 样例周 Sample week — 请求包含至少一个高波动交易日的完整样例周，用于联合验收测试。
为何仅有成交价 OHLC 不足以支撑可执行回测Why trade-only OHLC is insufficient
期权策略（尤其是像本例中的 SPY 0DTE 铁鹰组合这类多腿结构）在实盘执行时，交易者面对的是四条腿各自的双边报价， 而不是单一的收盘价序列。仅有成交价 OHLC 无法回答以下问题，因此不足以支撑可执行回测：
- 四腿 NBBO：入场/出场时刻，四条腿是否同时有可成交的双边报价？滑点应基于 bid/ask 而非最后成交价估计。
- 报价数量（size）：标注的报价在当时是否有足够的挂单量支撑实际下单规模，还是仅为象征性的 1×1 报价？
- 报价新鲜度（quote age）：策略决策时刻的报价距离上次更新已过去多久，是否已经失效（stale quote）？
- 入场时刻的行权价关系（strike-at-entry）：标的价格相对于各腿行权价的位置，决定了该结构在入场瞬间的真实风险敞口，仅凭收盘价序列无法重建。