API Dealer Hedge Flow

L'API Dealer Hedge Flow indique comment les dealers d'options sont positionnés sur les options BTC de Deribit et ce que ferait leur couverture si le prix bougeait : pour chaque niveau de prix, combien de dollars américains de BTC les dealers devraient acheter ou vendre pour rester couverts en delta en chemin, et si ce flux amplifie ou amortit le mouvement. Elle renvoie aussi l'exposition gamma nette (GEX), le niveau zero gamma et quelques statistiques d'options historiques (legacy). Un nouvel instantané est calculé toutes les heures.

Reconstruction des positions des dealers, formules et hypothèses : Méthodologie du Dealer Hedge Flow.

Pas un signal de trading

Le Dealer Hedge Flow est un modèle descriptif du positionnement des dealers, pas un objectif de prix ni un signal de trading.

Endpoints

Méthode	Chemin	Description
`GET`	`/v1/options/gex`	Série quotidienne : une ligne par jour (l'instantané de 00:00 UTC)
`GET`	`/v1/options/gex/hourly`	Chaque instantané horaire (Pro)
`GET`	`/v1/options/gex/profile`	Flux de couverture par prix pour un instantané (par défaut : le plus récent)
`GET`	`/v1/options/gex/heatmap`	Matrice temps × prix de l'impact pour une heatmap

URL de base : https://api.blocklens.co. Toutes les réponses sont au format JSON dans l'enveloppe {"success": true, "data": …} : pour les séries, data est une liste de lignes (accompagnée de count, access et message) ; pour /profile et /heatmap, c'est un objet qui contient access. Les erreurs utilisent {"success": false, "message": {…}, "timestamp": "…"} (voir Erreurs).

Authentification

Toutes les requêtes nécessitent une clé d'API :

Authorization: Bearer YOUR_API_KEY

Consultez Authentification pour les clés d'API et Limites de débit et formules pour savoir quels niveaux incluent l'accès à l'API ainsi que les limites de requêtes.

Signes et unités

Tous les montants sont en USD. Les valeurs de GEX (net_gex, gex[], strikes[].call_gex / put_gex) sont en USD par mouvement de 1 % ; le flux de couverture et l'impact sont en USD pour l'ensemble du mouvement, du prix actuel jusqu'au niveau.
hedge_flow > 0 — les dealers achètent du BTC en chemin vers le niveau ; < 0 — ils vendent.
impact = hedge_flow × signe(niveau − spot) : > 0 — amplification (le flux prolonge le mouvement), < 0 — amortissement (il freine le mouvement).
net_gex > 0 — les dealers sont long gamma en net (régime d'amortissement) ; < 0 — short gamma en net (régime d'amplification).
spot est le prix de l'indice BTC de l'instantané ; les niveaux se situent sur une grille absolue de $500 dans une plage de ±30 % autour de ce prix.
zero_gamma est recherché dans une plage de ±50 % autour de spot ; il peut donc se trouver en dehors de la grille des niveaux ; null lorsque la courbe GEX garde le même signe sur cette plage.

Niveaux et historique

Les règles des niveaux sont appliquées par l'API elle-même, et pas uniquement par l'interface du Lab :

	Free	Pro, Enterprise
`/v1/options/gex` (quotidien)	les 30 derniers jours	historique complet depuis le 2026-03-16
`/v1/options/gex/hourly`	— (403)	oui
`/v1/options/gex/profile`	uniquement l'instantané le plus récent, sans `strikes`	n'importe quel instantané, avec `strikes`
`/v1/options/gex/heatmap`	`resolution=1d`, les 30 derniers jours	`1h`, `6h`, `1d`, historique complet

Chaque réponse contient un bloc 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 — le premier jour accessible à l'appelant (null pour l'historique complet).
resolutions, profile_history, strikes, hourly — ce que permet le niveau de l'appelant.
clipped — true lorsque la série quotidienne ou la heatmap a été interrogée pour des jours antérieurs à history_from et que ceux-ci ont été tronqués. Ces deux endpoints ne renvoient jamais 403 pour cette raison : ils renvoient la partie autorisée.
Un instantané passé via /profile (tout sauf le plus récent), /hourly et une heatmap 6h / 1h renvoient 403 en Free (voir Erreurs).

Instantanés et horodatage

Un instantané du tableau des options BTC de Deribit par heure, quelques secondes après l'heure pleine. L'historique commence le 2026-03-16 ; la période du 2026-06-08 au 2026-07-07 manque (interruption de la collecte), et certaines heures isolées sont ignorées lorsque le tableau était incomplet. Les données sont actualisées toutes les heures vers :20 UTC.
Les heures sont en UTC, au format ISO 8601. Les horodatages des instantanés comportent des microsecondes lorsque l'instantané en a ("2026-10-24T09:00:02.418731Z") : repassez une valeur de ts / times[] telle quelle à /profile?ts= et elle sélectionne exactement cet instantané. Un ts sans fraction de seconde correspond à n'importe quel instantané de cette seconde.
Un jour (la série quotidienne, /profile?date=, la heatmap 1d) correspond à l'instantané de 00:00 UTC de ce jour — le premier instantané du jour si celui de 00:00 manque. Il est éloigné de l'échéance quotidienne de 08:00 UTC ; la ligne d'un jour ne change donc plus une fois publiée.

GET /v1/options/gex

Série quotidienne, de la plus récente à la plus ancienne.

Paramètre	Valeur par défaut	Description
`from_date`	premier jour autorisé	`YYYY-MM-DD` (UTC) ; antérieure à la fenêtre du niveau → tronquée, `access.clipped = true`
`to_date`	dernier jour	`YYYY-MM-DD` (UTC, incluse)
`limit`	`100`	Nombre de jours (1–10 000), du plus récent au plus ancien
`fields`	tous	Noms de champs séparés par des virgules (`date` est toujours conservé)

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

Champ	Signification
`date`	Jour UTC
`hedge_snapshot_ts`, `spot`	L'instantané du jour utilisé pour les champs de flux de couverture et son prix de l'indice BTC
`net_gex`	GEX net des dealers à `spot`, Black-Scholes, en USD par mouvement de 1 % — le GEX net publié
`zero_gamma`	Le changement de signe de la courbe GEX recalculée le plus proche de `spot` (±50 %) ; `null` s'il n'y en a pas
`flow_up5`, `flow_dn5`, `flow_up10`, `flow_dn10`	Flux de couverture en USD si le prix variait de +5 % / −5 % / +10 % / −10 % par rapport à `spot`, calculé exactement à `spot` × 1.05 / 0.95 / 1.10 / 0.90
`snapshot_ts`, `btc_price`	L'instantané des champs legacy et son prix du BTC
`top_support_strike`, `top_support_gex`	Le strike dont le GEX est le plus positif (gamma de Deribit ; les strikes dont le \|GEX\| est inférieur à $1,000 sont exclus)
`top_resist_strike`, `top_resist_gex`	Le strike dont le GEX est le plus négatif (mêmes règles)
`pc_ratio_oi`, `pc_ratio_vol_24h`	Ratio put/call par intérêt ouvert et par volume sur 24 h
`max_pain`, `max_pain_expiry`	Strike de max pain de l'échéance la plus proche, et cette échéance
`legacy_total_gex`, `legacy_call_gex`, `legacy_put_gex`	GEX calculé sur le gamma publié par Deribit (arrondi à 1e-5 — biaisé par rapport à Black-Scholes) ; utilisez `net_gex`
`legacy_flip_point`	Changement de signe du GEX par strike entre les deux strikes qui encadrent le prix — pas un gamma flip ; utilisez `zero_gamma`

Les colonnes quotidiennes net_gex, zero_gamma, flow_* et top_*_strike sont aussi des métriques du catalogue (options_*, catégorie options), disponibles via /v1/metrics et l'outil MCP get_metric.

GET /v1/options/gex/hourly

Chaque instantané horaire, du plus récent au plus ancien (Pro). Mêmes champs que la série quotidienne, indexés par timestamp (l'heure de l'instantané) au lieu de date ; les valeurs legacy et les valeurs de flux de couverture d'un même instantané partagent une seule ligne.

Paramètre	Valeur par défaut	Description
`from_date`, `to_date`	—	`YYYY-MM-DD` (UTC, `to_date` incluse)
`limit`	`168`	Nombre d'instantanés (1–10 000) ; la valeur par défaut correspond à une semaine
`fields`	tous	Noms de champs séparés par des virgules (`timestamp` est toujours conservé)

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

Flux de couverture par prix pour un instantané.

Paramètre	Valeur par défaut	Description
`ts`	le plus récent	Heure de l'instantané (ISO 8601, UTC si aucun décalage) : le dernier instantané à cette heure ou avant. Incompatible avec `date`
`date`	—	`YYYY-MM-DD` (UTC) : l'instantané de 00:00 UTC de ce jour (le premier du jour). Incompatible avec `ts`

En Free, seul l'instantané le plus récent est accessible : omettez ts / date (un ts / date qui correspond à l'instantané le plus récent est également accepté).

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

L'exemple est abrégé : un profil réel compte une centaine de niveaux.

Champ	Signification
`ts`, `spot`	Heure de l'instantané et prix de l'indice BTC
`step`, `levels`	Pas de la grille ($500) et niveaux de prix, par ordre croissant, dans une plage de ±30 % autour de `spot`
`hedge_flow[i]`	Montant en USD que les dealers traitent si le prix passe de `spot` à `levels[i]` (> 0 achat, < 0 vente)
`impact[i]`	`hedge_flow[i]` signé par la direction du mouvement (> 0 amplification, < 0 amortissement)
`gex[i]`	GEX net des dealers recalculé comme si le prix était à `levels[i]`, en USD par 1 %
`net_gex`	GEX à `spot`
`zero_gamma`, `flips`	Le changement de signe de la courbe GEX le plus proche de `spot` et tous les changements de signe, par ordre croissant, dans une plage de ±50 % autour de `spot` (`null` / `[]` s'il n'y en a pas)
`flow`	Flux de couverture exactement à `spot` × 1.05 / 0.95 / 1.10 / 0.90 (`up5`, `dn5`, `up10`, `dn10`)
`max_amplify_level`, `max_dampen_level`	La bande de $500 dont le flux marginal d'amplification / d'amortissement est le plus élevé (`null` s'il n'y en a pas)
`method_version`	Version de la méthode de calcul
`legacy`	Valeurs legacy du même instantané (gamma de Deribit) : `flip_point`, `top_support_strike`, `top_resist_strike`, `total_gex`
`strikes`	GEX net par strike, calls et puts séparément, additionné sur toutes les échéances (Pro ; `null` en Free)

hedge_flow est cumulatif le long de la trajectoire du prix : pour lire une bande entre deux niveaux, prenez la différence, jamais la somme de plusieurs niveaux.

GET /v1/options/gex/heatmap

Paramètre	Valeur par défaut	Description
`resolution`	`1d`	`1d`, `6h` ou `1h` (Pro) : un instantané par intervalle — le premier (`1d` = l'instantané de 00:00 UTC)
`from`	`1d` : tout l'historique ; `6h` : les 180 derniers jours ; `1h` : les 30 derniers jours	Date ou date-heure ISO (UTC). Antérieure à la fenêtre du niveau → tronquée, `access.clipped = true`
`to`	maintenant	Date ISO (incluse) ou date-heure (exclue)
`price_min`, `price_max`	tous les niveaux	Restreignent la plage de prix, en USD (finis, ≥ 0, `price_min` < `price_max`)

from / to sont étendus vers l'extérieur jusqu'à des intervalles entiers 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] — l'impact en USD entiers à levels[l] pour l'instantané times[t] (> 0 amplification, < 0 amortissement). null en dehors de la plage de ±30 % propre à cet instantané ou dans un trou de sa grille.
times correspond aux heures réelles des instantanés, par ordre croissant ; l'espacement est irrégulier autour des lacunes de données (pas de lignes vides).
levels — une grille commune de $500 couvrant tous les instantanés renvoyés.
overlays.price — le spot de chaque ligne ; overlays.zero_gamma — son niveau zero gamma (null lorsqu'il n'y en a pas). Le niveau zero gamma peut se trouver en dehors de levels : coupez la ligne au bord lorsque vous la tracez.
scale — le 98e centile et le maximum de |impact| ; plafonnez l'échelle de couleurs à p98.

Limites et taille des réponses

resolution=1h couvre au maximum 90 jours par requête (400 sinon — utilisez 6h ou 1d pour des plages plus longues).
Une requête de heatmap peut couvrir au maximum 2 000 000 de cellules (instantanés × niveaux) ; les requêtes plus volumineuses renvoient 400 — utilisez une résolution plus grossière, une période plus courte ou price_min / price_max.
L'historique horaire complet représente environ 10 Mo de JSON non compressé. Les réponses sont compressées en gzip lors de la transmission. Pour un premier affichage, utilisez 1d ou 6h, ou une courte fenêtre en 1h.
Limites de requêtes par clé d'API : Limites de débit et formules.

Mises à jour et mise en cache

Un nouvel instantané est calculé toutes les heures de notre côté et publié vers :20 UTC ; d'ici là, l'heure précédente reste la plus récente.
Les réponses sont mises en cache sur le serveur et actualisées à l'arrivée de nouvelles données.
La même URL renvoie des données différentes selon le niveau ; les réponses sont donc envoyées avec Cache-Control: private, max-age=600 et Vary: Authorization — elles ne sont jamais stockées par les caches partagés.

Erreurs

Les erreurs sont renvoyées dans l'enveloppe {"success": false, "message": {…}, "timestamp": "…"} ; le tableau indique message.

Statut	Cas	`message`
400	Date ou heure invalide, `to_date` antérieure à `from_date`, `ts` et `date` à la fois, `resolution` inconnue, `price_min` / `price_max` non finis, négatifs ou `price_min >= price_max`, plage sans recouvrement avec les niveaux, plus de 90 jours en `1h`, heatmap de plus de 2 000 000 de cellules	`{"error": "Invalid parameter", "message": "resolution must be one of 1h, 6h, 1d"}`
401	Clé d'API absente ou invalide
403	Free : un instantané passé via `/profile`, `/hourly`, une heatmap `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	Aucun instantané pour le jour ou l'heure demandés, ou aucune donnée dans la plage demandée	`{"error": "Not found", "message": "no profile on 2026-06-20"}`
429	Limite de débit dépassée	Voir Limites de débit et formules

Endpoints​

Authentification​

Signes et unités​

Niveaux et historique​

Instantanés et horodatage​

GET /v1/options/gex​

GET /v1/options/gex/hourly​

GET /v1/options/gex/profile​

GET /v1/options/gex/heatmap​

Limites et taille des réponses​

Mises à jour et mise en cache​

Erreurs​