Dealer Hedge Flow API

La Dealer Hedge Flow API indica come sono posizionati i dealer di opzioni sulle opzioni BTC di Deribit e che cosa farebbe il loro hedging se il prezzo si muovesse: per ogni livello di prezzo, quanti dollari USA di BTC i dealer dovrebbero comprare o vendere per restare delta-hedged lungo il percorso fino a quel livello, e se quel flusso amplifica o smorza il movimento. Restituisce inoltre la gamma exposure (GEX) netta, il livello di zero gamma e alcune statistiche legacy sulle opzioni. Ogni ora viene calcolato un nuovo snapshot.

Come vengono ricostruite le posizioni dei dealer, le formule e le ipotesi: Metodologia del Dealer Hedge Flow.

Non è un segnale di trading

Il Dealer Hedge Flow è un modello descrittivo del posizionamento dei dealer, non un target di prezzo né un segnale di trading.

Endpoint

Metodo	Percorso	Descrizione
`GET`	`/v1/options/gex`	Serie giornaliera: una riga per giorno (lo snapshot delle 00:00 UTC)
`GET`	`/v1/options/gex/hourly`	Ogni snapshot orario (Pro)
`GET`	`/v1/options/gex/profile`	Flusso di hedging per prezzo di un singolo snapshot (predefinito: l'ultimo)
`GET`	`/v1/options/gex/heatmap`	Matrice tempo × prezzo dell'impatto per una heatmap

URL di base: https://api.blocklens.co. Tutte le risposte sono in JSON nell'envelope {"success": true, "data": …}: per le serie data è un elenco di righe (affiancato da count, access e message), per /profile e /heatmap è un oggetto che contiene access. Gli errori usano {"success": false, "message": {…}, "timestamp": "…"} (vedere Errori).

Autenticazione

Ogni richiesta deve includere una chiave API:

Authorization: Bearer YOUR_API_KEY

Consultare Autenticazione per le chiavi API e Limiti di frequenza e piani per sapere quali piani includono l'accesso API e quali sono i limiti di richiesta.

Segni e unità

Tutti gli importi sono in USD. I valori GEX (net_gex, gex[], strikes[].call_gex / put_gex) sono in USD per movimento dell'1%; flusso di hedging e impatto sono in USD per l'intero movimento dal prezzo corrente al livello.
hedge_flow > 0 — i dealer comprano BTC lungo il percorso verso il livello; < 0 — vendono.
impact = hedge_flow × segno(livello − spot): > 0 — amplificazione (il flusso spinge oltre il movimento), < 0 — smorzamento (il flusso gli si oppone).
net_gex > 0 — i dealer sono net long gamma (regime di smorzamento); < 0 — net short gamma (regime di amplificazione).
spot è il prezzo dell'indice BTC dello snapshot; i livelli si trovano su una griglia assoluta di $500 entro ±30% da esso.
zero_gamma viene cercato entro ±50% da spot, quindi può trovarsi fuori dalla griglia dei livelli; è null quando in quell'intervallo la curva GEX mantiene un solo segno.

Piani e storico

Le regole dei piani sono imposte dall'API stessa, non solo dall'interfaccia del Lab:

	Free	Pro, Enterprise
`/v1/options/gex` (giornaliero)	gli ultimi 30 giorni	storico completo dal 2026-03-16
`/v1/options/gex/hourly`	— (403)	sì
`/v1/options/gex/profile`	solo l'ultimo snapshot, senza `strikes`	qualsiasi snapshot, con `strikes`
`/v1/options/gex/heatmap`	`resolution=1d`, gli ultimi 30 giorni	`1h`, `6h`, `1d`, storico completo

Ogni risposta contiene un blocco 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 — il primo giorno visibile al chiamante (null per lo storico completo).
resolutions, profile_history, strikes, hourly — ciò che il piano del chiamante consente.
clipped — true quando per la serie giornaliera o per la heatmap sono stati richiesti giorni precedenti a history_from e questi sono stati esclusi. Questi due endpoint non restituiscono mai 403 per questo motivo: restituiscono la parte consentita.
Uno snapshot passato da /profile (qualsiasi snapshot diverso dall'ultimo), /hourly e una heatmap 6h / 1h restituiscono 403 con il piano Free (vedere Errori).

Snapshot e orari

Uno snapshot del board delle opzioni BTC di Deribit ogni ora, pochi secondi dopo l'ora esatta. Lo storico parte dal 2026-03-16; manca il periodo 2026-06-08 … 2026-07-07 (interruzione della raccolta dati) e le singole ore in cui il board era incompleto vengono saltate. I dati vengono aggiornati ogni ora verso il minuto :20 UTC.
Gli orari sono in UTC, ISO 8601. Gli orari degli snapshot riportano i microsecondi quando lo snapshot li ha ("2026-10-24T09:00:02.418731Z"): passando un valore di ts / times[] invariato a /profile?ts= si seleziona esattamente quello snapshot. Un ts senza frazioni di secondo corrisponde a qualsiasi snapshot entro quel secondo.
Un giorno (la serie giornaliera, /profile?date=, la heatmap 1d) è lo snapshot delle 00:00 UTC di quel giorno, oppure il primo snapshot del giorno se manca quello delle 00:00. È lontano dalla scadenza giornaliera delle 08:00 UTC, quindi la riga di un giorno non cambia più una volta pubblicata.

GET /v1/options/gex

Serie giornaliera, dalla più recente.

Parametro	Predefinito	Descrizione
`from_date`	primo giorno consentito	`YYYY-MM-DD` (UTC); se anteriore alla finestra del piano → escluso, `access.clipped = true`
`to_date`	ultimo giorno	`YYYY-MM-DD` (UTC, incluso)
`limit`	`100`	Numero di giorni (1–10.000), dal più recente
`fields`	tutti	Nomi dei campi separati da virgole (`date` viene sempre mantenuto)

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	Significato
`date`	Giorno UTC
`hedge_snapshot_ts`, `spot`	Lo snapshot del giorno usato per i campi del flusso di hedging e il relativo prezzo dell'indice BTC
`net_gex`	GEX netto dei dealer a `spot`, Black-Scholes, USD per movimento dell'1% — il GEX netto pubblicato
`zero_gamma`	Il cambio di segno della curva GEX ricalcolata più vicino a `spot` (±50%); `null` se non ce n'è nessuno
`flow_up5`, `flow_dn5`, `flow_up10`, `flow_dn10`	Flusso di hedging in USD se il prezzo si muovesse del +5% / −5% / +10% / −10% da `spot`, calcolato esattamente a `spot` × 1,05 / 0,95 / 1,10 / 0,90
`snapshot_ts`, `btc_price`	Lo snapshot dei campi legacy e il relativo prezzo di BTC
`top_support_strike`, `top_support_gex`	Lo strike con il GEX positivo più elevato (gamma di Deribit; sono esclusi gli strike con \|GEX\| inferiore a $1,000)
`top_resist_strike`, `top_resist_gex`	Lo strike con il GEX più negativo (stesse regole)
`pc_ratio_oi`, `pc_ratio_vol_24h`	Rapporto put/call per open interest e per volume nelle 24h
`max_pain`, `max_pain_expiry`	Strike di max pain della scadenza più vicina e la scadenza stessa
`legacy_total_gex`, `legacy_call_gex`, `legacy_put_gex`	GEX sulla gamma pubblicata da Deribit (arrotondata a 1e-5 — distorta rispetto a Black-Scholes); usare `net_gex`
`legacy_flip_point`	Cambio di segno del GEX per strike tra i due strike attorno al prezzo — non è un gamma flip; usare `zero_gamma`

Le colonne giornaliere net_gex, zero_gamma, flow_* e top_*_strike sono anche metriche del catalogo (options_*, categoria options) disponibili tramite /v1/metrics e lo strumento MCP get_metric.

GET /v1/options/gex/hourly

Ogni snapshot orario, dal più recente (Pro). Stessi campi della serie giornaliera, indicizzati per timestamp (l'orario dello snapshot) anziché per date; i valori legacy e quelli del flusso di hedging dello stesso snapshot condividono un'unica riga.

Parametro	Predefinito	Descrizione
`from_date`, `to_date`	—	`YYYY-MM-DD` (UTC, `to_date` incluso)
`limit`	`168`	Numero di snapshot (1–10.000); il valore predefinito corrisponde a una settimana
`fields`	tutti	Nomi dei campi separati da virgole (`timestamp` viene sempre mantenuto)

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

Flusso di hedging per prezzo di un singolo snapshot.

Parametro	Predefinito	Descrizione
`ts`	più recente	Orario dello snapshot (ISO 8601, UTC se senza offset): l'ultimo snapshot fino a quell'istante incluso. Non combinabile con `date`
`date`	—	`YYYY-MM-DD` (UTC): lo snapshot delle 00:00 UTC di quel giorno (il primo del giorno). Non combinabile con `ts`

Con il piano Free è disponibile solo l'ultimo snapshot: omettere ts / date (viene accettato anche un ts / date che corrisponde all'ultimo 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}
  }
}

L'esempio è abbreviato: un profilo reale ha circa un centinaio di livelli.

Campo	Significato
`ts`, `spot`	Orario dello snapshot e prezzo dell'indice BTC
`step`, `levels`	Passo della griglia ($500) e livelli di prezzo, in ordine crescente, entro ±30% da `spot`
`hedge_flow[i]`	USD che i dealer scambiano se il prezzo si muove da `spot` a `levels[i]` (> 0 acquisto, < 0 vendita)
`impact[i]`	`hedge_flow[i]` con il segno della direzione del movimento (> 0 amplificazione, < 0 smorzamento)
`gex[i]`	GEX netto dei dealer ricalcolato come se il prezzo fosse a `levels[i]`, USD per 1%
`net_gex`	GEX a `spot`
`zero_gamma`, `flips`	Il cambio di segno della curva GEX più vicino a `spot` e tutti i cambi di segno, in ordine crescente, entro ±50% da `spot` (`null` / `[]` se non ce ne sono)
`flow`	Flusso di hedging esattamente a `spot` × 1,05 / 0,95 / 1,10 / 0,90 (`up5`, `dn5`, `up10`, `dn10`)
`max_amplify_level`, `max_dampen_level`	La fascia da $500 con il flusso marginale di amplificazione / smorzamento più elevato (`null` se non ce n'è nessuna)
`method_version`	Versione del metodo di calcolo
`legacy`	Valori legacy dello stesso snapshot (gamma di Deribit): `flip_point`, `top_support_strike`, `top_resist_strike`, `total_gex`
`strikes`	GEX netto per strike, call e put separate, sommato su tutte le scadenze (Pro; `null` con il piano Free)

hedge_flow è cumulativo lungo il percorso del prezzo: per leggere una fascia tra due livelli calcolarne la differenza, mai la somma di più livelli.

GET /v1/options/gex/heatmap

Parametro	Predefinito	Descrizione
`resolution`	`1d`	`1d`, `6h` oppure `1h` (Pro): uno snapshot per intervallo — il primo (`1d` = lo snapshot delle 00:00 UTC)
`from`	`1d`: l'intero storico; `6h`: gli ultimi 180 giorni; `1h`: gli ultimi 30 giorni	Data o data e ora ISO (UTC). Se anteriore alla finestra del piano → escluso, `access.clipped = true`
`to`	adesso	Data ISO (inclusa) oppure data e ora (esclusa)
`price_min`, `price_max`	tutti i livelli	Restringono l'intervallo di prezzo, in USD (finiti, ≥ 0, `price_min` < `price_max`)

from / to vengono estesi verso l'esterno fino a intervalli interi di 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'impatto in USD interi a levels[l] per lo snapshot times[t] (> 0 amplificazione, < 0 smorzamento). null fuori dall'intervallo di ±30% proprio di quello snapshot o in un buco della sua griglia.
times sono gli orari reali degli snapshot, in ordine crescente; la spaziatura è irregolare in corrispondenza dei gap nei dati (nessuna riga vuota).
levels — un'unica griglia comune da $500 che copre tutti gli snapshot restituiti.
overlays.price — lo spot di ciascuna riga; overlays.zero_gamma — il relativo livello di zero gamma (null dove non esiste). Il livello di zero gamma può trovarsi fuori da levels: tagliare la linea quando la si disegna.
scale — il 98° percentile e il massimo di |impatto|; usare p98 come limite superiore della scala di colori.

Limiti e dimensione del payload

resolution=1h copre al massimo 90 giorni per richiesta (altrimenti 400 — per intervalli più lunghi usare 6h o 1d).
Una richiesta di heatmap può coprire al massimo 2.000.000 di celle (snapshot × livelli); le richieste più grandi restituiscono 400 — usare una risoluzione meno fine, un periodo più breve oppure price_min / price_max.
Lo storico orario completo pesa circa 10 MB di JSON non compresso. Le risposte vengono inviate compresse con gzip. Per una prima visualizzazione usare 1d o 6h, oppure una breve finestra 1h.
Limiti di richiesta per chiave API: Limiti di frequenza e piani.

Aggiornamenti e caching

Ogni ora calcoliamo un nuovo snapshot, pubblicato verso il minuto :20 UTC; fino ad allora l'ora più recente disponibile è quella precedente.
Le risposte sono memorizzate nella cache del server e aggiornate all'arrivo di nuovi dati.
Lo stesso URL restituisce dati diversi a seconda del piano, quindi le risposte vengono inviate con Cache-Control: private, max-age=600 e Vary: Authorization — non vengono mai memorizzate da cache condivise.

Errori

Gli errori arrivano nell'envelope {"success": false, "message": {…}, "timestamp": "…"}; la tabella riporta message.

Stato	Quando	`message`
400	Una data o un orario non validi, `to_date` precedente a `from_date`, sia `ts` sia `date`, `resolution` sconosciuta, `price_min` / `price_max` non finiti, negativi o `price_min >= price_max`, un intervallo che non si sovrappone ai livelli, più di 90 giorni con `1h`, una heatmap oltre 2.000.000 di celle	`{"error": "Invalid parameter", "message": "resolution must be one of 1h, 6h, 1d"}`
401	Chiave API mancante o non valida
403	Free: uno snapshot passato da `/profile`, `/hourly`, una 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	Nessuno snapshot per il giorno o l'orario richiesti, oppure nessun dato nell'intervallo richiesto	`{"error": "Not found", "message": "no profile on 2026-06-20"}`
429	Limite di frequenza superato	Vedere Limiti di frequenza e piani

Endpoint​

Autenticazione​

Segni e unità​

Piani e storico​

Snapshot e orari​

GET /v1/options/gex​

GET /v1/options/gex/hourly​

GET /v1/options/gex/profile​

GET /v1/options/gex/heatmap​

Limiti e dimensione del payload​

Aggiornamenti e caching​

Errori​