Dealer Hedge Flow API

La Dealer Hedge Flow API muestra cómo están posicionados los dealers de opciones en las opciones BTC de Deribit y qué haría su cobertura si el precio se moviera: para cada nivel de precio, cuántos dólares estadounidenses de BTC tendrían que comprar o vender los dealers para seguir cubiertos en delta en el camino hasta ese nivel, y si ese flujo amplifica o amortigua el movimiento. También devuelve la exposición gamma (GEX) neta, el nivel zero gamma y algunas estadísticas de opciones heredadas. Cada hora se calcula un nuevo snapshot.

Cómo se reconstruyen las posiciones de los dealers, las fórmulas y los supuestos: Metodología de Dealer Hedge Flow.

No es una señal de trading

El Dealer Hedge Flow es un modelo descriptivo del posicionamiento de los dealers, no un objetivo de precio ni una señal de trading.

Endpoints

Método	Ruta	Descripción
`GET`	`/v1/options/gex`	Serie diaria: una fila por día (el snapshot de las 00:00 UTC)
`GET`	`/v1/options/gex/hourly`	Cada snapshot horario (Pro)
`GET`	`/v1/options/gex/profile`	Flujo de cobertura por precio para un snapshot (por defecto: el último)
`GET`	`/v1/options/gex/heatmap`	Matriz tiempo × precio del impacto para un mapa de calor

URL base: https://api.blocklens.co. Todas las respuestas son JSON con la envoltura {"success": true, "data": …}: en las series, data es una lista de filas (acompañada de count, access y message); en /profile y /heatmap es un objeto que contiene access. Los errores usan {"success": false, "message": {…}, "timestamp": "…"} (consulte Errores).

Autenticación

Todas las solicitudes requieren una clave de API:

Authorization: Bearer YOUR_API_KEY

Consulte Autenticación para las claves de API y Límites de tasa y planes para saber qué planes incluyen acceso a la API y cuáles son los límites de solicitudes.

Signos y unidades

Todos los importes están en USD. Los valores de GEX (net_gex, gex[], strikes[].call_gex / put_gex) son USD por movimiento del 1%; el flujo de cobertura y el impacto son USD para todo el movimiento desde el precio actual hasta el nivel.
hedge_flow > 0 — los dealers compran BTC en el camino hasta el nivel; < 0 — venden.
impact = hedge_flow × signo(nivel − spot): > 0 — amplificación (el flujo empuja el movimiento más lejos), < 0 — amortiguación (el flujo frena el movimiento).
net_gex > 0 — los dealers están netamente largos en gamma (régimen de amortiguación); < 0 — netamente cortos en gamma (régimen de amplificación).
spot es el precio del índice BTC en el snapshot; los niveles se sitúan en una cuadrícula absoluta de $500 dentro de ±30% de ese precio.
zero_gamma se busca dentro de ±50% de spot, por lo que puede quedar fuera de la cuadrícula de niveles; es null cuando la curva de GEX mantiene un mismo signo en ese rango.

Planes e historial

Las reglas de los planes las aplica la propia API, no solo la interfaz de Lab:

	Free	Pro, Enterprise
`/v1/options/gex` (diaria)	los últimos 30 días	historial completo desde el 2026-03-16
`/v1/options/gex/hourly`	— (403)	sí
`/v1/options/gex/profile`	solo el último snapshot, sin `strikes`	cualquier snapshot, con `strikes`
`/v1/options/gex/heatmap`	`resolution=1d`, los últimos 30 días	`1h`, `6h`, `1d`, historial completo

Cada respuesta incluye un bloque 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 — el primer día que el solicitante puede ver (null para el historial completo).
resolutions, profile_history, strikes, hourly — lo que permite el plan del solicitante.
clipped — true cuando se solicitaron a la serie diaria o al mapa de calor días anteriores a history_from y se recortaron. Estos dos endpoints nunca devuelven 403 por este motivo: devuelven la parte permitida.
Un snapshot pasado de /profile (cualquiera salvo el último), /hourly y un mapa de calor 6h / 1h devuelven 403 en el plan Free (consulte Errores).

Snapshots y hora

Un snapshot del tablero de opciones BTC de Deribit por hora, unos segundos después de la hora en punto. El historial comienza el 2026-03-16; falta el periodo 2026-06-08 … 2026-07-07 (interrupción de la recopilación) y se omiten horas sueltas cuando el tablero estaba incompleto. Los datos se actualizan cada hora hacia el minuto :20 UTC.
Las horas están en UTC, en formato ISO 8601. Las horas de los snapshots incluyen microsegundos cuando el snapshot los tiene ("2026-10-24T09:00:02.418731Z"): si pasa un valor de ts / times[] sin modificar a /profile?ts=, selecciona exactamente ese snapshot. Un ts sin fracciones de segundo coincide con cualquier snapshot dentro de ese segundo.
Un día (la serie diaria, /profile?date=, el mapa de calor 1d) es el snapshot de las 00:00 UTC de ese día (el primer snapshot del día si falta el de las 00:00). Queda lejos del vencimiento diario de las 08:00 UTC, por lo que la fila de un día no cambia una vez publicada.

GET /v1/options/gex

Serie diaria, de la más reciente a la más antigua.

Parámetro	Por defecto	Descripción
`from_date`	primer día permitido	`YYYY-MM-DD` (UTC); anterior a la ventana del plan → se recorta, `access.clipped = true`
`to_date`	último día	`YYYY-MM-DD` (UTC, inclusive)
`limit`	`100`	Número de días (1–10.000), del más reciente al más antiguo
`fields`	todos	Nombres de campo separados por comas (`date` se conserva siempre)

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)"
}

Campo	Significado
`date`	Día UTC
`hedge_snapshot_ts`, `spot`	El snapshot del día usado para los campos de flujo de cobertura y su precio del índice BTC
`net_gex`	GEX neto de los dealers en `spot`, Black-Scholes, USD por movimiento del 1% — el GEX neto publicado
`zero_gamma`	El cambio de signo de la curva de GEX recalculada más cercano a `spot` (±50%); `null` si no hay ninguno
`flow_up5`, `flow_dn5`, `flow_up10`, `flow_dn10`	Flujo de cobertura en USD si el precio se moviera +5% / −5% / +10% / −10% desde `spot`, exacto en `spot` × 1.05 / 0.95 / 1.10 / 0.90
`snapshot_ts`, `btc_price`	El snapshot de los campos heredados y su precio de BTC
`top_support_strike`, `top_support_gex`	El strike con el GEX positivo más alto (gamma de Deribit; se excluyen los strikes con \|GEX\| inferior a $1,000)
`top_resist_strike`, `top_resist_gex`	El strike con el GEX más negativo (mismas reglas)
`pc_ratio_oi`, `pc_ratio_vol_24h`	Ratio put/call por interés abierto y por volumen de 24 h
`max_pain`, `max_pain_expiry`	Strike de max pain del vencimiento más cercano, y ese vencimiento
`legacy_total_gex`, `legacy_call_gex`, `legacy_put_gex`	GEX sobre la gamma publicada por Deribit (redondeada a 1e-5, sesgada respecto a Black-Scholes); use `net_gex`
`legacy_flip_point`	Cambio de signo del GEX por strike entre los dos strikes que rodean el precio — no es un gamma flip; use `zero_gamma`

Las columnas diarias net_gex, zero_gamma, flow_* y top_*_strike también son métricas del catálogo (options_*, categoría options), disponibles a través de /v1/metrics y de la herramienta MCP get_metric.

GET /v1/options/gex/hourly

Cada snapshot horario, del más reciente al más antiguo (Pro). Los mismos campos que la serie diaria, indexados por timestamp (la hora del snapshot) en lugar de date; los valores heredados y los de flujo de cobertura de un mismo snapshot comparten fila.

Parámetro	Por defecto	Descripción
`from_date`, `to_date`	—	`YYYY-MM-DD` (UTC, `to_date` inclusive)
`limit`	`168`	Número de snapshots (1–10.000); el valor por defecto equivale a una semana
`fields`	todos	Nombres de campo separados por comas (`timestamp` se conserva siempre)

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

Flujo de cobertura por precio para un snapshot.

Parámetro	Por defecto	Descripción
`ts`	el último	Hora del snapshot (ISO 8601, UTC si no hay desfase): el último snapshot en esa hora o antes. No se combina con `date`
`date`	—	`YYYY-MM-DD` (UTC): el snapshot de las 00:00 UTC de ese día (el primero del día). No se combina con `ts`

En el plan Free solo está disponible el último snapshot: omita ts / date (también se acepta un ts / date que corresponda al último snapshot).

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}
  }
}

El ejemplo está abreviado: un perfil real tiene alrededor de un centenar de niveles.

Campo	Significado
`ts`, `spot`	Hora del snapshot y precio del índice BTC
`step`, `levels`	Paso de la cuadrícula ($500) y los niveles de precio, en orden ascendente, dentro de ±30% de `spot`
`hedge_flow[i]`	USD que negocian los dealers si el precio se mueve de `spot` a `levels[i]` (> 0 compran, < 0 venden)
`impact[i]`	`hedge_flow[i]` con el signo de la dirección del movimiento (> 0 amplificación, < 0 amortiguación)
`gex[i]`	GEX neto de los dealers recalculado como si el precio estuviera en `levels[i]`, USD por 1%
`net_gex`	GEX en `spot`
`zero_gamma`, `flips`	El cambio de signo de la curva de GEX más cercano a `spot` y todos los cambios de signo, en orden ascendente, dentro de ±50% de `spot` (`null` / `[]` si no hay ninguno)
`flow`	Flujo de cobertura exactamente en `spot` × 1.05 / 0.95 / 1.10 / 0.90 (`up5`, `dn5`, `up10`, `dn10`)
`max_amplify_level`, `max_dampen_level`	La franja de $500 con el mayor flujo marginal de amplificación / amortiguación (`null` si no hay ninguna)
`method_version`	Versión del método de cálculo
`legacy`	Valores heredados del mismo snapshot (gamma de Deribit): `flip_point`, `top_support_strike`, `top_resist_strike`, `total_gex`
`strikes`	GEX neto por strike, calls y puts por separado, sumado sobre los vencimientos (Pro; `null` en Free)

hedge_flow es acumulativo a lo largo de la trayectoria del precio: para leer una franja entre dos niveles, tome la diferencia, nunca la suma de varios niveles.

GET /v1/options/gex/heatmap

Parámetro	Por defecto	Descripción
`resolution`	`1d`	`1d`, `6h` o `1h` (Pro): un snapshot por bucket, el primero (`1d` = el snapshot de las 00:00 UTC)
`from`	`1d`: todo el historial; `6h`: los últimos 180 días; `1h`: los últimos 30 días	Fecha o fecha y hora ISO (UTC). Anterior a la ventana del plan → se recorta, `access.clipped = true`
`to`	ahora	Fecha ISO (inclusive) o fecha y hora (exclusiva)
`price_min`, `price_max`	todos los niveles	Recortan el rango de precios, USD (finitos, ≥ 0, `price_min` < `price_max`)

from / to se amplían hasta buckets completos de 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] — el impacto en USD enteros en levels[l] para el snapshot times[t] (> 0 amplificación, < 0 amortiguación). null fuera del propio rango de ±30% de ese snapshot o en un hueco de su cuadrícula.
times son las horas reales de los snapshots, en orden ascendente; el espaciado es irregular en torno a los huecos de datos (no hay filas vacías).
levels — una cuadrícula común de $500 que cubre todos los snapshots devueltos.
overlays.price — el spot de cada fila; overlays.zero_gamma — su nivel zero gamma (null donde no lo hay). El nivel zero gamma puede quedar fuera de levels: recorte la línea al dibujarla.
scale — el percentil 98 y el máximo de |impacto|; limite la escala de colores a p98.

Límites y tamaño de la respuesta

resolution=1h abarca como máximo 90 días por solicitud (en otro caso, 400; use 6h o 1d para rangos más largos).
Una solicitud de mapa de calor puede abarcar como máximo 2.000.000 de celdas (snapshots × niveles); las solicitudes mayores devuelven 400: use una resolución más gruesa, un periodo más corto o price_min / price_max.
El historial horario completo ocupa unos 10 MB de JSON sin comprimir. Las respuestas se envían comprimidas con gzip. Para una primera vista, use 1d o 6h, o una ventana 1h corta.
Límites de solicitudes por clave de API: Límites de tasa y planes.

Actualizaciones y caché

Cada hora calculamos un nuevo snapshot, que se publica hacia el minuto :20 UTC; hasta entonces, la hora anterior es la más reciente.
Las respuestas se almacenan en caché en el servidor y se actualizan cuando llegan datos nuevos.
La misma URL devuelve datos distintos según el plan, por lo que las respuestas se envían con Cache-Control: private, max-age=600 y Vary: Authorization — nunca se almacenan en cachés compartidas.

Errores

Los errores llegan en la envoltura {"success": false, "message": {…}, "timestamp": "…"}; la tabla muestra message.

Estado	Cuándo	`message`
400	Una fecha u hora no válida, `to_date` anterior a `from_date`, `ts` y `date` a la vez, `resolution` desconocida, `price_min` / `price_max` no finito, negativo o `price_min >= price_max`, un rango que no se solapa con los niveles, más de 90 días en `1h`, un mapa de calor de más de 2.000.000 de celdas	`{"error": "Invalid parameter", "message": "resolution must be one of 1h, 6h, 1d"}`
401	Clave de API ausente o no válida
403	Free: un snapshot pasado de `/profile`, `/hourly`, un mapa de calor `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	No hay snapshot para el día o la hora solicitados, o no hay datos en el rango solicitado	`{"error": "Not found", "message": "no profile on 2026-06-20"}`
429	Límite de tasa superado	Consulte Límites de tasa y planes

Endpoints​

Autenticación​

Signos y unidades​

Planes e historial​

Snapshots y hora​

GET /v1/options/gex​

GET /v1/options/gex/hourly​

GET /v1/options/gex/profile​

GET /v1/options/gex/heatmap​

Límites y tamaño de la respuesta​

Actualizaciones y caché​

Errores​