Dealer Hedge Flow API

A Dealer Hedge Flow API informa como os dealers de opções estão posicionados nas opções de BTC da Deribit e o que o hedge deles faria se o preço se movesse: para cada nível de preço, quantos dólares americanos em BTC os dealers teriam de comprar ou vender para manter o hedge de delta no caminho até lá, e se esse fluxo amplifica ou amortece o movimento. Ela também retorna a exposição gama (GEX) líquida, o nível de gama zero e algumas estatísticas legadas de opções. Um novo snapshot é calculado a cada hora.

Como as posições dos dealers são reconstruídas, as fórmulas e as premissas: Metodologia do Dealer Hedge Flow.

Não é um sinal de negociação

O Dealer Hedge Flow é um modelo descritivo do posicionamento dos dealers, não um alvo de preço nem um sinal de negociação.

Endpoints

Método	Caminho	Descrição
`GET`	`/v1/options/gex`	Série diária: uma linha por dia (o snapshot das 00:00 UTC)
`GET`	`/v1/options/gex/hourly`	Todos os snapshots horários (Pro)
`GET`	`/v1/options/gex/profile`	Fluxo de hedge por preço para um snapshot (padrão: o mais recente)
`GET`	`/v1/options/gex/heatmap`	Matriz tempo × preço do impacto para um mapa de calor

URL base: https://api.blocklens.co. Todas as respostas são JSON no envelope {"success": true, "data": …}: nas séries, data é uma lista de linhas (acompanhada de count, access e message); em /profile e /heatmap, é um objeto que contém access. Os erros usam {"success": false, "message": {…}, "timestamp": "…"} (veja Erros).

Autenticação

Todas as requisições exigem uma chave de API:

Authorization: Bearer YOUR_API_KEY

Consulte Autenticação para chaves de API e Limites de requisições e planos para saber quais planos incluem acesso à API e quais são os limites de requisições.

Sinais e unidades

Todos os valores estão em USD. Os valores de GEX (net_gex, gex[], strikes[].call_gex / put_gex) são USD por movimento de 1%; o fluxo de hedge e o impacto são USD para todo o movimento do preço atual até o nível.
hedge_flow > 0 — os dealers compram BTC no caminho até o nível; < 0 — eles vendem.
impact = hedge_flow × sinal(nível − spot): > 0 — amplifica (o fluxo empurra o movimento adiante), < 0 — amortece (ele segura o movimento).
net_gex > 0 — os dealers estão comprados em gama em termos líquidos (regime de amortecimento); < 0 — vendidos em gama em termos líquidos (regime de amplificação).
spot é o preço do índice do BTC no snapshot; os níveis ficam em uma grade absoluta de $500 dentro de ±30% desse preço.
zero_gamma é buscado dentro de ±50% de spot, então pode ficar fora da grade de níveis; null quando a curva de GEX mantém um único sinal nesse intervalo.

Planos e histórico

As regras de plano são aplicadas pela própria API, não apenas pela interface do Lab:

	Free	Pro, Enterprise
`/v1/options/gex` (diário)	os últimos 30 dias	histórico completo desde 2026-03-16
`/v1/options/gex/hourly`	— (403)	sim
`/v1/options/gex/profile`	apenas o snapshot mais recente, sem `strikes`	qualquer snapshot, com `strikes`
`/v1/options/gex/heatmap`	`resolution=1d`, os últimos 30 dias	`1h`, `6h`, `1d`, histórico completo

Toda resposta contém um bloco 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 — o primeiro dia que o solicitante pode ver (null para o histórico completo).
resolutions, profile_history, strikes, hourly — o que o plano do solicitante permite.
clipped — true quando a série diária ou o mapa de calor foi solicitado para dias anteriores a history_from e eles foram cortados. Esses dois endpoints nunca retornam 403 por esse motivo: retornam a parte permitida.
Um snapshot passado de /profile (qualquer um, exceto o mais recente), /hourly e um mapa de calor 6h / 1h retornam 403 no Free (veja Erros).

Snapshots e horário

Um snapshot do quadro de opções de BTC da Deribit por hora, alguns segundos após a hora cheia. O histórico começa em 2026-03-16; 2026-06-08 … 2026-07-07 está ausente (interrupção na coleta), e horas isoladas são descartadas quando o quadro estava incompleto. Os dados são atualizados a cada hora, por volta de hh:20 UTC.
Os horários estão em UTC, no formato ISO 8601. Os horários dos snapshots trazem microssegundos quando o snapshot os tem ("2026-10-24T09:00:02.418731Z"): passe um valor de ts / times[] sem alterações para /profile?ts= e ele seleciona exatamente aquele snapshot. Um ts sem frações de segundo corresponde a qualquer snapshot dentro daquele segundo.
Um dia (a série diária, /profile?date=, o mapa de calor 1d) é o snapshot das 00:00 UTC daquele dia — o primeiro snapshot do dia, se o das 00:00 estiver ausente. Ele fica longe do vencimento diário das 08:00 UTC, então a linha de um dia não muda depois de publicada.

GET /v1/options/gex

Série diária, da mais recente para a mais antiga.

Parâmetro	Padrão	Descrição
`from_date`	primeiro dia permitido	`YYYY-MM-DD` (UTC); anterior à janela do plano → cortado, `access.clipped = true`
`to_date`	dia mais recente	`YYYY-MM-DD` (UTC, inclusive)
`limit`	`100`	Número de dias (1–10.000), do mais recente para o mais antigo
`fields`	todos	Nomes de campos separados por vírgula (`date` é sempre mantido)

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`	Dia em UTC
`hedge_snapshot_ts`, `spot`	O snapshot do dia usado para os campos de fluxo de hedge e seu preço do índice do BTC
`net_gex`	GEX líquido dos dealers em `spot`, Black-Scholes, USD por movimento de 1% — o GEX líquido publicado
`zero_gamma`	A mudança de sinal da curva de GEX recalculada mais próxima de `spot` (±50%); `null` se não houver
`flow_up5`, `flow_dn5`, `flow_up10`, `flow_dn10`	Fluxo de hedge em USD se o preço se movesse +5% / −5% / +10% / −10% a partir de `spot`, exato em `spot` × 1,05 / 0,95 / 1,10 / 0,90
`snapshot_ts`, `btc_price`	O snapshot dos campos legados e seu preço do BTC
`top_support_strike`, `top_support_gex`	O strike com o maior GEX positivo (gama da Deribit; strikes com \|GEX\| inferior a $1.000 ficam de fora)
`top_resist_strike`, `top_resist_gex`	O strike com o GEX mais negativo (mesmas regras)
`pc_ratio_oi`, `pc_ratio_vol_24h`	Razão put/call por interesse em aberto e por volume de 24h
`max_pain`, `max_pain_expiry`	Strike de max pain do vencimento mais próximo, e esse vencimento
`legacy_total_gex`, `legacy_call_gex`, `legacy_put_gex`	GEX sobre a gama publicada pela Deribit (arredondada para 1e-5 — enviesada em relação a Black-Scholes); use `net_gex`
`legacy_flip_point`	Mudança de sinal do GEX por strike entre os dois strikes em torno do preço — não é um gamma flip; use `zero_gamma`

As colunas diárias net_gex, zero_gamma, flow_* e top_*_strike também são métricas do catálogo (options_*, categoria options), disponíveis via /v1/metrics e pela ferramenta MCP get_metric.

GET /v1/options/gex/hourly

Todos os snapshots horários, do mais recente para o mais antigo (Pro). Mesmos campos da série diária, indexados por timestamp (o horário do snapshot) em vez de date; os valores legados e os de fluxo de hedge do mesmo snapshot ficam na mesma linha.

Parâmetro	Padrão	Descrição
`from_date`, `to_date`	—	`YYYY-MM-DD` (UTC, `to_date` inclusive)
`limit`	`168`	Número de snapshots (1–10.000); o padrão é uma semana
`fields`	todos	Nomes de campos separados por vírgula (`timestamp` é sempre mantido)

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

Fluxo de hedge por preço para um snapshot.

Parâmetro	Padrão	Descrição
`ts`	mais recente	Horário do snapshot (ISO 8601, UTC se não houver offset): o snapshot mais recente nesse horário ou antes dele. Não combina com `date`
`date`	—	`YYYY-MM-DD` (UTC): o snapshot das 00:00 UTC daquele dia (o primeiro do dia). Não combina com `ts`

No Free, apenas o snapshot mais recente está disponível: omita ts / date (um ts / date que corresponda ao snapshot mais recente também é aceito).

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

O exemplo está abreviado: um perfil real tem cerca de cem níveis.

Campo	Significado
`ts`, `spot`	Horário do snapshot e preço do índice do BTC
`step`, `levels`	Passo da grade ($500) e os níveis de preço, em ordem crescente, dentro de ±30% de `spot`
`hedge_flow[i]`	USD que os dealers negociam se o preço for de `spot` até `levels[i]` (> 0 compra, < 0 venda)
`impact[i]`	`hedge_flow[i]` com o sinal da direção do movimento (> 0 amplifica, < 0 amortece)
`gex[i]`	GEX líquido dos dealers recalculado como se o preço estivesse em `levels[i]`, USD por 1%
`net_gex`	GEX em `spot`
`zero_gamma`, `flips`	A mudança de sinal da curva de GEX mais próxima de `spot` e todas as mudanças de sinal, em ordem crescente, dentro de ±50% de `spot` (`null` / `[]` se não houver)
`flow`	Fluxo de hedge exatamente em `spot` × 1,05 / 0,95 / 1,10 / 0,90 (`up5`, `dn5`, `up10`, `dn10`)
`max_amplify_level`, `max_dampen_level`	A faixa de $500 com o maior fluxo marginal de amplificação / amortecimento (`null` se não houver)
`method_version`	Versão do método de cálculo
`legacy`	Valores legados do mesmo snapshot (gama da Deribit): `flip_point`, `top_support_strike`, `top_resist_strike`, `total_gex`
`strikes`	GEX líquido por strike, calls e puts em separado, somado entre os vencimentos (Pro; `null` no Free)

hedge_flow é cumulativo ao longo do caminho do preço: para ler uma faixa entre dois níveis, use a diferença, nunca a soma de vários níveis.

GET /v1/options/gex/heatmap

Parâmetro	Padrão	Descrição
`resolution`	`1d`	`1d`, `6h` ou `1h` (Pro): um snapshot por bucket — o primeiro (`1d` = o snapshot das 00:00 UTC)
`from`	`1d`: todo o histórico; `6h`: os últimos 180 dias; `1h`: os últimos 30 dias	Data ou data e hora ISO (UTC). Anterior à janela do plano → cortado, `access.clipped = true`
`to`	agora	Data ISO (inclusive) ou data e hora (exclusive)
`price_min`, `price_max`	todos os níveis	Limitam o intervalo de preço, em USD (finitos, ≥ 0, `price_min` < `price_max`)

from / to são arredondados para fora, até buckets inteiros 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] — o impacto em USD inteiros em levels[l] para o snapshot times[t] (> 0 amplifica, < 0 amortece). null fora do próprio intervalo de ±30% daquele snapshot ou em um buraco da sua grade.
times são os horários reais dos snapshots, em ordem crescente; o espaçamento é irregular em torno das lacunas de dados (sem linhas vazias).
levels — uma grade comum de $500 que cobre todos os snapshots retornados.
overlays.price — o spot de cada linha; overlays.zero_gamma — seu nível de gama zero (null onde não houver). O nível de gama zero pode ficar fora de levels: corte a linha ao desenhá-la.
scale — o percentil 98 e o máximo de |impacto|; limite a escala de cores a p98.

Limites e tamanho da resposta

resolution=1h cobre no máximo 90 dias por requisição (caso contrário, 400 — use 6h ou 1d para intervalos mais longos).
Uma requisição de mapa de calor pode cobrir no máximo 2.000.000 células (snapshots × níveis); requisições maiores retornam 400 — use uma resolução menos detalhada, um período mais curto ou price_min / price_max.
O histórico horário completo tem cerca de 10 MB de JSON sem compressão. As respostas são transmitidas com compressão gzip. Para uma primeira visualização, use 1d ou 6h, ou uma janela curta de 1h.
Limites de requisições por chave de API: Limites de requisições e planos.

Atualizações e cache

Um novo snapshot é calculado a cada hora do nosso lado e publicado por volta de hh:20 UTC; até lá, a hora anterior é a mais recente.
As respostas ficam em cache no servidor e são atualizadas quando chegam novos dados.
A mesma URL retorna dados diferentes para planos diferentes, por isso as respostas são enviadas com Cache-Control: private, max-age=600 e Vary: Authorization — elas nunca são armazenadas por caches compartilhados.

Erros

Os erros vêm no envelope {"success": false, "message": {…}, "timestamp": "…"}; a tabela mostra message.

Status	Quando	`message`
400	Data ou horário inválido, `to_date` anterior a `from_date`, `ts` e `date` ao mesmo tempo, `resolution` desconhecida, `price_min` / `price_max` não finito, negativo ou `price_min >= price_max`, um intervalo que não se sobrepõe aos níveis, mais de 90 dias em `1h`, mapa de calor acima de 2.000.000 células	`{"error": "Invalid parameter", "message": "resolution must be one of 1h, 6h, 1d"}`
401	Chave de API ausente ou inválida
403	Free: um snapshot passado de `/profile`, `/hourly`, um 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	Nenhum snapshot para o dia ou horário solicitado, ou nenhum dado no intervalo solicitado	`{"error": "Not found", "message": "no profile on 2026-06-20"}`
429	Limite de requisições excedido	Veja Limites de requisições e planos

Endpoints​

Autenticação​

Sinais e unidades​

Planos e histórico​

Snapshots e horário​

GET /v1/options/gex​

GET /v1/options/gex/hourly​

GET /v1/options/gex/profile​

GET /v1/options/gex/heatmap​

Limites e tamanho da resposta​

Atualizações e cache​

Erros​