Dealer Hedge Flow API

Dealer Hedge Flow API는 Deribit BTC 옵션에서 옵션 딜러가 어떻게 포지셔닝되어 있는지, 그리고 가격이 움직이면 그들의 헤지가 어떤 작용을 하는지를 반환합니다. 각 가격 수준에 대해 딜러가 그 수준까지 가는 동안 델타 헤지를 유지하려면 BTC를 몇 달러어치 매수하거나 매도해야 하는지, 그리고 그 플로우가 움직임을 증폭하는지 억제하는지를 알려 줍니다. 순 감마 익스포저(GEX), 제로 감마 수준과 몇 가지 레거시 옵션 통계도 함께 반환합니다. 새 스냅샷은 매시간 계산됩니다.

딜러 포지션을 재구성하는 방식, 수식과 가정은 Dealer Hedge Flow 방법론을 참고하십시오.

트레이딩 신호가 아닙니다

Dealer Hedge Flow는 딜러 포지셔닝의 서술적(descriptive) 모델이며, 목표 가격이나 트레이딩 신호가 아닙니다.

엔드포인트

메서드	경로	설명
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. 모든 응답은 {"success": true, "data": …} 형태의 JSON입니다. 시리즈의 경우 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(level − spot): > 0 — 증폭(플로우가 움직임을 더 밀어붙임), < 0 — 억제 (움직임을 거스름).
• net_gex > 0 — 딜러는 순 롱 감마(억제 국면)입니다. < 0 — 순 숏 감마(증폭 국면)입니다.
• spot은 스냅샷의 BTC 인덱스 가격이며, 수준은 그 ±30% 범위 안의 절대 $500 그리드에 놓입니다.
• zero_gamma는 spot의 ±50% 범위에서 탐색하므로 수준 그리드 밖에 있을 수 있습니다. 해당 범위에서 GEX 곡선의 부호가 바뀌지 않으면 null입니다.

등급과 이력

등급 규칙은 Lab 화면뿐 아니라 API 자체에서도 적용됩니다.

	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을 반환하지 않고, 허용된 부분만 반환합니다.
• /profile의 과거 스냅샷(최신이 아닌 모든 스냅샷), /hourly, 6h / 1h 히트맵은 Free에서 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 감마; |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가 공개하는 감마 기준 GEX(1e-5로 반올림 — Black-Scholes 대비 편향됨); net_gex를 사용하십시오
legacy_flip_point	가격을 둘러싼 두 행사가 사이에서 행사가별 GEX의 부호가 바뀌는 지점 — 감마 플립이 아님; zero_gamma를 사용하십시오

일별 net_gex, zero_gamma, flow_*, top_*_strike 열은 카탈로그 메트릭(options_*, 카테고리 options)으로도 제공되며, /v1/metrics와 MCP 도구 get_metric으로 조회할 수 있습니다.

GET /v1/options/gex/hourly

모든 시간별 스냅샷, 최신순(Pro). 필드는 일별 시리즈와 같지만 date 대신 timestamp(스냅샷 시각)를 키로 사용하며, 같은 스냅샷의 레거시 값과 헤지 플로우 값이 한 행에 함께 들어 있습니다.

매개변수	기본값	설명
from_date, to_date	—	YYYY-MM-DD (UTC, to_date는 해당 일자 포함)
limit	168	스냅샷 수(1–10,000); 기본값은 1주
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}
  }
}

예시는 축약된 것입니다. 실제 프로파일에는 약 100개의 수준이 있습니다.

필드	의미
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% 범위에서 spot에 가장 가까운 GEX 곡선의 부호 전환점과 모든 부호 전환점, 오름차순(없으면 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 감마): 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 — 그 행의 제로 감마 수준(없으면 null). 제로 감마 수준은 levels 밖에 있을 수 있으므로, 선을 그릴 때는 잘라 내십시오.
• scale — |impact|의 98번째 백분위수와 최댓값. 색상 스케일의 상한은 p98로 두십시오.

제한 및 페이로드 크기

• resolution=1h는 요청당 최대 90일까지 다룹니다(초과 시 400 — 더 긴 기간에는 6h 또는 1d를 사용하십시오).
• 히트맵 요청 한 번에 최대 2,000,000개 셀(스냅샷 × 수준)까지 받을 수 있으며, 이를 초과하면 400을 반환합니다. 더 거친 해상도나 더 짧은 기간, 또는 price_min / price_max를 사용하십시오.
• 시간별 전체 이력은 압축되지 않은 JSON 기준 약 10 MB입니다. 응답은 전송 시 gzip으로 압축됩니다. 첫 화면에서는 1d나 6h, 또는 짧은 1h 구간을 사용하십시오.
• API 키별 요청 한도: 속도 제한 및 등급.

업데이트 및 캐싱

• 새 스냅샷은 당사 측에서 매시간 계산되어 약 :20 UTC에 게시됩니다. 그 전까지는 이전 시간의 스냅샷이 최신으로 반환됩니다.
• 응답은 서버에 캐시되며 새 데이터가 들어오면 갱신됩니다.
• 동일한 URL이라도 등급에 따라 다른 데이터를 반환하므로, 응답은 Cache-Control: private, max-age=600 및 Vary: Authorization과 함께 전송되며 공유 캐시에는 저장되지 않습니다.

오류

오류는 {"success": false, "message": {…}, "timestamp": "…"} 형태로 반환되며, 아래 표에는 message가 표시되어 있습니다.

상태	발생 조건	message
400	잘못된 날짜 또는 시각, from_date보다 이전인 to_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	속도 제한 초과	속도 제한 및 등급 참고