跳到主要内容
OptionData LogoOptionData

更新日期: 2026 年 8 月 19 日

API 更新日志

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

当前的请求/响应架构请查看各产品页面： 期权链 · 市场结构 · 历史 SQL · 实时

  1. 修复实时 WebSocket2026 年 8 月 19 日

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

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

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

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

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

    • 请在乘法或聚合前转换定点数操作数；例如，计算权利金时可使用 SUM(toFloat64(price) * size * 100)。
    • 响应仍会保护隐私，不会包含提交的 SQL 或数据库内部错误文本。
  3. 修复历史 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。
  4. 新增通用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。
  5. 变更历史 SQL破坏性2026 年 8 月 10 日

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

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

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

    修正期权链 as_of 时间戳

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

    • 此前的时间值可能相差四至五小时。此修复会自动生效，客户端无需修改。
    • 响应结构不变：meta.as_of 仍为可空的 UTC ISO 8601 字符串。
  7. 变更历史 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。
  8. 新增市场结构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 字段含义保持不变。
  9. 新增市场结构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 状态可由行权价数据推导，因此不会在响应中重复存储。
  10. 变更期权链破坏性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，而不是返回部分数据。
  11. 变更历史 SQL2026 年 7 月 3 日

    扩展历史 SQL 校验规则

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

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

    行权价筛选

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

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

    移除 limit 请求参数

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

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

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

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

    • 移除请求参数：min_strike、max_strike、min_expiry_days 与 max_expiry_days。
    • 行权价筛选于 2026 年 7 月 1 日通过 strike、strike_min 与 strike_max 恢复。
  15. 移除期权链破坏性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 字段继续提供每份合约的最新成交价。
  16. 变更通用破坏性2026 年 6 月 22 日

    API 基础地址迁移至 www

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

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

    响应中新增 Beta 元数据

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

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

    修正文档中的情绪筛选值

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

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

    移除实时逐笔字段

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

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

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