Dealer Heatmap API - Nightwatch

概览

Dealer Heatmap 数据集提供 90 天多到期 Dealer GEX 网格的最新快照与单 cell 的分钟级历史,与 Heatmap 面板同源同口径——API 返回的就是面板正在展示的数据。

端点	用途	配额消耗
`GET /v1/derived/heatmap/{ticker}/snapshot`	最新网格(整表)	1 unit / 次
`GET /v1/derived/heatmap/{ticker}/cell-history`	单个 cell 的 1 分钟历史序列(分页)	1 unit / 页

API Key 在账户页自助生成(见快速开始);鉴权方式为 Authorization: Bearer sk_live_...,配额包含于订阅。

响应字段

{
  "data": {
    "ticker": "SPY",
    "generated_at": "2026-07-08T14:30:15-04:00",
    "session_date_et": "2026-07-08",
    "market_status": "open",
    "state": "fresh",
    "spot_usd": 598.42,
    "expirations": ["2026-07-10", "2026-07-17"],
    "strikes_usd": [590.0, 595.0, 600.0],
    "cells": [
      {
        "strike_usd": 600.0,
        "expiration": "2026-07-10",
        "net_dealer_gex_usd": -1234567.0,
        "call_gex_usd": 2345678.0,
        "put_gex_usd": -3580245.0
      }
    ],
    "row_stacks": [
      {
        "strike_usd": 600.0,
        "row_net_wall_gex_usd": -2345678.0,
        "row_abs_wall_gex_usd": 4567890.0,
        "rank": 1
      }
    ],
    "scale": {
      "cap_abs_usd": 5678901.0,
      "row_cap_abs_usd": 6789012.0,
      "color_min_value_usd": -4567890.0,
      "color_max_value_usd": 3456789.0
    }
  }
}

读法要点

cells:行权价 × 到期日 的净 dealer gamma 敞口。正值倾向钉住/支撑,负值倾向助推/加速,与 Heatmap 面板配色语义一致。
row_stacks:按行权价跨到期聚合的”墙”强度排名,rank=1 为当前最强行。
scale:面板着色所用的比例参数,供你在自己的界面里复刻同款颜色映射。
到期覆盖:网格覆盖未来 90 天的挂牌到期列(含当日,如适用)。当日 0DTE 的专用快照与历史序列见 Dealer GEX API。
cells 缺席语义:属于真实挂牌面的 行权价 × 到期 组合即使敞口为 0 也会以 net_dealer_gex_usd: 0 返回;不在挂牌面或尚未水合的组合缺席,客户端按 0 处理即可。
market_status(open / closed)表示交易时段,与 state(数据质量:fresh / stale / waiting / degraded / disabled)语义分离。

Cell 历史(cell-history)

单个 行权价 × 到期日 cell 的 1 分钟净敞口序列,用于回看一个价位在盘中的演化。一次查询锚定一个 cell:expiration 与 strike 为必填参数。

参数	类型	说明
`expiration`	`YYYY-MM-DD`	必填,到期日(ET 日历日)
`strike`	数字	必填,行权价(美元,如 `600` 或 `600.5`)
`from` / `to`	ISO 8601	可选,时间窗口
`limit`	整数	默认 100,上限 500(超出按 500 钳制);一页恰好覆盖一个完整常规时段(390 分钟)
`cursor`	不透明串	上一页 `_meta.next_cursor` 原样回传

curl -s "https://api.yehangshe.com/v1/derived/heatmap/SPY/cell-history?expiration=2026-09-18&strike=600&limit=390" \
  -H "Authorization: Bearer sk_live_xxxxxxxx"

每行三个字段:minute_at(分钟时间戳)、net_dealer_gex_usd、spot_usd(该分钟的现货参照),按时间从新到旧排列;查询窗口为滚动 90 天。

归档是尽力而为语义:没有归档值的分钟直接缺行,不会插值、不会补零。消费端把缺行当作”该分钟无归档”处理,不要当作 0。

新鲜度与频率

数据按秒级节奏更新,响应 _meta.data_freshness_seconds 为权威新鲜度信号。轮询建议不高于 1 次/秒——更高频率不会拿到更新的数据,只会消耗配额与触发限流。 Heatmap 服务处于维护 / 恢复窗口时,两个端点返回 503 SERVICE_DISABLED(语义与处理方式见错误处理)——这类窗口通常是分钟级,降级处理后低频重试即可,不要按秒级自动重试循环;快照与历史的更多行为约定见数据新鲜度与通用约定。