Dealer Hedge Flow API

Dealer Hedge Flow API 返回期权做市商在 Deribit BTC 期权上的持仓情况，以及价格变动时其对冲行为的影响：对于每个价位，做市商在价格移向该价位的过程中，为保持 Delta 对冲需要买入或卖出多少美元的 BTC，以及这笔资金流会放大还是抑制行情。API 还返回净 Gamma 敞口（GEX）、零 Gamma 位以及若干旧版期权统计数据。每小时计算一个新快照。

做市商持仓如何重建、公式与假设，请参阅 Dealer Hedge Flow 方法论。

非交易信号

Dealer Hedge Flow 是做市商持仓的描述性模型，而非价格目标或交易信号。

端点

方法	路径	描述
GET	/v1/options/gex	每日序列：每天一行（00:00 UTC 快照）
GET	/v1/options/gex/hourly	每个小时快照（Pro）
GET	/v1/options/gex/profile	单个快照按价格划分的对冲资金流（默认：最新快照）
GET	/v1/options/gex/heatmap	用于热力图的“时间 × 价格”影响值矩阵

基础 URL：https://api.blocklens.co。所有响应均为 JSON，外层结构为 {"success": true, "data": …}：对于序列，data 是数据行列表（与之并列的还有 count、access 和 message）；对于 /profile 和 /heatmap，则是一个包含 access 的对象。错误使用 {"success": false, "message": {…}, "timestamp": "…"}（参见错误）。

认证

所有请求都需要 API 密钥：

Authorization: Bearer YOUR_API_KEY

API 密钥请参阅认证；哪些套餐包含 API 访问权限以及请求限制，请参阅速率限制与订阅层级。

符号与单位

• 所有金额均以 USD 计。GEX 数值（net_gex、gex[]、strikes[].call_gex / put_gex）的单位为每 1% 变动的 USD；对冲资金流和影响值是价格从当前价格移动到该价位的整个过程中的 USD 总额。
• hedge_flow > 0——做市商在价格移向该价位的过程中买入 BTC；< 0——做市商卖出。
• impact = hedge_flow × sign(价位 − 现价)：> 0——放大（资金流推动行情继续发展），< 0——抑制（资金流对行情形成阻碍）。
• net_gex > 0——做市商净持有多头 Gamma（抑制状态）；< 0——净持有空头 Gamma（放大状态）。
• spot 为快照中的 BTC 指数价格；价位位于其 ±30% 范围内的固定 $500 网格上。
• zero_gamma 在 spot 的 ±50% 范围内搜索，因此可能位于价位网格之外；若 GEX 曲线在该范围内符号不变，则为 null。

订阅层级与历史

订阅层级规则由 API 本身强制执行，而不只是在 Lab 界面中生效：

	Free	Pro、Enterprise
/v1/options/gex（每日）	最近 30 天	自 2026-03-16 以来的完整历史
/v1/options/gex/hourly	—（403）	是
/v1/options/gex/profile	仅最新快照，不含 strikes	任意快照，含 strikes
/v1/options/gex/heatmap	resolution=1d，最近 30 天	1h、6h、1d，完整历史

每个响应都包含一个 access 块：

"access": {"tier": "free", "grade": 0, "full_history": false, "history_from": "2026-09-24",
           "resolutions": ["1d"], "profile_history": false, "strikes": false, "hourly": false,
           "required_grade": 1, "clipped": false}

• history_from——调用方可查看的第一天（完整历史时为 null）。
• resolutions、profile_history、strikes、hourly——调用方的订阅层级所允许的内容。
• clipped——当每日序列或热力图请求了 history_from 之前的日期且这些日期被截除时为 true。这两个端点不会因此返回 403，而是返回允许范围内的部分。
• 在 Free 层级下，通过 /profile 请求过去的快照（最新快照以外的任何快照）、请求 /hourly 以及请求 6h / 1h 热力图均返回 403（参见错误）。

快照与时间

• 每小时对 Deribit BTC 期权链拍摄一次快照，时间为整点后几秒。历史始于 2026-03-16；2026-06-08 … 2026-07-07 缺失（数据采集中断），期权链不完整的个别小时也会被跳过。数据每小时约在 :20 UTC 更新。
• 时间均为 UTC，ISO 8601 格式。若快照带有微秒，快照时间也会带上微秒（"2026-10-24T09:00:02.418731Z"）：将 ts / times[] 的值原样传回 /profile?ts=，即可精确选中该快照。不带小数秒的 ts 匹配该秒内的任意快照。
• 一天（每日序列、/profile?date=、1d 热力图）指当天的 00:00 UTC 快照；若缺少 00:00，则取当天第一个快照。它避开 08:00 UTC 的每日到期，因此某一天的数据行一经出现便不再变化。

GET /v1/options/gex

每日序列，最新的在前。

参数	默认值	描述
from_date	首个允许的日期	YYYY-MM-DD（UTC）；早于订阅层级窗口 → 被截除，access.clipped = true
to_date	最新日期	YYYY-MM-DD（UTC，含当天）
limit	100	天数（1–10,000），最新的在前
fields	全部	以逗号分隔的字段名（始终保留 date）

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.blocklens.co/v1/options/gex?from_date=2026-10-01&fields=btc_price,net_gex,zero_gamma,flow_up5,flow_dn5"

{
  "success": true,
  "data": [
    {"date": "2026-10-23", "snapshot_ts": "2026-10-23T00:00:02Z", "btc_price": 80712.4,
     "legacy_total_gex": 30112000.0, "legacy_call_gex": 41870000.0, "legacy_put_gex": -11758000.0,
     "top_support_strike": 80000.0, "top_support_gex": 9120000.0,
     "top_resist_strike": 76000.0, "top_resist_gex": -3410000.0, "legacy_flip_point": 80551.2,
     "pc_ratio_oi": 0.62, "pc_ratio_vol_24h": 0.81, "max_pain": 82000.0, "max_pain_expiry": "24OCT26",
     "hedge_snapshot_ts": "2026-10-23T00:00:02Z", "spot": 80712.4, "net_gex": 35700000.0, "zero_gamma": 59300.0,
     "flow_up5": -219000000.0, "flow_dn5": 288000000.0, "flow_up10": -402000000.0, "flow_dn10": 515000000.0}
  ],
  "count": 1,
  "access": {"tier": "pro", "grade": 1, "full_history": true, "history_from": null, "resolutions": ["1h", "6h", "1d"],
             "profile_history": true, "strikes": true, "hourly": true, "required_grade": 1, "clipped": false},
  "message": "Options GEX and dealer hedge flow, daily (Deribit BTC)"
}

字段	含义
date	UTC 日期
hedge_snapshot_ts, spot	当天用于对冲资金流字段的快照及其 BTC 指数价格
net_gex	spot 处做市商的净 GEX，基于 Black-Scholes，单位为每 1% 变动的 USD——即发布的净 GEX
zero_gamma	重新计算的 GEX 曲线上距 spot 最近的变号点（±50%）；没有时为 null
flow_up5, flow_dn5, flow_up10, flow_dn10	价格从 spot 变动 +5% / −5% / +10% / −10% 时以 USD 计的对冲资金流，恰好在 spot × 1.05 / 0.95 / 1.10 / 0.90 处计算
snapshot_ts, btc_price	旧版字段所用的快照及其 BTC 价格
top_support_strike, top_support_gex	GEX 正值最大的行权价（基于 Deribit 公布的 Gamma；|GEX| 低于 $1,000 的行权价不计入）
top_resist_strike, top_resist_gex	GEX 负值最大的行权价（规则相同）
pc_ratio_oi, pc_ratio_vol_24h	按未平仓量和按 24 小时成交量计算的看跌/看涨比率
max_pain, max_pain_expiry	最近到期日的最大痛点行权价及该到期日
legacy_total_gex, legacy_call_gex, legacy_put_gex	基于 Deribit 公布的 Gamma（舍入到 1e-5——相对 Black-Scholes 存在偏差）计算的 GEX；请使用 net_gex
legacy_flip_point	当前价格两侧两个行权价之间逐行权价 GEX 的变号点——并非 Gamma 翻转；请使用 zero_gamma

每日的 net_gex、zero_gamma、flow_* 和 top_*_strike 列同时也是目录指标（options_*，类别 options），可通过 /v1/metrics 和 MCP 工具 get_metric 获取。

GET /v1/options/gex/hourly

每个小时快照，最新的在前（Pro）。字段与每日序列相同，但以 timestamp（快照时间）而非 date 作为键；同一快照的旧版数值和对冲资金流数值位于同一行。

参数	默认值	描述
from_date, to_date	—	YYYY-MM-DD（UTC，to_date 含当天）
limit	168	快照数量（1–10,000）；默认为一周
fields	全部	以逗号分隔的字段名（始终保留 timestamp）

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.blocklens.co/v1/options/gex/hourly?limit=24&fields=spot,net_gex,zero_gamma"

GET /v1/options/gex/profile

单个快照按价格划分的对冲资金流。

参数	默认值	描述
ts	最新	快照时间（ISO 8601，未指定时区偏移时按 UTC）：返回该时刻或之前的最新快照。不可与 date 同时使用
date	—	YYYY-MM-DD（UTC）：当天的 00:00 UTC 快照（当天第一个快照）。不可与 ts 同时使用

Free 调用方只能获取最新快照：请省略 ts / date（解析结果为最新快照的 ts / date 也会被接受）。

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.blocklens.co/v1/options/gex/profile

{
  "success": true,
  "data": {
    "ts": "2026-10-24T09:00:02Z", "spot": 80712.4, "step": 500.0,
    "levels": [80000.0, 80500.0, 81000.0, 81500.0],
    "hedge_flow": [21400000.0, 4900000.0, -6800000.0, -27300000.0],
    "impact": [-21400000.0, -4900000.0, -6800000.0, -27300000.0],
    "gex": [36900000.0, 35900000.0, 35200000.0, 34100000.0],
    "net_gex": 35700000.0, "zero_gamma": 59300.0, "flips": [59300.0],
    "flow": {"up5": -219000000.0, "dn5": 288000000.0, "up10": -402000000.0, "dn10": 515000000.0},
    "max_amplify_level": null, "max_dampen_level": 74000.0, "method_version": 1,
    "legacy": {"flip_point": 80551.2, "top_support_strike": 80000.0, "top_resist_strike": 76000.0,
               "total_gex": 30112000.0},
    "strikes": [{"strike": 80000.0, "call_gex": 6200000.0, "put_gex": 2920000.0}],
    "access": {"tier": "pro", "grade": 1, "full_history": true, "history_from": null, "resolutions": ["1h", "6h", "1d"],
               "profile_history": true, "strikes": true, "hourly": true, "required_grade": 1, "clipped": false}
  }
}

示例已截短：真实的分布图约有一百个价位。

字段	含义
ts, spot	快照时间与 BTC 指数价格
step, levels	网格步长（$500）以及 spot ±30% 范围内按升序排列的价位
hedge_flow[i]	价格从 spot 移动到 levels[i] 时做市商成交的 USD 金额（> 0 买入，< 0 卖出）
impact[i]	按行情方向取符号的 hedge_flow[i]（> 0 放大，< 0 抑制）
gex[i]	假设价格位于 levels[i] 时重新计算的做市商净 GEX，单位为每 1% 的 USD
net_gex	spot 处的 GEX
zero_gamma, flips	spot ±50% 范围内 GEX 曲线上距 spot 最近的变号点，以及按升序排列的全部变号点（没有时为 null / []）
flow	恰好在 spot × 1.05 / 0.95 / 1.10 / 0.90 处的对冲资金流（up5、dn5、up10、dn10）
max_amplify_level, max_dampen_level	放大 / 抑制边际资金流最大的 $500 价位带（没有时为 null）
method_version	计算方法的版本
legacy	同一快照的旧版数值（基于 Deribit 公布的 Gamma）：flip_point、top_support_strike、top_resist_strike、total_gex
strikes	按行权价拆分的净 GEX，看涨与看跌分开，按到期日加总（Pro；Free 下为 null）

hedge_flow 沿价格路径累计：要读取两个价位之间价位带的数值，请取二者之差，切勿将多个价位的数值相加。

GET /v1/options/gex/heatmap

参数	默认值	描述
resolution	1d	1d、6h 或 1h（Pro）：每个时间桶取一个快照，即其中的第一个（1d = 00:00 UTC 快照）
from	1d：完整历史；6h：最近 180 天；1h：最近 30 天	ISO 日期或日期时间（UTC）。早于订阅层级窗口 → 被截除，access.clipped = true
to	当前时刻	ISO 日期（含当天）或日期时间（不含该时刻）
price_min, price_max	全部价位	裁剪价格范围，单位 USD（有限值、≥ 0、price_min < price_max）

from / to 会向外对齐到 resolution 的完整时间桶。

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.blocklens.co/v1/options/gex/heatmap?resolution=6h&from=2026-09-01"

{
  "success": true,
  "data": {
    "resolution": "1d", "times": ["2026-10-22T00:00:01Z", "2026-10-23T00:00:02Z"], "step": 500.0,
    "levels": [80000.0, 80500.0, 81000.0],
    "matrix": [[-18200000, null, -5100000], [-21400000, -4900000, -6800000]],
    "overlays": {"price": [80310.0, 80712.4], "zero_gamma": [null, 59300.0]},
    "scale": {"p98": 310000000, "max": 612000000},
    "access": {"tier": "pro", "grade": 1, "full_history": true, "history_from": null, "resolutions": ["1h", "6h", "1d"],
               "profile_history": true, "strikes": true, "hourly": true, "required_grade": 1, "clipped": false}
  }
}

• matrix[t][l]——快照 times[t] 在 levels[l] 处以整数 USD 计的影响值（> 0 放大，< 0 抑制）。超出该快照自身 ±30% 范围或落在其网格空洞处时为 null。
• times 为真实的快照时间，按升序排列；在数据空缺附近间隔不均匀（无空行）。
• levels——覆盖所有返回快照的统一 $500 网格。
• overlays.price——每一行的 spot；overlays.zero_gamma——该行的零 Gamma 位（没有时为 null）。零 Gamma 位可能位于 levels 之外：绘制时请截断该线。
• scale——|impact| 的第 98 百分位数和最大值；可将色阶上限设为 p98。

限制与负载大小

• resolution=1h 每次请求最多覆盖 90 天（否则返回 400——更长的范围请使用 6h 或 1d）。
• 单次热力图请求最多可覆盖 2,000,000 个单元格（快照 × 价位）；更大的请求将返回 400——请使用更粗的分辨率、更短的时段或 price_min / price_max。
• 完整的小时历史约为 10 MB 未压缩 JSON。响应在传输时采用 gzip 压缩。首次查看时，请使用 1d 或 6h，或较短的 1h 时间窗口。
• 每个 API 密钥的请求限制：速率限制与订阅层级。

更新与缓存

• 我们每小时计算一个新快照，约在 :20 UTC 发布；在此之前，最新数据仍是上一个小时的快照。
• 响应在服务器端缓存，并在新数据到达时刷新。
• 同一 URL 对不同订阅层级返回不同的数据，因此响应附带 Cache-Control: private, max-age=600 和 Vary: Authorization，不会被共享缓存存储。

错误

错误以 {"success": false, "message": {…}, "timestamp": "…"} 结构返回；下表列出的是 message。

状态码	触发条件	message
400	无效的日期或时间、to_date 早于 from_date、同时指定 ts 和 date、未知的 resolution、price_min / price_max 非有限值、为负数或 price_min >= price_max、范围与价位不重叠、1h 下超过 90 天、热力图超过 2,000,000 个单元格	{"error": "Invalid parameter", "message": "resolution must be one of 1h, 6h, 1d"}
401	API 密钥缺失或无效
403	Free：通过 /profile 请求过去的快照、请求 /hourly、请求 6h / 1h 热力图	{"error": "Insufficient tier", "message": "Profiles of past snapshots requires Pro", "required_grade": 1, "current_tier": "free", "current_grade": 0, "history_from": "2026-09-24", "upgrade_url": "https://blocklens.co/pricing"}
404	所请求的日期或时间没有快照，或所请求的范围内没有数据	{"error": "Not found", "message": "no profile on 2026-06-20"}
429	超出速率限制	参见速率限制与订阅层级