Snapshot API

‏Snapshot API نمودارهای تحلیلی on-chain را به‌صورت تصاویر PNG یا گرافیک برداری SVG رندر می‌کند. شناسه‌های متریک و پارامترهای نمایشی اختیاری را ارسال کنید و یک تصویر نمودار کاملاً رندرشده دریافت کنید که آماده درج در گزارش‌ها، داشبوردها یا گفتگوهای هوش مصنوعی است. در حال حاضر از متریک‌های بیت‌کوین پشتیبانی می‌کند و پوشش چندزنجیره‌ای (ETH، TON، TRON) در حال گسترش است.

نقاط پایانی (Endpoints)

متد	مسیر	توضیحات
`GET`	`/v1/chart/snapshot`	نمودارهای ساده از طریق پارامترهای کوئری
`POST`	`/v1/chart/snapshot`	سفارشی‌سازی کامل از طریق بدنه JSON

هر دو نقطه پایانی به‌صورت پیش‌فرض image/png بازمی‌گردانند. با تنظیم هدر درخواست Accept — یا در POST، فیلد بدنه format ("png"، "svg"، "json") — می‌توانید به SVG (image/svg+xml) یا فراداده JSON (application/json) سوئیچ کنید.

پاسخ‌های موفق PNG و SVG شامل یک هدر X-Render-Id هستند تا نمودار رندرشده بتواند ظرف ۱ ساعت از طریق URL دوباره واکشی شود:

خروجی	کش‌شده در
PNG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.png`
SVG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.svg`

احراز هویت

همه درخواست‌ها به یک کلید API از طریق هدر Authorization نیاز دارند:

Authorization: Bearer YOUR_API_KEY

برای جزئیات مربوط به دریافت کلیدهای API به احراز هویت مراجعه کنید.

دسترسی و محدودیت‌های نرخ

‏Snapshot API به سطح Pro یا Enterprise نیاز دارد. کلیدهای سطح Demo و Free پاسخ 403 Forbidden دریافت می‌کنند.

‏Snapshot API از همان محدودیت‌های نرخ Data API پیروی می‌کند. برای جزئیات به محدودیت‌های نرخ مراجعه کنید.

هنگام محدود شدن نرخ، API پاسخ 429 Too Many Requests به همراه یک فیلد retry_after بازمی‌گرداند.

دسترسی به متریک نیز بر اساس درجه (grade) محدود می‌شود: متریک‌های درجه ۰ (price، supply، MVRV) برای همه کلیدهای Pro+ در دسترس‌اند، متریک‌های درجه ۱ (SOPR، P&L) به Pro نیاز دارند و متریک‌های درجه ۲ (نقشه‌های حرارتی CBD) به Enterprise نیاز دارند.

‏GET `/v1/chart/snapshot`

نموداری از پارامترهای کوئری تولید می‌کند. بهترین گزینه برای نمودارهای ساده، تک‌متریکی یا مبتنی بر قالب.

پارامترها

پارامتر	نوع	پیش‌فرض	توضیحات
`metric`	string	-	شناسه یک متریک (مثلاً `price`، `lth_supply`). متقابلاً انحصاری با `metrics` و `template`.
`metrics`	string	-	شناسه‌های متریک جداشده با کاما، حداکثر ۶ (مثلاً `lth_supply,sth_supply`). متقابلاً انحصاری با `metric` و `template`.
`template`	string	-	شناسه قالب از پیش‌تعریف‌شده. متقابلاً انحصاری با `metric` و `metrics`.
`days`	integer	365	روزهای داده تاریخی (۷ تا ۱۰۰۰۰).
`start_date`	string	-	تاریخ شروع (`YYYY-MM-DD`). بر `days` اولویت دارد.
`end_date`	string	-	تاریخ پایان (`YYYY-MM-DD`). پیش‌فرض امروز.
`style`	string	auto	سبک نمودار: `line`، `area`، `bar`. در صورت حذف، به‌طور خودکار از رجیستری متریک تشخیص داده می‌شود.
`scale`	string	`linear`	مقیاس محور Y: `linear` یا `log`.
`overlay`	string	-	افزودن روی‌هم‌اندازی قیمت به‌صورت یک خط‌چین ملایم روی محور راست (از `price` استفاده کنید). در حال حاضر قیمت BTC.
`width`	integer	1200	عرض تصویر به پیکسل (۶۰۰ تا ۲۴۰۰).
`height`	integer	600	ارتفاع تصویر به پیکسل (۳۰۰ تا ۱۲۰۰).
`title`	string	auto	عنوان نمودار. در صورت حذف، به‌طور خودکار از نام متریک‌ها تولید می‌شود.
`theme`	string	`light`	تم رنگ: `light` یا `dark`.

دقیقاً یکی از metric، metrics یا template باید ارائه شود.

قالب‌های در دسترس

قالب	متریک‌ها
`price`	قیمت BTC
`price_volume`	قیمت + حجم
`market_cap`	ارزش بازار
`holder_supply`	عرضه LTH + عرضه STH
`mvrv_ratio`	‏MVRV نوع LTH + MVRV نوع STH
`realized_price`	قیمت تحقق‌یافته LTH + قیمت تحقق‌یافته STH
`realized_cap`	ارزش تحقق‌یافته LTH + ارزش تحقق‌یافته STH
`unrealized_pl`	سود/زیان تحقق‌نیافته LTH + سود/زیان تحقق‌نیافته STH
`realized_pl`	سود/زیان تحقق‌یافته LTH + سود/زیان تحقق‌یافته STH
`sopr`	‏SOPR نوع LTH + SOPR نوع STH
`block_height`	ارتفاع بلاک

نمونه‌ها

# Bitcoin example: BTC price, 1 year, line chart
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" \
  --output price.png

# Bitcoin example: two metrics with area style
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?metrics=lth_supply,sth_supply&style=area&days=730" \
  --output supply.png

# Template with dark theme
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?template=mvrv_ratio&theme=dark" \
  --output mvrv_dark.png

# Log scale with price overlay
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=lth_supply&scale=log&overlay=price&days=1095" \
  --output supply_with_price.png

# Get JSON metadata instead of image
curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" | jq

# Get SVG instead of PNG
curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: image/svg+xml" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" \
  --output price.svg

پاسخ موفق

‏PNG (پیش‌فرض):

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=3600
X-Snapshot-Cache: HIT
X-Snapshot-Render-Ms: 0
X-Render-Id: 0a1b2c3d4e5f6789

<binary PNG data>

‏SVG (با Accept: image/svg+xml):

HTTP/1.1 200 OK
Content-Type: image/svg+xml
Cache-Control: public, max-age=3600
X-Snapshot-Cache: MISS
X-Snapshot-Render-Ms: 412
X-Render-Id: 0a1b2c3d4e5f6789
Content-Disposition: attachment; filename="chart.svg"

<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>

مقدار X-Render-Id می‌تواند برای واکشی مجدد همان تصویر در /v1/chart/renders/{render_id}.png یا /v1/chart/renders/{render_id}.svg تا ۱ ساعت استفاده شود.

‏POST `/v1/chart/snapshot`

سفارشی‌سازی کامل نمودار از طریق بدنه JSON. از سبک‌دهی به‌ازای هر متریک، محورهای سفارشی، فرمول‌ها، خطوط مرجع، نواحی مرجع و موارد دیگر پشتیبانی می‌کند. طراحی‌شده برای عامل‌های هوش مصنوعی (از طریق MCP) و کاربران پیشرفته.

بدنه درخواست

دقیقاً یک منبع داده ارائه کنید (metric، metrics یا template):

{
  "metric": "price",

  "days": 365,
  "start_date": "2025-01-01",
  "end_date": "2026-02-23",

  "title": "Custom Chart Title",
  "width": 1200,
  "height": 600,
  "theme": "light",
  "format": "png",

  "style": "line",
  "scale": "linear",
  "overlay": "price",

  "y_axes": [
    {"id": "axis-left", "side": "left", "scale": "linear", "format": "number"},
    {"id": "axis-right", "side": "right", "scale": "log", "format": "currency"}
  ],

  "formulas": [
    {"expression": "sma(m1, 200)", "label": "200-day SMA", "color": "#9333ea", "style": "line"}
  ],

  "reference_lines": [
    {"y": 1.0, "stroke": "#9ca3af", "stroke_dasharray": "3 3", "label": "Break-even"}
  ],
  "reference_areas": [
    {"y1": 0, "y2": 0.85, "fill": "#16a34a", "fill_opacity": 0.08, "label": "Undervalued"}
  ]
}

توجه: دقیقاً یکی از metric، metrics یا template باید ارائه شود.

فیلد metrics

فیلد metrics از انواع ترکیبی پشتیبانی می‌کند:

// String shorthand
["price", "lth_supply"]

// Full config objects
[{"id": "price", "axis": "right", "style": "line", "color": "#374151"}]

// Mixed
["price", {"id": "lth_supply", "axis": "left", "style": "area"}]

// With params for parameterized metrics
[
  {"id": "funding_binance", "params": {"exchange": "binance"}},
  {"id": "price"}
]

برخی متریک‌ها به پارامترهای اضافی نیاز دارند (مثلاً exchange، ticker، id). هنگام استفاده از این متریک‌ها، شیء params را از تعریف متریک قید کنید.

گزینه‌های به‌ازای هر متریک

فیلد	نوع	توضیحات
`id`	string	الزامی. شناسه متریک از رجیستری.
`params`	object	پارامترهای متریک‌های پارامتری‌شده (مثلاً `{"exchange": "binance"}`). برای پارامترهای الزامی به تعریف متریک مراجعه کنید.
`axis`	`left` / `right`	سمت محور Y. در صورت حذف، به‌طور خودکار تخصیص می‌یابد.
`y_axis_id`	string	اتصال به یک محور Y مشخص بر اساس شناسه (مثلاً `axis-diff`). بر `axis` اولویت دارد.
`style`	`line` / `area` / `bar`	سبک نمودار. در صورت حذف، پیش‌فرض رجیستری.
`color`	string	رنگ هگز (مثلاً `#2563eb`). در صورت حذف، به‌طور خودکار تخصیص می‌یابد.
`label`	string	برچسب نمایشی. در صورت حذف، از نام متریک استفاده می‌شود.
`stroke_width`	integer	عرض خط (۰ تا ۵). پیش‌فرض: ۲. برای میله‌های بدون حاشیه از ۰ استفاده کنید.
`fill_opacity`	float	شفافیت پُرشدگی (۰.۰ تا ۱.۰). برای میله‌های شفاف، مقادیر کم مانند ۰.۲ به کار ببرید.
`stroke_dash`	string	الگوی خط‌چین (مثلاً `5 5`).
`stack_group`	string	شناسه گروه پشته‌ای برای نمودارهای پشته‌ای.
`show_in_legend`	boolean	اینکه آیا در راهنمای نمودار نمایش داده شود. پیش‌فرض: true.
`visible`	boolean	نمایش/پنهان‌سازی. پیش‌فرض: true.

محورهای Y سفارشی

فیلد y_axes محورهای Y در دسترس برای متریک‌ها و فرمول‌ها را تعریف می‌کند. هر محور یک id یکتا دارد که می‌تواند از طریق y_axis_id روی متریک‌ها یا فرمول‌ها ارجاع داده شود. می‌توانید بیش از دو محور تعریف کنید — برای مثال، یک محور جداگانه برای تفاوت‌های محاسبه‌شده:

"y_axes": [
  {"id": "axis-left", "side": "left", "scale": "linear", "format": "number"},
  {"id": "axis-right", "side": "right", "scale": "log", "format": "currency"},
  {"id": "axis-diff", "side": "left", "scale": "linear", "format": "number"}
]

فیلد	نوع	توضیحات
`id`	string	شناسه یکتای محور. توسط `y_axis_id` روی متریک‌ها/فرمول‌ها ارجاع داده می‌شود.
`side`	`left` / `right`	اینکه محور در کدام سمت نمودار ظاهر شود.
`scale`	`linear` / `log`	مقیاس محور. پیش‌فرض: `linear`.
`format`	`number` / `currency` / `percent`	قالب عددی برای برچسب‌های محور.
`range`	`[number, number]`	ناحیه عمودی به‌صورت `[from%, to%]`. `0` = پایین، `100` = بالا. پیش‌فرض: ارتفاع کامل. برای پشته‌سازی عمودی محورها استفاده کنید (مثلاً حجم در ۲۰٪ پایین، قیمت در ۸۰٪ بالا).
`domain_min`	number	محدودسازی سخت حداقل دامنه. محور هرگز پایین‌تر از این مقدار نمی‌رود.
`domain_max`	number	محدودسازی سخت حداکثر دامنه. محور هرگز بالاتر از این مقدار نمی‌رود.
`no_padding`	`"top"` / `"bottom"` / `"both"`	حذف فاصله خودکار ۱۰٪ از لبه‌ها. زمانی مفید است که یک محدودسازی دامنه یک مرز سخت باشد (مثلاً افت‌سرمایه محدودشده در ۰).

اگر y_axes حذف شود، محورها به‌طور خودکار بر اساس مقادیر axis متریک‌ها تولید می‌شوند.

مثال: قیمت + حجم با نواحی عمودی

میله‌های حجم را در ۲۰٪ پایین و قیمت را در فضای باقی‌مانده پشته کنید:

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {"id": "price", "style": "line", "color": "#374151", "y_axis_id": "axis-price"},
      {"id": "volume", "style": "bar", "color": "#3b82f6", "fill_opacity": 0.3, "stroke_width": 0, "y_axis_id": "axis-vol"}
    ],
    "y_axes": [
      {"id": "axis-price", "side": "right", "scale": "log", "format": "currency", "range": [20, 100]},
      {"id": "axis-vol", "side": "left", "format": "number", "range": [0, 20], "no_padding": "bottom"}
    ],
    "days": 365,
    "title": "BTC Price + Volume (Zoned)"
  }' --output price_volume_zones.png

این چه چیزی تولید می‌کند:

میله‌های حجم ۲۰٪ پایین نمودار را پُر می‌کنند (range: [0, 20]) بدون فاصله در لبه پایین
قیمت ۸۰٪ بالا را اشغال می‌کند (range: [20, 100]) روی مقیاس لگاریتمی
دو سری هرگز هم‌پوشانی ندارند و یک چیدمان پشته‌ای تمیز ایجاد می‌کنند

مثال: افت‌سرمایه با محدودسازی دامنه

افت‌سرمایه را در ۰ (لبه بالا) محدود کنید تا خط به بالای ناحیه خود برسد:

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["price"],
    "formulas": [
      {"expression": "drawdown(price)", "label": "Drawdown from ATH", "style": "area", "color": "#dc2626", "fill_opacity": 0.15, "y_axis_id": "axis-dd"}
    ],
    "y_axes": [
      {"id": "axis-right", "side": "right", "scale": "log", "format": "currency"},
      {"id": "axis-dd", "side": "left", "format": "percent", "domain_max": 0, "no_padding": "top"}
    ],
    "days": 1825,
    "title": "BTC Price + Drawdown from ATH"
  }' --output drawdown.png

این چه چیزی تولید می‌کند:

افت‌سرمایه همیشه ≤ ۰ است، بنابراین domain_max: 0 لبه بالا را محدود می‌کند
‏no_padding: "top" فاصله خودکار ۱۰٪ بالای ۰ را حذف می‌کند و باعث می‌شود وقتی افت‌سرمایه ۰٪ است خط به بالا برسد
قیمت روی محور راست با مقیاس لگاریتمی قرار دارد

فرمول‌ها

فیلد formulas به شما اجازه می‌دهد سری‌های محاسبه‌شده مشتق‌گرفته از متریک‌هایتان را تعریف کنید. فرمول‌ها می‌توانند متریک‌ها را با id آن‌ها (مثلاً lth_supply) یا با شاخص موقعیتی (m1، m2 و غیره بر اساس ترتیب در آرایه metrics) ارجاع دهند.

"formulas": [
  {
    "expression": "lth_supply - shift(lth_supply, 30)",
    "label": "LTH 30d Change",
    "color": "#16a34a",
    "style": "bar",
    "y_axis_id": "axis-diff",
    "fill_opacity": 0.2,
    "stroke_width": 0
  }
]

توابع پشتیبانی‌شده (در مجموع ۳۰):

میانگین‌های متحرک و آماره‌های غلتان

تابع	نحو	توضیحات
`sma`	`sma(series, period)`	میانگین متحرک ساده
`ema`	`ema(series, period)`	میانگین متحرک نمایی
`median`	`median(series, period)`	میانه غلتان
`sum`	`sum(series, period)`	مجموع غلتان
`std`	`std(series, period)`	انحراف معیار غلتان

تجمعی

تابع	نحو	توضیحات
`cumsum`	`cumsum(series)`	مجموع تجمعی گسترش‌یابنده
`cummean`	`cummean(series)`	میانگین تجمعی گسترش‌یابنده
`cummedian`	`cummedian(series)`	میانه تجمعی گسترش‌یابنده
`cumstd`	`cumstd(series)`	انحراف معیار تجمعی گسترش‌یابنده
`cummax`	`cummax(series)`	بیشینه تجمعی تمام‌دوران
`cummin`	`cummin(series)`	کمینه تجمعی تمام‌دوران

تغییرات

تابع	نحو	توضیحات
`percent_change`	`percent_change(series, period)`	تغییر درصدی (اعشاری: ۰.۲۰ = ‎+۲۰٪)
`diff`	`diff(series, period)`	تغییر مقدار مطلق

ریاضی

تابع	نحو	توضیحات
`abs`	`abs(series)`	مقدار مطلق
`pow`	`pow(series, n)`	به توان n رساندن
`log`	`log(series)`	لگاریتم پایه ۱۰
`round`	`round(series, digits)`	گرد کردن به N رقم اعشار
`max`	`max(a, b, ...)`	بیشینه نقطه‌به‌نقطه
`min`	`min(a, b, ...)`	کمینه نقطه‌به‌نقطه

شاخص‌های تکنیکال

تابع	نحو	توضیحات
`rsi`	`rsi(series, period)`	شاخص قدرت نسبی (۰ تا ۱۰۰)
`corr`	`corr(s1, s2, period)`	همبستگی پیرسون (‎-۱ تا ۱)
`drawdown`	`drawdown(series)`	افت‌سرمایه از ATH (اعشاری منفی)

ریسک و بازده

تابع	نحو	توضیحات
`mean_return`	`mean_return(series, period)`	میانگین بازده غلتان سالانه‌شده
`realized_vol`	`realized_vol(series, period)`	نوسان تحقق‌یافته سالانه‌شده
`sharpe_ratio_arithmetic`	`sharpe_ratio_arithmetic(series, period)`	نسبت شارپ (حسابی)
`sharpe_ratio_geometric`	`sharpe_ratio_geometric(series, period)`	نسبت شارپ (هندسی)

دستکاری سری

تابع	نحو	توضیحات
`shift`	`shift(series, period)`	جابه‌جایی سری به اندازه N دوره
`if`	`if(a, "op", b, then, else)`	شرطی (op: `=`، `!=`، `>`، `>=`، `<`، `<=`)

عملگرها

حسابی: +، -، *، / گروه‌بندی: (، )

ارجاع‌دهی

متریک‌ها با نام: lth_supply + sth_supply — مستقیماً از شناسه‌های متریک استفاده کنید
متریک‌ها با موقعیت: m1 + m2 — ارجاع‌های موقعیتی (m1 = اولین متریک، m2 = دومین و غیره)
سایر فرمول‌ها: f1 * 2 — ارجاع به فرمول‌های قبلی (f1 = اولین فرمول و غیره)
فرمول‌ها به ترتیب ارزیابی می‌شوند، بنابراین f2 می‌تواند به f1 ارجاع دهد، اما برعکس نه.

گزینه‌های فرمول:

فیلد	نوع	توضیحات
`expression`	string	الزامی. عبارت فرمول با استفاده از شناسه‌های متریک یا ارجاع‌های موقعیتی (`m1`، `m2`).
`label`	string	الزامی. برچسب نمایشی برای راهنما.
`color`	string	رنگ هگز. در صورت حذف، به‌طور خودکار تخصیص می‌یابد.
`style`	`line` / `area` / `bar`	سبک نمودار. پیش‌فرض: `line`.
`y_axis_id`	string	اتصال به یک محور Y مشخص بر اساس شناسه (مثلاً `axis-diff`). بر `axis` اولویت دارد.
`axis`	`left` / `right`	سمت محور Y. پیش‌فرض: `left`. در صورت تنظیم `y_axis_id` نادیده گرفته می‌شود.
`fill_opacity`	float	شفافیت پُرشدگی (۰.۰ تا ۱.۰). برای میله‌های شفاف، مقادیر کم مانند ۰.۲ به کار ببرید.
`stroke_width`	integer	عرض خط (۰ تا ۵). برای میله‌های بدون حاشیه از ۰ استفاده کنید.
`stroke_dash`	string	الگوی خط‌چین (مثلاً `6 3`).
`stack_group`	string	شناسه گروه پشته‌ای برای پشته‌سازی چندین سری فرمول.

خطوط مرجع و نواحی مرجع

خطوط مرجع خطوط راهنمای افقی برای برجسته کردن مقادیر خاص اضافه می‌کنند (مثلاً سربه‌سر در ۱.۰، آستانه اشباع خرید). نواحی مرجع نواحی سایه‌دار برای برجسته کردن بازه‌های مقادیر اضافه می‌کنند (مثلاً ناحیه کم‌ارزش‌گذاری‌شده، باندهای شبیه بولینگر). هر دو از مقادیر ثابت و فرمول‌های پویا با استفاده از همان موتور فرمول فیلد formulas پشتیبانی می‌کنند.

گزینه‌های خط مرجع

فیلد	نوع	توضیحات
`y`	number	مقدار Y ثابت.
`y_formula`	string	عبارت فرمول برای Y پویا (مثلاً `"sma(m1, 200)"`). از همان موتور `formulas` استفاده می‌کند.
`y_axis_id`	string	شناسه محور Y (پیش‌فرض اولین محور چپ).
`stroke`	string	رنگ خط هگز (پیش‌فرض: `#9ca3af`).
`stroke_dasharray`	string	الگوی خط‌چین، مثلاً `"3 3"` برای خط‌چین.
`label`	string	متن برچسب.

یا y (ثابت) یا y_formula (پویا) را ارائه کنید، نه هر دو را. حداکثر ۱۰ خط مرجع در هر نمودار.

گزینه‌های ناحیه مرجع

فیلد	نوع	توضیحات
`y1`	number	کران پایین Y ثابت.
`y2`	number	کران بالای Y ثابت.
`y1_formula`	string	فرمول برای کران پایین پویا.
`y2_formula`	string	فرمول برای کران بالای پویا.
`y_axis_id`	string	شناسه محور Y (پیش‌فرض اولین محور چپ).
`fill`	string	رنگ پُرشدگی هگز (پیش‌فرض: `#3b82f6`).
`fill_opacity`	number	شفافیت پُرشدگی ۰ تا ۱ (پیش‌فرض: `0.1`).
`label`	string	متن برچسب.

کران‌های ثابت (y1/y2) یا مبتنی بر فرمول (y1_formula/y2_formula) را ارائه کنید — می‌توانید آن‌ها را ترکیب کنید (مثلاً y1 ثابت با y2_formula پویا). حداکثر ۱۰ ناحیه مرجع در هر نمودار.

مثال: MVRV با نواحی ارزش

ناحیه سبز کم‌ارزش‌گذاری‌شده (۰ تا ۰.۸۵)، ناحیه قرمز بیش‌ارزش‌گذاری‌شده (۸ تا ۱۰۰) و یک خط سربه‌سر خط‌چین در ۱.۰ اضافه کنید:

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "mvrv",
    "days": 1825,
    "title": "MVRV Ratio — Value Zones",
    "reference_lines": [
      {"y": 1.0, "stroke": "#9ca3af", "stroke_dasharray": "3 3", "label": "Break-even"}
    ],
    "reference_areas": [
      {"y1": 0, "y2": 0.85, "fill": "#16a34a", "fill_opacity": 0.08, "label": "Undervalued"},
      {"y1": 8, "y2": 100, "fill": "#dc2626", "fill_opacity": 0.08, "label": "Overvalued"}
    ]
  }' --output mvrv_zones.png

مثال: باند مبتنی بر فرمول

یک باند شبیه بولینگر حول اولین فرمول ایجاد کنید (پاکت ±۱۰٪):

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["price"],
    "days": 365,
    "formulas": [
      {"expression": "sma(m1, 50)", "label": "50-day SMA", "color": "#2563eb", "style": "line"}
    ],
    "reference_areas": [
      {"y1_formula": "f1 * 0.9", "y2_formula": "f1 * 1.1", "fill": "#2563eb", "fill_opacity": 0.06, "label": "±10% Band"}
    ],
    "reference_lines": [
      {"y_formula": "sma(m1, 200)", "stroke": "#9333ea", "stroke_dasharray": "6 3", "label": "200-day SMA"}
    ]
  }' --output price_bands.png

قالب خروجی

فیلد format خروجی را کنترل می‌کند:

قالب	Content-Type	توضیحات
`png` (پیش‌فرض)	`image/png`	تصویر نمودار رستری
`svg`	`image/svg+xml`	گرافیک برداری (مقیاس‌پذیر، قابل درج)
`json`	`application/json`	فراداده نمودار (بدون رندر)

به‌طور جایگزین، از هدر Accept استفاده کنید:

Accept: image/png - ‏PNG (پیش‌فرض)
Accept: image/svg+xml - ‏SVG
Accept: application/json - فراداده JSON

پاسخ فراداده JSON

وقتی format=json یا Accept: application/json:

{
  "success": true,
  "title": "BTC Price",
  "metrics": [{"id": "price", "label": "BTC Price"}],
  "days": 365,
  "start_date": null,
  "end_date": null,
  "theme": "light",
  "width": 1200,
  "height": 600,
  "formulas": [],
  "data_points": 365,
  "cached": false,
  "render_time_ms": 0
}

نمونه‌ها

# POST with single metric
curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metric": "price", "days": 365}' \
  --output price.png

# Multi-metric with custom styling
curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {"id": "price", "axis": "right", "style": "line", "color": "#374151"},
      {"id": "lth_supply", "axis": "left", "style": "area", "color": "#2563eb"}
    ],
    "days": 730,
    "title": "BTC Price vs LTH Supply",
    "theme": "dark"
  }' \
  --output chart.png

# SVG output
curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template": "mvrv_ratio", "format": "svg"}' \
  --output mvrv.svg

# JSON metadata
curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metric": "price", "format": "json"}' | jq

رندر نقشه حرارتی

‏Snapshot API می‌تواند نمودارهای نقشه حرارتی را برای متریک‌های مبتنی بر توزیع مانند توزیع مبنای هزینه (Cost Basis Distribution) رندر کند. نقشه‌های حرارتی از مجموعه پارامترهای جداگانه‌ای نسبت به نمودارهای متریک استاندارد استفاده می‌کنند.

پارامترهای نقشه حرارتی

پارامتر	نوع	پیش‌فرض	توضیحات
`heatmap_id`	string	-	شناسه نقشه حرارتی (مثلاً `cost-basis-distribution`)
`heatmap_period`	string	`1y`	بازه زمانی: `3m`، `6m`، `1y`، `2y`، `3y`، `5y`، `all`
`heatmap_color_scale`	string	`viridis`	مقیاس رنگ: `viridis`، `plasma`، `inferno`، `magma`، `cividis`
`heatmap_y_scale`	string	`linear`	مقیاس محور Y: `linear` یا `log`
`theme`	string	`light`	تم رنگ: `light` یا `dark`
`title`	string	auto	عنوان نمودار
`width`	integer	1200	عرض تصویر به پیکسل
`height`	integer	600	ارتفاع تصویر به پیکسل

مثال

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "heatmap_id": "cost-basis-distribution",
    "heatmap_period": "1y",
    "heatmap_color_scale": "viridis",
    "heatmap_y_scale": "log",
    "theme": "dark",
    "title": "Cost Basis Distribution"
  }' --output cbd_heatmap.png

توجه: پارامترهای نقشه حرارتی (heatmap_id و غیره) متقابلاً انحصاری با پارامترهای متریک استاندارد (metric، metrics، template) هستند. متریک‌های نقشه حرارتی به سطح Enterprise نیاز دارند.

راهنمای مقیاس رنگ در تصویر رندرشده گنجانده می‌شود و بازه مقادیر نگاشت‌شده به پالت رنگ انتخاب‌شده را نشان می‌دهد.

نمودارهای روی‌هم‌اندازی عملکرد چرخه

نمودارهای عملکرد چرخه چندین چرخه بیت‌کوین را روی همان محور X روی‌هم می‌اندازند تا بتوانید آن‌ها را به‌صورت همسان مقایسه کنید. به‌جای رسم در مقابل تاریخ‌های تقویمی، قیمت هر چرخه نسبت به رویداد لنگر خودش (کف چرخه، ATH یا هاوینگ) شاخص‌گذاری می‌شود و در مقابل روزهای سپری‌شده از آن لنگر رسم می‌شود.

با تنظیم x_axis: "day_offset" در یک درخواست POST /v1/chart/snapshot و قید کردن متریک‌های چرخه در آرایه metrics، حالت روی‌هم‌اندازی را فعال کنید. رندرکننده به‌جای date از فیلد day_offset روی هر نقطه داده استفاده می‌کند، بنابراین همه چرخه‌ها روی محور X از روز ۰ شروع می‌شوند.

برچسب‌های تیک تاریخ‌های تقویمی را از آخرین چرخه خانواده انتخاب‌شده نشان می‌دهند. برای مثال، یک روی‌هم‌اندازی ATH (cycle_ath_1…cycle_ath_5) در 2025-10-06 لنگر می‌اندازد و تیک‌ها Oct '25، Jan '26، Apr '26 و غیره را نشان می‌دهند — نه Day 0، Day 90، Day 180. سایر چرخه‌های همان نمودار با همان موقعیت‌های محور X تراز می‌شوند، بنابراین یک مقدار در تیک Apr '26 روی cycle_ath_3 به‌معنای «BTC در روز ۱۸۲اُم چرخه ۲۰۱۷ چه می‌کرد» است. شماره‌گذاری روز تنها به‌عنوان جایگزین زمانی دوباره ظاهر می‌شود که بک‌اند نتواند لنگر را تعیین کند.

انواع لنگر

سه خانواده از متریک‌های چرخه در دسترس‌اند، یکی برای هر رویداد لنگر:

لنگر	پیشوند شناسه متریک	توضیحات	راهنمای نقطه پایانی
کف چرخه ← کف بعدی	`cycle_low_*`	قیمت شاخص‌گذاری‌شده به کف چرخه — هر سری در تاریخ کف از ۱.۰ شروع می‌شود و تا کف چرخه بعدی ادامه می‌یابد.	`endpoint: "cycle-performance?type=low"`
‏ATH ← ATH	`cycle_ath_*`	قیمت شاخص‌گذاری‌شده به بالاترین قیمت تاریخی چرخه — هر سری در تاریخ ATH از ۱.۰ شروع می‌شود و تا ATH بعدی ادامه می‌یابد.	`endpoint: "cycle-performance?type=ath"`
هاوینگ ← هاوینگ	`cycle_halving_*`	قیمت شاخص‌گذاری‌شده به بلاک هاوینگ — هر سری در تاریخ هاوینگ از ۱.۰ شروع می‌شود و تا هاوینگ بعدی ادامه می‌یابد.	`endpoint: "cycle-performance?type=halving"`

درون یک خانواده لنگر، هر چرخه همان شکل داده است — شاخصی که از ۱.۰ شروع می‌شود و price(t) / price(anchor) را تا رویداد لنگر بعدی (یا برای چرخه جاری، تا امروز) دنبال می‌کند. همین چیزی است که مقایسه روی‌هم‌اندازی را معنادار می‌کند: مقدار 5.0 در روز ۲۰۰اُم cycle_ath_3 به‌معنای «BTC در ۲۰۰ روز پس از ATH خود ۵ برابر ATH سال ۲۰۱۷ بود» است.

همه متریک‌های چرخه در دسترس

شناسه متریک	تاریخ لنگر	لنگر ← تاریخ پایان
`cycle_low_1`	2011-11-18	2011-11-18 → 2015-01-14
`cycle_low_2`	2015-01-14	2015-01-14 → 2018-12-15
`cycle_low_3`	2018-12-15	2018-12-15 → 2022-11-21
`cycle_low_4`	2022-11-21	2022-11-21 → today (current cycle)
`cycle_ath_1`	2011-06-11	2011-06-11 → 2013-11-30
`cycle_ath_2`	2013-11-30	2013-11-30 → 2017-12-17
`cycle_ath_3`	2017-12-17	2017-12-17 → 2021-11-10
`cycle_ath_4`	2021-11-10	2021-11-10 → 2025-10-06
`cycle_ath_5`	2025-10-06	2025-10-06 → today (current cycle)
`cycle_halving_1`	2012-11-28	2012-11-28 → 2016-07-09
`cycle_halving_2`	2016-07-09	2016-07-09 → 2020-05-11
`cycle_halving_3`	2020-05-11	2020-05-11 → 2024-04-20
`cycle_halving_4`	2024-04-20	2024-04-20 → today (current cycle)

قواعد اعتبارسنجی

همه metrics باید از یک خانواده لنگر بیایند. ترکیب cycle_ath_* با cycle_low_* (یا هر چیز خارج از daily_cycle_performance) پاسخ 400 invalid_params بازمی‌گرداند.
پرچم x_axis: "day_offset" فقط برای متریک‌های چرخه معتبر است — جفت کردن آن با هر متریک دیگری پاسخ 400 invalid_params بازمی‌گرداند.
محدودیت استاندارد «حداکثر ۶ متریک در هر نمودار» اعمال می‌شود — تا ۶ چرخه در هر روی‌هم‌اندازی انتخاب کنید.

پارامترهای عملکرد چرخه

علاوه بر همه پارامترهای استاندارد نمودار (days، width، height، theme، scale، format، title، y_axes، reference_lines، reference_areas، formulas و غیره)، حالت روی‌هم‌اندازی چرخه از این فیلدها استفاده می‌کند:

فیلد	نوع	پیش‌فرض	توضیحات
`x_axis`	`"date"` / `"day_offset"`	`"date"`	برای فعال‌سازی روی‌هم‌اندازی چرخه روی `"day_offset"` تنظیم کنید. در غیر این صورت محور X تاریخ تقویمی است.
`metrics`	array	الزامی	‏۱ تا ۶ شناسه متریک چرخه از یک خانواده لنگر. رشته‌ها یا اشیاء (`{id, color, style, label, stroke_width, fill_opacity, show_in_legend, y_axis_id}`).
`days`	integer	365	حداکثر آفست روز رندرشده را محدود می‌کند (بازه محور X، نه روزهای تقویمی). روی `1500` تنظیم کنید تا حدود ۴ سال در هر چرخه ببینید.
`scale`	`"linear"` / `"log"`	`"linear"`	مقیاس لگاریتمی تقریباً همیشه چیزی است که می‌خواهید — ضریب‌های اوایل چرخه می‌توانند ۱۰۰× تا ۵۰۰× باشند که روی مقیاس خطی غیرقابل‌خواندن است.
`theme`	`"light"` / `"dark"`	`"light"`	تم تیره پیش‌فرض داشبورد برای این نمودارهاست.

خطوط مرجع (reference_lines) به‌ویژه روی نمودارهای روی‌هم‌اندازی مفیدند — مثلاً یک خط افقی در y: 1.0 سطح لنگر را علامت می‌زند، y: 2.0 «۲× لنگر» را علامت می‌زند و به همین ترتیب.

مثال: روی‌هم‌اندازی لنگرشده به ATH (رنگ‌های سفارشی برای هر چرخه)

این دستور با نمودار «Price Performance Since ATH» داشبورد مطابقت دارد — پنج چرخه، هر یک با رنگی متمایز، روی محور لگاریتمی.

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {"id": "cycle_ath_1", "color": "#8b5cf6", "label": "2011 ATH cycle"},
      {"id": "cycle_ath_2", "color": "#3b82f6", "label": "2013 ATH cycle"},
      {"id": "cycle_ath_3", "color": "#22c55e", "label": "2017 ATH cycle"},
      {"id": "cycle_ath_4", "color": "#f59e0b", "label": "2021 ATH cycle"},
      {"id": "cycle_ath_5", "color": "#ef4444", "label": "2025 ATH cycle (current)"}
    ],
    "x_axis": "day_offset",
    "scale": "log",
    "y_axes": [
      {"id": "left", "side": "left", "scale": "log", "format": "number"}
    ],
    "reference_lines": [
      {"y": 1.0, "stroke": "#9ca3af", "stroke_dasharray": "3 3", "label": "ATH = 1.0"}
    ],
    "days": 1500,
    "theme": "dark",
    "title": "Price Performance Since ATH"
  }' --output cycle_ath.png

مثال: روی‌هم‌اندازی کف چرخه (فرم مختصر)

برای مقایسه سریع بدون سبک‌دهی به‌ازای هر چرخه، شناسه‌های متریک را به‌صورت رشته‌های ساده ارسال کنید — رنگ‌ها به‌طور خودکار از پالت رجیستری می‌آیند.

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["cycle_low_1", "cycle_low_2", "cycle_low_3", "cycle_low_4"],
    "x_axis": "day_offset",
    "scale": "log",
    "days": 1500,
    "title": "Price Since Cycle Low"
  }' --output cycle_low.png

مثال: روی‌هم‌اندازی لنگرشده به هاوینگ

همان شکل، چهار چرخه لنگرشده در هر رویداد هاوینگ.

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      "cycle_halving_1", "cycle_halving_2", "cycle_halving_3", "cycle_halving_4"
    ],
    "x_axis": "day_offset",
    "scale": "log",
    "days": 1500,
    "theme": "dark",
    "title": "Price Since Halving"
  }' --output cycle_halving.png

معادل ابزار MCP

از یک عامل هوش مصنوعی متصل به سرور MCP، همان نمودار یک فراخوانی ابزار است:

render_chart({
  metrics: [
    { id: "cycle_ath_1", color: "#8b5cf6" },
    { id: "cycle_ath_2", color: "#3b82f6" },
    { id: "cycle_ath_3", color: "#22c55e" },
    { id: "cycle_ath_4", color: "#f59e0b" },
    { id: "cycle_ath_5", color: "#ef4444" }
  ],
  x_axis: "day_offset",
  scale: "log",
  days: 1500,
  theme: "dark",
  title: "Price Performance Since ATH"
})

سرور MCP همان enum مربوط به x_axis، همان شناسه‌های متریک و همان قواعد اعتبارسنجی API مبتنی بر HTTP را می‌پذیرد.

کنترل راهنما به‌ازای هر متریک

از show_in_legend روی اشیاء پیکربندی متریک به‌صورت تکی استفاده کنید تا کنترل کنید آیا یک متریک در راهنمای نمودار ظاهر شود یا خیر. این کار هنگام ترکیب چندین سری که برخی از آن‌ها خطوط زمینه/بافت هستند مفید است.

{
  "metrics": [
    {"id": "price", "show_in_legend": true},
    {"id": "sma_200", "show_in_legend": false}
  ]
}

فیلد	نوع	پیش‌فرض	توضیحات
`show_in_legend`	boolean	`true`	اینکه آیا متریک در راهنمای نمودار ظاهر شود

پیش‌فرض‌های هوشمند

‏Snapshot API از پیش‌فرض‌های هوشمند استفاده می‌کند تا بتوانید با کمترین پیکربندی نمودارهای زیبا بسازید:

پارامتر	چگونگی تعیین پیش‌فرض
سبک نمودار	از رجیستری متریک (`chart_types[0]`)
رنگ	از رجیستری متریک، سپس چرخش پالت
سمت محور Y	اولین متریک در چپ؛ متریک‌های هم‌قالب محور مشترک دارند؛ قالب متفاوت در راست
مقیاس محور Y	`linear` (با `scale=log` بازنویسی کنید)
بازه زمانی	بر اساس دسته‌بندی: ۳۶۵ روز برای price/valuation/profit، ۷۳۰ برای supply، ۱۸۰ برای blockchain
عنوان	تک‌متریک: نام متریک. چندتایی: "Name1 vs Name2"
اندازه تصویر	‏۱۲۰۰ × ۶۰۰ پیکسل
تم	`light`

پاسخ‌های خطا

همه خطاها به‌صورت JSON بازگردانده می‌شوند:

// 400 Bad Request
{"success": false, "error": "invalid_params", "message": "Exactly one of 'metric', 'metrics', or 'template' must be provided"}

// 401 Unauthorized
{"success": false, "error": "unauthorized", "message": "API key required"}

// 403 Forbidden
{"success": false, "error": "insufficient_tier", "message": "Metric 'lth_sopr' requires Pro tier", "upgrade_url": "https://blocklens.co/pricing"}

// 429 Rate Limited
{"success": false, "error": "rate_limited", "message": "Snapshot rate limit exceeded. Max 60 per hour for pro tier.", "retry_after": 120}

// 504 Timeout
{"success": false, "error": "render_timeout", "message": "Chart rendering timed out after 20.0s. Try a shorter date range."}

ابزار MCP: `render_chart`

سرور MCP Blocklens شامل یک ابزار render_chart است که به عامل‌های هوش مصنوعی اجازه می‌دهد تصاویر نمودار را مستقیماً در گفتگوها تولید کنند. این ابزار Snapshot API را فراخوانی می‌کند و تصویر را به‌صورت درون‌خطی به‌عنوان PNG (رستری) یا SVG (برداری) بازمی‌گرداند.

پارامترها

پارامتر	نوع	پیش‌فرض	توضیحات
`metric`	string	-	شناسه یک متریک
`metrics`	array	-	چندین متریک (رشته‌ها یا اشیاء)
`template`	string	-	شناسه قالب
`days`	integer	365	روزهای داده تاریخی
`start_date`	string	-	تاریخ شروع (YYYY-MM-DD)
`end_date`	string	-	تاریخ پایان (YYYY-MM-DD)
`overlay`	`price`	-	افزودن روی‌هم‌اندازی قیمت (در حال حاضر BTC)
`theme`	`light` / `dark`	`light`	تم رنگ
`width`	integer	1200	عرض تصویر
`height`	integer	600	ارتفاع تصویر
`title`	string	auto	عنوان نمودار
`style`	`line` / `area` / `bar`	auto	سبک نمودار
`scale`	`linear` / `log`	`linear`	مقیاس محور Y
`format`	`png` / `svg` / `json`	`png`	قالب خروجی: `png` (تصویر رستری)، `svg` (تصویر برداری، بدون افت کیفیت مقیاس می‌شود) یا `json` (فقط فراداده — بدون رندر)
`y_axes`	array	-	محورهای Y سفارشی با نواحی (به محورهای Y سفارشی مراجعه کنید)
`x_axis`	`date` / `day_offset`	`date`	حالت محور X. برای روی‌هم‌اندازی‌های عملکرد چرخه از `day_offset` استفاده کنید — همه `metrics` باید از یک خانواده چرخه باشند.
`heatmap_id`	`cost-basis-distribution`	-	رندر یک نقشه حرارتی به‌جای نمودار خطی (به رندر نقشه حرارتی مراجعه کنید). متقابلاً انحصاری با `metric` / `metrics` / `template`.
`heatmap_period`	`3m` / `6m` / `1y` / `2y` / `3y` / `5y` / `all`	`1y`	پنجره دسته‌بندی نقشه حرارتی.
`heatmap_color_scale`	`viridis` / `plasma` / `inferno` / `magma` / `cividis`	`viridis`	پالت رنگ نقشه حرارتی.
`heatmap_y_scale`	`linear` / `log`	`linear`	مقیاس محور Y برای دسته‌های قیمت نقشه حرارتی.
`params`	object	-	پارامترهای به‌ازای هر فراخوانی برای متریک‌های پارامتری‌شده (مثلاً `{ "exchange": "binance" }`، `{ "ticker": "IBIT" }`، `{ "entity": "tesla" }`).
`reference_lines`	array	-	خطوط مرجع افقی (به خطوط مرجع و نواحی مرجع مراجعه کنید)
`reference_areas`	array	-	نواحی مرجع سایه‌دار (به خطوط مرجع و نواحی مرجع مراجعه کنید)

نمونه‌های استفاده

User: "Show me the MVRV ratio for the last 2 years"
Agent calls: render_chart({ template: "mvrv_ratio", days: 730 })
-> Returns PNG image inline

User: "Chart BTC price vs LTH supply"
Agent calls: render_chart({
  metrics: [
    { id: "price", axis: "right" },
    { id: "lth_supply", axis: "left", style: "area" }
  ],
  days: 365
})
-> Returns PNG image inline

User: "Is there capitulation? Show SOPR"
Agent calls: render_chart({ template: "sopr", days: 180, overlay: "price" })
-> Returns PNG image inline

User: "Render the MVRV chart as SVG so I can embed it in a slide deck"
Agent calls: render_chart({ template: "mvrv_ratio", format: "svg" })
-> Returns the chart inline as image/svg+xml and a /chart/renders/{id}.svg URL

پیکربندی MCP

برای فعال‌سازی رندر نمودار، این را به پیکربندی Claude Desktop یا Cursor خود اضافه کنید:

{
  "mcpServers": {
    "blocklens": {
      "command": "npx",
      "args": ["-y", "blocklens-mcp-server"],
      "env": {
        "BLOCKLENS_API_KEY": "your_api_key_here"
      }
    }
  }
}

برای دستورالعمل‌های کامل راه‌اندازی به سرور MCP مراجعه کنید.

مثال پیشرفته: نمودار عرضه LTH

این مثال نمودار کامل عرضه دارندگان بلندمدت (Long-Term Holder Supply) از داشبورد Blocklens را بازسازی می‌کند — دو متریک، دو سری فرمول محاسبه‌شده و سه محور Y:

curl -X POST "https://api.blocklens.co/v1/chart/snapshot" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {"id": "price", "label": "BTC Price", "style": "line", "color": "#6b7280", "axis": "right", "fill_opacity": 0, "stroke_width": 1},
      {"id": "lth_supply", "label": "LTH Supply", "style": "line", "color": "#2563eb", "axis": "left", "stroke_width": 2}
    ],
    "y_axes": [
      {"id": "axis-left", "side": "left", "scale": "linear"},
      {"id": "axis-right", "side": "right", "scale": "log"},
      {"id": "axis-diff", "side": "left", "scale": "linear"}
    ],
    "formulas": [
      {"expression": "max(lth_supply - shift(lth_supply, 30), 0)", "label": "LTH 30d+ diff", "color": "#16a34a", "style": "bar", "y_axis_id": "axis-diff", "fill_opacity": 0.2, "stroke_width": 0},
      {"expression": "min(0, lth_supply - shift(lth_supply, 30))", "label": "LTH 30d- diff", "color": "#dc2626", "style": "bar", "y_axis_id": "axis-diff", "fill_opacity": 0.2, "stroke_width": 0}
    ],
    "days": 730,
    "title": "Long-Term Holder Supply"
  }' --output lth_supply.png

این چه چیزی تولید می‌کند:

قیمت BTC — خط خاکستری روی محور راست (مقیاس لگاریتمی)
عرضه LTH — خط آبی روی محور چپ (خطی)
انباشت مثبت ۳۰روزه — میله‌های سبز نیمه‌شفاف روی محور جداگانه axis-diff
توزیع ۳۰روزه — میله‌های قرمز نیمه‌شفاف روی همان محور axis-diff

تکنیک‌های کلیدی به‌کاررفته:

‏shift(lth_supply, 30) مقدار نگاه‌به‌گذشته ۳۰روزه را محاسبه می‌کند
‏max(..., 0) و min(0, ...) تغییرات مثبت و منفی را به سری‌های جداگانه تقسیم می‌کنند
‏y_axis_id: "axis-diff" هر دو میله فرمول را به یک محور اختصاصی مستقل از محورهای اصلی متریک متصل می‌کند
‏fill_opacity: 0.2 + stroke_width: 0 میله‌های شفاف ملایم و بدون حاشیه ایجاد می‌کند

قالب‌های نمودار

پیکربندی‌های کامل نمودار (شامل متریک‌ها، فرمول‌ها، محورها و سبک‌دهی) به‌صورت قالب‌های پشتیبانی‌شده توسط پایگاه داده از طریق این مسیر در دسترس‌اند:

GET /api/lab/templates

این قالب‌ها می‌توانند به‌عنوان مرجعی برای ساخت بدنه‌های درخواست POST خودتان عمل کنند. هر قالب شامل پیکربندی کاملی است که نمودار خاصی را روی داشبورد Blocklens تولید می‌کند.

واترمارک

همه تصاویر نمودار رندرشده شامل یک واترمارک blocklens.co و اطلاعیه حق نشر هستند. این مورد برای هر دو قالب خروجی PNG و SVG اعمال می‌شود.

کش‌گذاری

اسنپ‌شات‌های رندرشده به‌مدت ۱ ساعت در Redis کش می‌شوند. رفتار کش:

پیکربندی‌های نمودار یکسان فوراً نتایج کش‌شده بازمی‌گردانند
کلید کش از پیکربندی کامل نمودار (متریک‌ها، محورها، بازه زمانی، تم، اندازه) به‌علاوه قالب خروجی استخراج می‌شود — گونه‌های PNG و SVG یک نمودار به‌طور مستقل کش می‌شوند
هدر پاسخ X-Snapshot-Cache مقدار HIT یا MISS را نشان می‌دهد
هدر X-Snapshot-Render-Ms زمان رندر را نشان می‌دهد (۰ برای اصابت‌های کش)
فایل‌های رندرشده همچنین به‌مدت ۱ ساعت روی دیسک در /v1/chart/renders/{render_id}.png و /v1/chart/renders/{render_id}.svg پایدار می‌مانند، بنابراین URLهای نموداری که در هدر X-Render-Id بازگردانده می‌شوند قابل‌دسترس باقی می‌مانند
نمودارهای پرطرفدار پس از هر به‌روزرسانی روزانه داده (۰۵:۰۰ UTC) از پیش گرم می‌شوند

نقاط پایانی (Endpoints)​

احراز هویت​

دسترسی و محدودیت‌های نرخ​

‏GET /v1/chart/snapshot​

پارامترها​

قالب‌های در دسترس​

نمونه‌ها​

پاسخ موفق​

‏POST /v1/chart/snapshot​

بدنه درخواست​

فیلد metrics​

گزینه‌های به‌ازای هر متریک​

محورهای Y سفارشی​

مثال: قیمت + حجم با نواحی عمودی​

مثال: افت‌سرمایه با محدودسازی دامنه​

فرمول‌ها​

میانگین‌های متحرک و آماره‌های غلتان​

تجمعی​

تغییرات​

ریاضی​

شاخص‌های تکنیکال​

ریسک و بازده​

دستکاری سری​

عملگرها​

ارجاع‌دهی​

خطوط مرجع و نواحی مرجع​

گزینه‌های خط مرجع​

گزینه‌های ناحیه مرجع​

مثال: MVRV با نواحی ارزش​

مثال: باند مبتنی بر فرمول​

قالب خروجی​

پاسخ فراداده JSON​

نمونه‌ها​

رندر نقشه حرارتی​

پارامترهای نقشه حرارتی​

مثال​

نمودارهای روی‌هم‌اندازی عملکرد چرخه​

انواع لنگر​

همه متریک‌های چرخه در دسترس​

پارامترهای عملکرد چرخه​

مثال: روی‌هم‌اندازی لنگرشده به ATH (رنگ‌های سفارشی برای هر چرخه)​

مثال: روی‌هم‌اندازی کف چرخه (فرم مختصر)​

مثال: روی‌هم‌اندازی لنگرشده به هاوینگ​

معادل ابزار MCP​

کنترل راهنما به‌ازای هر متریک​

پیش‌فرض‌های هوشمند​

پاسخ‌های خطا​

ابزار MCP: render_chart​

پارامترها​

نمونه‌های استفاده​

پیکربندی MCP​

مثال پیشرفته: نمودار عرضه LTH​

قالب‌های نمودار​

واترمارک​

کش‌گذاری​

نقاط پایانی (Endpoints)

احراز هویت

دسترسی و محدودیت‌های نرخ

‏GET `/v1/chart/snapshot`

پارامترها

قالب‌های در دسترس

نمونه‌ها

پاسخ موفق

‏POST `/v1/chart/snapshot`

بدنه درخواست

فیلد metrics

گزینه‌های به‌ازای هر متریک

محورهای Y سفارشی

مثال: قیمت + حجم با نواحی عمودی

مثال: افت‌سرمایه با محدودسازی دامنه

فرمول‌ها

میانگین‌های متحرک و آماره‌های غلتان

تجمعی

تغییرات

ریاضی

شاخص‌های تکنیکال

ریسک و بازده

دستکاری سری

عملگرها

ارجاع‌دهی

خطوط مرجع و نواحی مرجع

گزینه‌های خط مرجع

گزینه‌های ناحیه مرجع

مثال: MVRV با نواحی ارزش

مثال: باند مبتنی بر فرمول

قالب خروجی

پاسخ فراداده JSON

نمونه‌ها

رندر نقشه حرارتی

پارامترهای نقشه حرارتی

مثال

نمودارهای روی‌هم‌اندازی عملکرد چرخه

انواع لنگر

همه متریک‌های چرخه در دسترس

پارامترهای عملکرد چرخه

مثال: روی‌هم‌اندازی لنگرشده به ATH (رنگ‌های سفارشی برای هر چرخه)

مثال: روی‌هم‌اندازی کف چرخه (فرم مختصر)

مثال: روی‌هم‌اندازی لنگرشده به هاوینگ

معادل ابزار MCP

کنترل راهنما به‌ازای هر متریک

پیش‌فرض‌های هوشمند

پاسخ‌های خطا

ابزار MCP: `render_chart`

پارامترها

نمونه‌های استفاده

پیکربندی MCP

مثال پیشرفته: نمودار عرضه LTH

قالب‌های نمودار

واترمارک

کش‌گذاری