Dealer Hedge Flow API

Dealer Hedge Flow API نشان می‌دهد دیلرهای آپشن در آپشن‌های BTC در Deribit چه پوزیشنی دارند و اگر قیمت حرکت کند، هج آن‌ها چه خواهد کرد: برای هر سطح قیمت، دیلرها در مسیر رسیدن به آن سطح برای دلتا-هج ماندن چند دلار آمریکا BTC می‌خرند یا می‌فروشند، و آیا این جریان حرکت را تشدید می‌کند یا مهار. API همچنین گاما اکسپوژر خالص (GEX)، سطح گامای صفر و چند آمار قدیمی (legacy) آپشن‌ها را برمی‌گرداند. هر ساعت یک اسنپ‌شات جدید محاسبه می‌شود.

پوزیشن دیلرها چگونه بازسازی می‌شود، فرمول‌ها و فرض‌ها: روش‌شناسی Dealer Hedge Flow.

سیگنال معاملاتی نیست

Dealer Hedge Flow مدلی توصیفی از پوزیشن‌گیری دیلرهاست، نه هدف قیمتی یا سیگنال معاملاتی.

اندپوینت‌ها

متد	مسیر	توضیح
`GET`	`/v1/options/gex`	سری روزانه: یک ردیف برای هر روز (اسنپ‌شات 00:00 UTC)
`GET`	`/v1/options/gex/hourly`	همه اسنپ‌شات‌های ساعتی (Pro)
`GET`	`/v1/options/gex/profile`	جریان هج بر حسب قیمت برای یک اسنپ‌شات (پیش‌فرض: آخرین)
`GET`	`/v1/options/gex/heatmap`	ماتریس زمان × قیمت از اثر برای نقشه حرارتی

آدرس پایه: https://api.blocklens.co. همه پاسخ‌ها JSON در پوشش {"success": true, "data": …} هستند: در سری‌ها 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) بر حسب USD به ازای هر حرکت 1% هستند؛ جریان هج و اثر، مبلغ USD برای کل حرکت از قیمت فعلی تا آن سطح هستند.
hedge_flow > 0 — دیلرها در مسیر رسیدن به آن سطح BTC می‌خرند؛ < 0 — می‌فروشند.
impact = hedge_flow × sign(level − spot): > 0 — تشدید (جریان حرکت را جلوتر می‌برد)، < 0 — مهار (در برابر حرکت می‌ایستد).
net_gex > 0 — دیلرها در مجموع لانگ گاما هستند (رژیم مهار)؛ < 0 — در مجموع شورت گاما (رژیم تشدید).
spot قیمت شاخص BTC در اسنپ‌شات است؛ سطوح روی یک شبکه مطلق $500 در محدوده ±30% آن قرار دارند.
zero_gamma در محدوده ±50% از spot جست‌وجو می‌شود، بنابراین ممکن است بیرون از شبکه سطوح باشد؛ اگر منحنی GEX در این محدوده علامت خود را حفظ کند، null است.

سطوح اشتراک و تاریخچه

قواعد سطوح اشتراک در خود API اعمال می‌شوند، نه فقط در رابط Lab:

	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 برمی‌گردانند (نگاه کنید به خطاها).

اسنپ‌شات‌ها و زمان

هر ساعت یک اسنپ‌شات از تابلوی آپشن‌های BTC در Deribit، چند ثانیه پس از ساعت کامل. تاریخچه از 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`	GEX خالص دیلرها در `spot`، با Black-Scholes، بر حسب USD به ازای هر حرکت 1% — همان GEX خالص منتشرشده
`zero_gamma`	نزدیک‌ترین تغییر علامت منحنی GEX بازمحاسبه‌شده به `spot` (±50%)؛ اگر وجود نداشته باشد، `null`
`flow_up5`، `flow_dn5`، `flow_up10`، `flow_dn10`	جریان هج بر حسب USD اگر قیمت از `spot` به میزان +5% / −5% / +10% / −10% حرکت کند، دقیقاً در `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`	استرایک max pain نزدیک‌ترین سررسید، و خود آن سررسید
`legacy_total_gex`، `legacy_call_gex`، `legacy_put_gex`	GEX بر پایه گامای منتشرشده Deribit (گردشده تا 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). همان فیلدهای سری روزانه، با کلید timestamp (زمان اسنپ‌شات) به جای date؛ مقادیر قدیمی و مقادیر جریان هج یک اسنپ‌شات در یک ردیف می‌آیند.

پارامتر	پیش‌فرض	توضیح
`from_date`، `to_date`	—	`YYYY-MM-DD` (UTC، `to_date` شامل خود روز)
`limit`	`168`	تعداد اسنپ‌شات‌ها (1–10,000)؛ پیش‌فرض یک هفته است
`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، اگر offset نداشته باشد 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}
  }
}

این مثال کوتاه شده است: یک پروفایل واقعی حدود صد سطح دارد.

فیلد	معنا
`ts`، `spot`	زمان اسنپ‌شات و قیمت شاخص BTC
`step`، `levels`	گام شبکه ($500) و سطوح قیمت، به ترتیب صعودی، در محدوده ±30% از `spot`
`hedge_flow[i]`	مبلغ USD که دیلرها معامله می‌کنند اگر قیمت از `spot` به `levels[i]` برود (> 0 خرید، < 0 فروش)
`impact[i]`	`hedge_flow[i]` که علامت آن بر اساس جهت حرکت تعیین شده است (> 0 تشدید، < 0 مهار)
`gex[i]`	GEX خالص دیلرها که گویی قیمت در `levels[i]` است بازمحاسبه شده، بر حسب USD به ازای هر 1%
`net_gex`	GEX در `spot`
`zero_gamma`، `flips`	نزدیک‌ترین تغییر علامت منحنی GEX به `spot` و همه تغییر علامت‌ها، به ترتیب صعودی، در محدوده ±50% از `spot` (اگر وجود نداشته باشد `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] — اثر بر حسب USD (عدد صحیح) در levels[l] برای اسنپ‌شات times[t] (> 0 تشدید، < 0 مهار). بیرون از محدوده ±30% خود آن اسنپ‌شات یا در حفره‌ای از شبکه آن، null است.
times زمان‌های واقعی اسنپ‌شات‌ها هستند، به ترتیب صعودی؛ فاصله آن‌ها در اطراف شکاف‌های داده نامنظم است (ردیف خالی نداریم).
levels — یک شبکه مشترک $500 که همه اسنپ‌شات‌های برگردانده‌شده را پوشش می‌دهد.
overlays.price — spot هر ردیف؛ overlays.zero_gamma — سطح گامای صفر آن (جایی که وجود ندارد null). سطح گامای صفر ممکن است بیرون از levels باشد: هنگام رسم، خط آن را در لبه ببرید.
scale — صدک 98 و بیشینه |impact|؛ سقف مقیاس رنگ را روی p98 بگذارید.

محدودیت‌ها و حجم پاسخ

resolution=1h در هر درخواست حداکثر 90 روز را پوشش می‌دهد (در غیر این صورت 400 — برای بازه‌های طولانی‌تر از 6h یا 1d استفاده کنید).
هر درخواست نقشه حرارتی حداکثر 2,000,000 سلول (اسنپ‌شات‌ها × سطوح) را پوشش می‌دهد؛ درخواست‌های بزرگ‌تر خطای 400 می‌گیرند — از رزولوشن درشت‌تر، دوره کوتاه‌تر یا price_min / price_max استفاده کنید.
تاریخچه کامل ساعتی حدود 10 MB JSON بدون فشرده‌سازی است. پاسخ‌ها در انتقال با gzip فشرده می‌شوند. برای نمای اولیه از 1d یا 6h، یا یک پنجره کوتاه 1h استفاده کنید.
محدودیت‌های درخواست برای هر کلید API: محدودیت‌های نرخ و سطوح اشتراک.

به‌روزرسانی‌ها و کش

هر ساعت یک اسنپ‌شات جدید در سمت ما محاسبه می‌شود و حدود دقیقه 20 هر ساعت (UTC) منتشر می‌شود؛ تا آن موقع، ساعت قبل آخرین اسنپ‌شات است.
پاسخ‌ها روی سرور کش می‌شوند و با رسیدن داده‌های جدید تازه‌سازی می‌شوند.
یک URL واحد برای سطوح اشتراک مختلف، داده‌های متفاوتی برمی‌گرداند؛ به همین دلیل پاسخ‌ها با Cache-Control: private, max-age=600 و Vary: Authorization ارسال می‌شوند و هیچ‌وقت در کش‌های مشترک ذخیره نمی‌شوند.

خطاها

خطاها در پوشش {"success": false, "message": {…}, "timestamp": "…"} می‌آیند؛ جدول مقدار message را نشان می‌دهد.

وضعیت	چه زمانی	`message`
400	تاریخ یا زمان نامعتبر، `to_date` پیش از `from_date`، ارسال هم‌زمان `ts` و `date`، `resolution` ناشناخته، `price_min` / `price_max` نامتناهی یا منفی، یا `price_min >= price_max`، بازه‌ای که با سطوح هم‌پوشانی ندارد، بیش از 90 روز در `1h`، نقشه حرارتی بیش از 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	محدودیت نرخ رد شده است	نگاه کنید به محدودیت‌های نرخ و سطوح اشتراک

اندپوینت‌ها​

احراز هویت​

علامت‌ها و واحدها​

سطوح اشتراک و تاریخچه​

اسنپ‌شات‌ها و زمان​

GET /v1/options/gex​

GET /v1/options/gex/hourly​

GET /v1/options/gex/profile​

GET /v1/options/gex/heatmap​

محدودیت‌ها و حجم پاسخ​

به‌روزرسانی‌ها و کش​

خطاها​