跳到主要内容
OptionData LogoOptionData

更新日期: 2026 年 10 月 14 日

API 更新日志

OptionData 数据 API（市场结构、期权链、实时 WebSocket、历史 SQL）的请求、响应与接口契约变更记录。破坏性变更已标注。

当前的请求/响应架构请查看 API 参考文档： 期权链 · 市场结构 · 历史 SQL · 实时

34 条更新

  1. 变更历史 SQL破坏性尚未发布

    试用历史 SQL：过去 7 天，每次响应最多 1,000 行

    试用订阅现可查询滚动 7 天窗口（连续 168 小时，约五个交易日），每次响应最多返回 1,000 行（原为 10 行）。试用成功响应包含 meta.lookback_days: 7。

    • 与付费订阅相同，窗口之外的成交会在连接与聚合前被排除。此前查询更早日期的试用查询现在只返回窗口内的成交。
    • 试用响应的 meta.capped 仍为 true。付费访问、15 分钟延迟与测试模式模拟样例不变。
  2. 新增通用尚未发布

    403 SUBSCRIPTION_REQUIRED 说明原因及恢复权限的位置

    期权链、市场结构与历史 SQL 接口在 HTTP 403 SUBSCRIPTION_REQUIRED 响应中新增 reason "NO_ACTIVE_SUBSCRIPTION" 与 billing_url "/billing"。期权链与市场结构将其放在 error 对象内；历史 SQL 将其与 errorCode、errorMsg 并列。

    • 现有字段与状态码不变。billing_url 是 www.optiondata.io 上的路径，账户所有者可在该页面恢复 Pro 权限。
  3. 修复实时 WebSocket尚未发布

    AGGREGATED 模式的 market_cap 与 updated_timestamp 以数字发送

    AGGREGATED 模式下，实时流此前以 JSON 字符串发送 market_cap 与 updated_timestamp，现按字段说明以 JSON 数字发送。RAW 模式的 updated_timestamp 此前已为数字。

    • 字段数值不变。使用数字解析转换这两个字段的客户端无需修改；将原始值按字符串处理的客户端需改为接受数字。
  4. 修复市场结构尚未发布

    无法连接快照服务时返回可重试的 503

    当市场结构接口对快照服务的请求在收到任何响应前失败时，返回 HTTP 503 与错误代码 UPSTREAM_UNAVAILABLE。此前这类请求返回 HTTP 500 与 INTERNAL_ERROR。

    • 请稍后重试同一请求。快照服务超时或返回错误状态时，此前已返回 503。
  5. 修复通用2026 年 10 月 14 日

    API 密钥无法及时验证时返回可重试的 503

    当账户服务无法及时确认 API 密钥时，期权链、市场结构与历史 SQL 接口返回 HTTP 503、错误代码 UPSTREAM_UNAVAILABLE 以及 Retry-After 响应头。此前这类请求返回 HTTP 500 与 INTERNAL_ERROR。

    • 请在 Retry-After 指定的秒数后重试同一请求。无效或已撤销的密钥仍返回 401 UNAUTHORIZED。
    • 期权链使用 { error: { code, message } }，历史 SQL 使用 errorCode；市场结构此前已在快照服务不可用时使用 UPSTREAM_UNAVAILABLE。
  6. 新增实时 WebSocket2026 年 10 月 8 日

    实时流新增按到期日精确筛选

    WebSocket 与 SSE 实时流新增 expiration_date 查询参数：一个或多个 YYYY-MM-DD 格式的到期日，以逗号分隔。现有参数保持不变。

    • 当记录的 expiration_date 等于所列日期之一时通过筛选。与 expiry_days 不同，该筛选不会随交易日推移而变化，因此 symbols、put_call、strike 与 expiration_date 组合可跟踪单个合约。
    • 日期必须为 YYYY-MM-DD 格式；其他格式的值不会匹配任何记录。该参数在 AGGREGATED 与 RAW 模式下均可用。
  7. 变更市场结构2026 年 10 月 8 日

    市场结构字段与数据时效说明完善

    API 参考文档与 OpenAPI schema 现补充 RV20/RV30、波动率元数据、到期日范围和各部分独立的数据时间说明。本次为文档更新，不改变响应行为。

    • rv20 与 rv30 为基于 20 或 30 个有效交易日对数收益率计算的年化已实现波动率，使用小数表示。rv_as_of 标明计算包含的最近已完成交易日。这些字段为可选字段，较早快照可能不包含。
    • 到期日范围以 meta.effective_date 为基准，按日历天计算：zero_dte 为 0 天，weekly 为 1–7 天，monthly 为 8–31 天，all 包含所有尚未到期的到期日。
    • 请分别检查 meta.structure_as_of、meta.flow_as_of 与 meta.intraday_gex_as_of。结构价位随完整期权链快照更新；交易时段资金流与日内 GEX 通常约每五分钟更新一次。显式指定的 date 不会被替换为其他交易日。
  8. 变更期权链2026 年 10 月 8 日

    期权链数据时效与日期语义说明完善

    API 参考文档与快速入门现明确区分最新可用交易日、成交驱动的更新和单个合约的数据时效。本次为文档更新；响应字段及预期约 90 秒的更新间隔保持不变。

    • 将响应视为当前数据前，请检查 meta.trading_date 与 meta.as_of。meta.as_of 表示响应所包含的最新期权链快照时间或成交时间，并不保证所有合约均为最新。有较长时间未成交的合约可能保留较早的期权链数值。
    • 显式指定的 date 选择该交易日已存储的期权链，不提供日内回放。行权价筛选值必须为正数；strike 不能与 strike_min 或 strike_max 同时使用。
  9. 修复期权链2026 年 10 月 2 日

    买价与卖价由当日成交补全

    bid 与 ask 现为该合约在当日交易时段最近一笔成交时记录的最优买价与卖价。此前多数合约没有报价，历史交易日完全没有。

    • 适用于最新交易日及所有历史日期。当日没有成交的合约，两个字段仍返回 null。
    • 报价来自合约最近一笔成交，若合约最后成交较早，则报价也较早。
  10. 变更期权链破坏性2026 年 10 月 2 日

    无效日期与缺失期权链返回错误

    无法返回期权链的请求现在返回错误，而不是返回其他交易日的数据或空的 200 响应。

    • date 或 expiration_date 中不存在的日历日期（如 2026-02-30）返回 400 INVALID_REQUEST。此前可能返回之后某个交易日的期权链。
    • 没有已存储交易日的日期（周末、节假日、未来日期或超出保留期）返回 404 SNAPSHOT_NOT_FOUND；该交易日没有期权链的标的返回 404 SYMBOL_NOT_FOUND。
    • 期权链存在但筛选条件没有匹配合约时，仍返回 200 与空的 data 数组。
  11. 修复期权链破坏性2026 年 10 月 2 日

    不可用的报价与希腊值返回 null

    合约没有已存储报价时，bid 与 ask 返回 null 而非 0；没有模型值时，implied_volatility 与希腊值一同返回 null 而非 0。

    • 对这些字段计算前请先处理 null。单个 0 值（例如 bid 为 0、ask 为正）仍是真实数值。
  12. 新增历史 SQL2026 年 10 月 2 日

    历史 SQL 返回截断标记与错误码

    成功响应包含 meta.truncated：查询结果超过 meta.row_limit 时为 true。所有错误响应现在都包含 errorCode。

    • meta.capped 含义不变：表示适用试用行数上限，并不代表结果被截断。
    • 新增 errorCode：INVALID_REQUEST、INVALID_SQL、UNAUTHORIZED、SUBSCRIPTION_REQUIRED、RATE_LIMITED 与 METHOD_NOT_ALLOWED。
  13. 修复通用2026 年 10 月 2 日

    不支持的 HTTP 方法返回 405

    以错误的方法调用 HTTP 数据接口时返回 405 METHOD_NOT_ALLOWED 与 Allow 响应头，而不是网站首页。

    • 适用于 /api/option-chain 与 /api/historical/sql（POST）以及 /api/v1/market-structure/{symbol}（GET）。OPTIONS 返回 204 与 Allow 响应头。
  14. 变更期权链2026 年 10 月 1 日

    最新期权链约每 90 秒更新一次

    美股交易时段内，不带 date 的请求返回的期权链约每 90 秒刷新一次：有成交的合约会获得更新的报价、希腊值、隐含波动率、成交量、持仓量和最新价。

    • 请求与响应结构不变。建议轮询间隔不短于 1–2 分钟，并在处理前比较 meta.as_of。
  15. 变更历史 SQL破坏性2026 年 9 月 12 日

    付费历史 SQL 访问限制为过去 15 天

    付费（active）订阅仅能查询过去 15 天的成交，即连续 360 小时，包含周末与节假日。现有 15 分钟延迟保持不变。

    • 连接与聚合前会排除更早的成交。跨越边界的查询仅包含范围内的成交；仅查询更早成交的行查询不返回数据。
    • 请将使用更早日期的查询更新为近期日期。付费成功响应包含 meta.lookback_days: 15。
    • 试用访问、行数限制与测试模式模拟样例不变。
  16. 修复实时 WebSocket2026 年 8 月 19 日

    连接数上限重试现已受到保护

    当 API token 已有五条实时连接时，新的 WebSocket 或 SSE 握手现返回带 Retry-After 的 HTTP 429，已有连接保持打开。

    • 请遵守 Retry-After 并使用指数退避后再重试。请关闭未使用的连接，使单个 token 保持在五条连接上限以内。
    • 第六次握手请求到达时，服务端不再驱逐已有连接。
  17. 修复历史 SQL2026 年 8 月 15 日

    数值溢出现返回可操作的查询错误

    超出支持数值范围的历史 SQL 表达式现返回 HTTP 422、errorCode = INVALID_QUERY 和 reason = NUMERIC_OVERFLOW，而不再返回 HTTP 500。

    • 请在乘法或聚合前转换定点数操作数；例如，计算权利金时可使用 SUM(toFloat64(price) * size * 100)。
    • 响应仍会保护隐私，不会包含提交的 SQL 或数据库内部错误文本。
  18. 修复历史 SQL2026 年 8 月 13 日

    无效的历史 SQL 现返回 INVALID_QUERY

    包含未知字段、函数、别名或不兼容数据类型的查询现返回 HTTP 422 和 errorCode = INVALID_QUERY，而不再返回 HTTP 500。

    • 响应现包含 UNKNOWN_IDENTIFIER 等安全的 reason 和可操作的 errorMsg，且不会暴露数据库内部错误文本。
    • 重试前请先修正 SQL。可通过 errorCode 区分 INVALID_QUERY、QUERY_TOO_BROAD、QUERY_TIMEOUT 与 INTERNAL_ERROR。
  19. 新增通用2026 年 8 月 10 日

    HTTP 数据 API 新增 Bearer 认证

    历史 SQL 与期权链现支持通过 Authorization: Bearer 传递 API 密钥，与市场结构 API 保持一致。

    • 请通过 Authorization: Bearer YOUR_API_KEY 传递在 OptionData Portal 中生成的 API 密钥。
    • 未提供 Authorization 请求头时，仍可在 JSON 或表单请求体中使用 api_key 字段，以保持向后兼容。
    • 提供 Authorization 时，其优先级高于 api_key。使用不支持的认证方式或错误的请求头格式会返回 HTTP 401。
  20. 变更历史 SQL破坏性2026 年 8 月 10 日

    稳定的历史 SQL 执行错误契约

    历史 SQL 执行失败现返回一致的 HTTP 状态码、错误代码与消息。

    • 扫描数据量过大的查询会返回 HTTP 422 和 errorCode = QUERY_TOO_BROAD。请缩小日期、标的或其他筛选范围后重试。
    • 执行超时返回 HTTP 504，并使用 errorCode = QUERY_TIMEOUT。
    • 其他意外执行失败返回 HTTP 500，并使用 errorCode = INTERNAL_ERROR。
  21. 修复期权链2026 年 8 月 10 日

    修正期权链 as_of 时间戳

    期权链 meta.as_of 现会正确返回响应中最新数据对应的 UTC 时间戳。

    • 此前的时间值可能相差四至五小时。此修复会自动生效，客户端无需修改。
    • 响应结构不变：meta.as_of 仍为可空的 UTC ISO 8601 字符串。
  22. 变更历史 SQL破坏性2026 年 8 月 10 日

    强制至少延迟 15 分钟

    历史 SQL 现在仅返回执行时间至少已过去 15 分钟的成交记录。

    • 该时间边界适用于所有历史 SQL 查询，包括嵌套查询、联接与聚合。
    • 在美东时间 10:00:00，最新可见执行时间为 09:45:00。数据可能延迟超过 15 分钟，但不会短于最低延迟。
    • 成功响应元数据新增 meta.minimum_data_delay_minutes = 15，并返回对应的 X-OptionData-Historical-Sql-Minimum-Data-Delay-Minutes 响应头。
    • 如需不受历史时间边界限制的当日实时成交，请使用实时 WebSocket API。
  23. 新增市场结构2026 年 7 月 27 日

    盘中 GEX 汇总与更新时间

    v1 响应新增可为空的五分钟完整期权链 GEX 汇总及其更新时间戳。

    • 成功响应现包含 data.intraday_gex: { spot, call_gex, put_gex } | null 与 meta.intraday_gex_as_of: string | null。
    • 常规交易时段内，资金流与盘中 GEX 可每五分钟刷新。GEX 包含零成交合约；资金流字段仍仅包含有成交的合约。
    • structure_as_of 表示按行权价 GEX、关键墙位、Gamma Flip、Max Pain、OI 与到期日的最近计算时间。这些值不会随五分钟资金流更新而刷新。
    • 这是 v1 架构的增量变更；现有 structure 与 flow 字段含义保持不变。
  24. 新增市场结构2026 年 7 月 24 日

    市场结构 API 响应架构 v1

    新增完整期权链标的快照 v1 成功与错误响应契约。

    • 新增端点：GET /api/v1/market-structure/:symbol。使用 Authorization: Bearer YOUR_API_KEY 认证；添加 date=YYYY-MM-DD 可读取保留的历史快照。
    • 成功响应使用 { data: { symbol, symbol_meta, structure, flow }, meta: { effective_date, structure_as_of, flow_as_of } }。
    • 错误响应使用 { error: { code, message } }。稳定错误代码包括 INVALID_REQUEST、UNAUTHORIZED、SUBSCRIPTION_REQUIRED、SNAPSHOT_NOT_FOUND、SYMBOL_NOT_FOUND、RATE_LIMITED、UPSTREAM_UNAVAILABLE 和 INTERNAL_ERROR。
    • data 与 meta 对象包括按行权价与到期日统计的看涨/看跌 GEX、GEX/OI 墙、按范围计算的 Gamma Flip 与 Max Pain，以及最新期权资金流指标。
    • 标的元数据完整内嵌：标的类型、名称、交易所、板块、市值、股本、财报、价格、平均成交量、历史波动率、IV30、IV Rank/Percentile、偏斜、蝶式与期限斜率。
    • 看跌 GEX 使用负号。净 GEX、总 GEX、看跌/看涨比率与 Gamma 状态可由行权价数据推导，因此不会在响应中重复存储。
  25. 变更期权链破坏性2026 年 7 月 9 日

    精简期权链响应结构

    破坏性变更：成功响应现在使用 { data, meta: { trading_date, as_of } }，错误响应使用 { error: { code, message } }。

    • meta.trading_date 表示响应对应的市场交易日。meta.as_of 表示响应中最新的数据更新时间，格式为 UTC ISO 8601；时间不可用时可为 null。
    • 合约行移除了 symbol、expiry_days 和 mark。close 更名为 last_price；strike 与 expiration_date 现在为非空字段。
    • 响应中移除了 status、api_version、beta、notice、entitlement、source、returned、filters 和 statistics，同时移除了 test_mode 请求参数。
    • 错误响应现在提供稳定的 code 与 message。错误代码包括 INVALID_REQUEST、UNAUTHORIZED、SUBSCRIPTION_REQUIRED、REQUEST_TOO_BROAD、RATE_LIMITED、INTERNAL_ERROR 和 QUERY_TIMEOUT。
    • 迁移方式：直接读取 data，不再检查 status === "SUCCESS"；将 meta.date 替换为 meta.trading_date，并将 close 替换为 last_price。
    • 结果超过最大支持期权链大小的请求会返回 HTTP 422 和 REQUEST_TOO_BROAD，而不是返回部分数据。
  26. 变更历史 SQL2026 年 7 月 3 日

    扩展历史 SQL 校验规则

    不支持的多表与表函数查询形式现会返回校验错误。

    • 不支持 FROM table_a, table_b 这类逗号分隔联接。
    • 请直接使用文档中的表名，不要添加数据库前缀；指向其他数据库的引用会被拒绝。
    • 不支持 url()、remote()、merge() 等表函数，也不支持 # 注释。
    • 文档中的单表 SELECT 示例不受影响。
  27. 新增期权链2026 年 7 月 1 日

    行权价筛选

    期权链请求新增行权价筛选参数。

    • 新增请求参数：strike 用于精确匹配，strike_min 与 strike_max 用于闭区间筛选。
    • strike 不能与 strike_min 或 strike_max 同时使用。
    • 每个值均可使用数字；在表单编码请求中也可使用数字字符串。
  28. 移除期权链破坏性2026 年 6 月 26 日

    移除 limit 请求参数

    API 不再接受客户端传入的 limit 参数。

    • 请使用 date、expiration_date、put_call、strike、strike_min 或 strike_max 缩小标的请求范围。
    • 自 2026 年 7 月 9 日起，超过最大响应大小的请求会返回错误，而不是部分数据。
  29. 移除期权链破坏性2026 年 6 月 25 日

    移除行权价与到期日区间参数

    移除旧版行权价与到期日区间参数。

    • 移除请求参数：min_strike、max_strike、min_expiry_days 与 max_expiry_days。
    • 行权价筛选于 2026 年 7 月 1 日通过 strike、strike_min 与 strike_max 恢复。
  30. 移除期权链破坏性2026 年 6 月 25 日

    移除 flow 字段与 include_flow

    响应中移除了可选的 flow 字段以及 include_flow 开关。

    • 移除 include_flow 请求参数，以及 premium、size、trade_count、latest_trade_price、latest_trade_time 与 vol_oi_ratio 响应字段。
    • 此次变更后，close 字段继续提供每份合约的最新成交价。
  31. 变更通用破坏性2026 年 6 月 22 日

    API 基础地址迁移至 www

    API 规范主机名现为 www 子域名。

    • 基础地址现为 https://www.optiondata.io；此前为 https://optiondata.io。
    • 请将 POST /api/historical/sql 与 POST /api/option-chain 请求更新为新的基础地址。
  32. 新增期权链2026 年 6 月 21 日

    响应中新增 Beta 元数据

    每个期权链响应现在都会标注其 Beta 状态。

    • 响应包含 meta.api_version = "v1"、meta.beta = true 与 meta.notice。
    • 响应同时包含 X-OptionData-Option-Chain-Beta: true。
    • 这些 Beta 字段随后在 2026 年 7 月 9 日的响应架构变更中移除。
  33. 修复实时 WebSocket2026 年 3 月 5 日

    修正文档中的情绪筛选值

    文档中的中性情绪筛选值为 NEUTRAL。

    • 请使用 NEUTRAL；此前文档曾将该值误写为 NEUTRUAL。
  34. 移除实时 WebSocket破坏性2026 年 2 月 24 日

    移除实时逐笔字段

    实时逐笔交易消息中移除了若干字段。

    • 移除字段：bid_size、ask_size、vega、theta、rho 与 exchange。

本日志仅记录数据 API 的架构与接口变更。产品、账单与平台更新请查看博客。