Snapshot API

Snapshot API отрисовывает графики on-chain аналитики в виде PNG-изображений или векторной графики SVG. Передайте идентификаторы метрик и необязательные параметры отображения — и получите полностью отрисованное изображение графика, готовое для встраивания в отчёты, дашборды или диалоги с ИИ. На данный момент поддерживаются метрики Bitcoin, при этом мультичейн-покрытие (ETH, TON, TRON) расширяется.

Эндпоинты

Метод	Путь	Описание
`GET`	`/v1/chart/snapshot`	Простые графики через query-параметры
`POST`	`/v1/chart/snapshot`	Полная настройка через JSON-тело

Оба эндпоинта по умолчанию возвращают image/png. Переключиться на SVG (image/svg+xml) или JSON-метаданные (application/json) можно, задав заголовок запроса Accept или — для POST — поле format в теле ("png", "svg", "json").

Успешные ответы в формате PNG и SVG содержат заголовок X-Render-Id, чтобы отрисованный график можно было повторно получить по URL в течение 1 часа:

Вывод	Кэшируется по адресу
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.

Доступ к метрикам также ограничивается по грейдам: метрики грейда 0 (price, supply, MVRV) доступны всем ключам Pro и выше, метрики грейда 1 (SOPR, P&L) требуют тарифа Pro, а метрики грейда 2 (тепловые карты CBD) требуют тарифа Enterprise.

GET `/v1/chart/snapshot`

Генерация графика по query-параметрам. Лучше всего подходит для простых графиков с одной метрикой или на основе шаблона.

Параметры

Параметр	Тип	По умолчанию	Описание
`metric`	string	-	Идентификатор одной метрики (например, `price`, `lth_supply`). Взаимоисключающий с `metrics` и `template`.
`metrics`	string	-	Идентификаторы метрик через запятую, максимум 6 (например, `lth_supply,sth_supply`). Взаимоисключающий с `metric` и `template`.
`template`	string	-	Идентификатор предопределённого шаблона. Взаимоисключающий с `metric` и `metrics`.
`days`	integer	365	Количество дней исторических данных (7–10000).
`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	Ширина изображения в пикселях (600–2400).
`height`	integer	600	Высота изображения в пикселях (300–1200).
`title`	string	auto	Заголовок графика. Генерируется автоматически по названиям метрик, если не указан.
`theme`	string	`light`	Цветовая тема: `light` или `dark`.

Должен быть указан ровно один из параметров: metric, metrics или template.

Доступные шаблоны

Шаблон	Метрики
`price`	BTC Price
`price_volume`	Price + Volume
`market_cap`	Market Cap
`holder_supply`	LTH Supply + STH Supply
`mvrv_ratio`	LTH MVRV + STH MVRV
`realized_price`	LTH Realized Price + STH Realized Price
`realized_cap`	LTH Realized Cap + STH Realized Cap
`unrealized_pl`	LTH Unrealized P/L + STH Unrealized P/L
`realized_pl`	LTH Realized P/L + STH Realized P/L
`sopr`	LTH SOPR + STH SOPR
`block_height`	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 в течение 1 часа.

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	Цвет в hex (например, `#2563eb`). Назначается автоматически, если не указан.
`label`	string	Отображаемая подпись. Используется название метрики, если не указано.
`stroke_width`	integer	Толщина линии (0–5). По умолчанию: 2. Используйте 0 для столбцов без границ.
`fill_opacity`	float	Непрозрачность заливки (0.0–1.0). Для прозрачных столбцов используйте небольшие значения, например 0.2.
`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` = верх. По умолчанию: вся высота. Используйте, чтобы разнести оси по вертикали друг над другом (например, объём в нижних 20%, цена в верхних 80%).
`domain_min`	number	Жёсткое ограничение минимума домена. Ось никогда не опустится ниже этого значения.
`domain_max`	number	Жёсткое ограничение максимума домена. Ось никогда не поднимется выше этого значения.
`no_padding`	`"top"` / `"bottom"` / `"both"`	Убрать автоматический 10%-й отступ от краёв. Полезно, когда ограничение домена является жёсткой границей (например, просадка ограничена нулём).

Если y_axes не указано, оси генерируются автоматически на основе значений axis у метрик.

Пример: цена + объём с вертикальными зонами

Разместить столбцы объёма в нижних 20%, а цену — в оставшемся пространстве:

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

Что это даёт:

Столбцы объёма заполняют нижние 20% графика (range: [0, 20]) без отступа у нижнего края
Цена занимает верхние 80% (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

Что это даёт:

Просадка всегда ≤ 0, поэтому domain_max: 0 ограничивает верхний край
no_padding: "top" убирает автоматический 10%-й отступ над 0, заставляя линию касаться верха, когда просадка равна 0%
Цена находится на правой оси с логарифмической шкалой

Формулы

Поле 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
  }
]

Поддерживаемые функции (всего 30):

Скользящие средние и скользящая статистика

Функция	Синтаксис	Описание
`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)`	Процентное изменение (в долях: 0.20 = +20%)
`diff`	`diff(series, period)`	Изменение абсолютного значения

Математика

Функция	Синтаксис	Описание
`abs`	`abs(series)`	Абсолютное значение
`pow`	`pow(series, n)`	Возведение в степень n
`log`	`log(series)`	Логарифм по основанию 10
`round`	`round(series, digits)`	Округление до N знаков после запятой
`max`	`max(a, b, ...)`	Поточечный максимум
`min`	`min(a, b, ...)`	Поточечный минимум

Технические индикаторы

Функция	Синтаксис	Описание
`rsi`	`rsi(series, period)`	Индекс относительной силы (0–100)
`corr`	`corr(s1, s2, period)`	Корреляция Пирсона (от -1 до 1)
`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	Цвет в hex. Назначается автоматически, если не указан.
`style`	`line` / `area` / `bar`	Стиль графика. По умолчанию: `line`.
`y_axis_id`	string	Привязка к конкретной оси Y по идентификатору (например, `axis-diff`). Переопределяет `axis`.
`axis`	`left` / `right`	Сторона оси Y. По умолчанию: `left`. Игнорируется, если задан `y_axis_id`.
`fill_opacity`	float	Непрозрачность заливки (0.0–1.0). Для прозрачных столбцов используйте небольшие значения, например 0.2.
`stroke_width`	integer	Толщина обводки (0–5). Используйте 0 для столбцов без границ.
`stroke_dash`	string	Шаблон пунктира (например, `6 3`).
`stack_group`	string	Идентификатор группы стека для накопления нескольких рядов формул.

Опорные линии и области

Опорные линии добавляют горизонтальные направляющие линии для выделения конкретных значений (например, точки безубыточности на уровне 1.0, порога перекупленности). Опорные области добавляют затенённые зоны для выделения диапазонов значений (например, зоны недооценённости, полос по типу Боллинджера). Обе поддерживают статические значения и динамические формулы, используя тот же движок формул, что и поле formulas.

Опции опорной линии

Поле	Тип	Описание
`y`	number	Статическое значение Y.
`y_formula`	string	Выражение формулы для динамического Y (например, `"sma(m1, 200)"`). Использует тот же движок, что и `formulas`.
`y_axis_id`	string	Идентификатор оси Y (по умолчанию — первая левая ось).
`stroke`	string	Цвет линии в hex (по умолчанию: `#9ca3af`).
`stroke_dasharray`	string	Шаблон пунктира, например `"3 3"` для пунктирной линии.
`label`	string	Текст подписи.

Укажите либо y (статическое), либо y_formula (динамическое), но не оба. Максимум 10 опорных линий на график.

Опции опорной области

Поле	Тип	Описание
`y1`	number	Статическая нижняя граница Y.
`y2`	number	Статическая верхняя граница Y.
`y1_formula`	string	Формула для динамической нижней границы.
`y2_formula`	string	Формула для динамической верхней границы.
`y_axis_id`	string	Идентификатор оси Y (по умолчанию — первая левая ось).
`fill`	string	Цвет заливки в hex (по умолчанию: `#3b82f6`).
`fill_opacity`	number	Непрозрачность заливки 0–1 (по умолчанию: `0.1`).
`label`	string	Текст подписи.

Укажите статические границы (y1/y2) или границы на основе формул (y1_formula/y2_formula) — их можно смешивать (например, статическое y1 с динамическим y2_formula). Максимум 10 опорных областей на график.

Пример: MVRV с зонами стоимости

Добавить зелёную зону недооценённости (0–0.85), красную зону переоценённости (8–100) и пунктирную линию безубыточности на уровне 1.0:

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

Пример: полоса на основе формулы

Создать полосу по типу Боллинджера вокруг первой формулы (огибающая ±10%):

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.

Легенда цветовой шкалы включается в отрисованное изображение, показывая диапазон значений, сопоставленный с выбранной цветовой палитрой.

Графики наложения производительности циклов

Графики производительности циклов накладывают несколько циклов Bitcoin на одну ось X, чтобы их можно было сравнивать на равных. Вместо построения по календарным датам цена каждого цикла индексируется относительно собственного опорного события (минимума цикла, ATH или халвинга) и строится по числу дней с момента этого опорного события.

Включите режим наложения, задав x_axis: "day_offset" в запросе POST /v1/chart/snapshot и передав метрики циклов в массиве metrics. Рендерер использует поле day_offset каждой точки данных вместо date, поэтому все циклы начинаются с Дня 0 на оси 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 на 182-й день цикла 2017 года». Нумерация по дням появляется в качестве запасного варианта только в том случае, если бэкенд не может определить опорную точку.

Типы опорных точек

Доступны три семейства метрик циклов, по одному на каждое опорное событие:

Опорная точка	Префикс ID метрики	Описание	Подсказка по эндпоинту
Минимум цикла → следующий минимум	`cycle_low_*`	Цена, индексированная относительно дна цикла — каждый ряд начинается с 1.0 на дату минимума и идёт до минимума следующего цикла.	`endpoint: "cycle-performance?type=low"`
ATH → ATH	`cycle_ath_*`	Цена, индексированная относительно исторического максимума цикла — каждый ряд начинается с 1.0 на дату ATH и идёт до следующего ATH.	`endpoint: "cycle-performance?type=ath"`
Халвинг → халвинг	`cycle_halving_*`	Цена, индексированная относительно блока халвинга — каждый ряд начинается с 1.0 на дату халвинга и идёт до следующего халвинга.	`endpoint: "cycle-performance?type=halving"`

В пределах семейства опорных точек каждый цикл представляет собой данные одинаковой формы — индекс, который начинается с 1.0 и отслеживает price(t) / price(anchor) до следующего опорного события (или, для текущего цикла, до сегодняшнего дня). Именно это делает сравнение наложением осмысленным: значение 5.0 на 200-й день cycle_ath_3 означает «BTC был в 5× выше своего ATH 2017 года через 200 дней после этого ATH».

Все доступные метрики циклов

ID метрики	Дата опорной точки	Опорная точка → конечная дата
`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 → сегодня (текущий цикл)
`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 → сегодня (текущий цикл)
`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 → сегодня (текущий цикл)

Правила валидации

Все metrics должны быть из одного семейства опорных точек. Смешивание cycle_ath_* с cycle_low_* (или чем-либо за пределами daily_cycle_performance) возвращает 400 invalid_params.
Флаг x_axis: "day_offset" действителен только для метрик циклов — его сочетание с любой другой метрикой возвращает 400 invalid_params.
Действует стандартный лимит «максимум 6 метрик на график» — выбирайте до 6 циклов на наложение.

Параметры производительности циклов

В дополнение ко всем стандартным параметрам графика (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	обязательное	1–6 идентификаторов метрик циклов из одного семейства опорных точек. Строки или объекты (`{id, color, style, label, stroke_width, fill_opacity, show_in_legend, y_axis_id}`).
`days`	integer	365	Ограничивает максимальное смещение дня при отрисовке (диапазон оси X, а не календарные дни). Установите `1500`, чтобы видеть ~4 года на цикл.
`scale`	`"linear"` / `"log"`	`"linear"`	Логарифмическая шкала почти всегда — то, что вам нужно: множители ранних циклов могут составлять 100×–500×, что нечитаемо на линейной шкале.
`theme`	`"light"` / `"dark"`	`"light"`	Тёмная тема используется в дашборде по умолчанию для этих графиков.

Опорные линии (reference_lines) особенно полезны на графиках наложения — например, горизонтальная линия на y: 1.0 отмечает уровень опорной точки, y: 2.0 отмечает «2× от опорной точки» и т. д.

Пример: наложение с привязкой к 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, те же идентификаторы метрик и те же правила валидации, что и HTTP API.

Управление легендой для отдельных метрик

Используйте 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`)
Временной диапазон	По категории: 365 дней для price/valuation/profit, 730 для supply, 180 для blockchain
Заголовок	Одна метрика: название метрики. Несколько: "Name1 vs Name2"
Размер изображения	1200 x 600 пикселей
Тема	`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 Server.

Продвинутый пример: график LTH Supply

Этот пример воспроизводит полный график 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 Price — серая линия на правой оси (логарифмическая шкала)
LTH Supply — синяя линия на левой оси (линейная)
30-дневное положительное накопление — полупрозрачные зелёные столбцы на отдельной оси axis-diff
30-дневное распределение — полупрозрачные красные столбцы на той же оси axis-diff

Использованные ключевые приёмы:

shift(lth_supply, 30) вычисляет значение с оглядкой на 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.

Кэширование

Отрисованные снимки кэшируются на 1 час в Redis. Поведение кэша:

Идентичные конфигурации графиков мгновенно возвращают кэшированные результаты
Ключ кэша вычисляется из полной конфигурации графика (метрики, оси, временной диапазон, тема, размер) плюс формат вывода — варианты PNG и SVG одного и того же графика кэшируются независимо
Заголовок ответа X-Snapshot-Cache показывает HIT или MISS
Заголовок X-Snapshot-Render-Ms показывает время отрисовки (0 для попаданий в кэш)
Отрисованные файлы также сохраняются на диске по адресам /v1/chart/renders/{render_id}.png и /v1/chart/renders/{render_id}.svg в течение 1 часа, поэтому URL графиков, возвращаемые в заголовке X-Render-Id, остаются доступными
Популярные графики предварительно прогреваются после каждого ежедневного обновления данных (05:00 UTC)

Эндпоинты​

Аутентификация​

Доступ и лимиты запросов​

GET /v1/chart/snapshot​

Параметры​

Доступные шаблоны​

Примеры​

Успешный ответ​

POST /v1/chart/snapshot​

Тело запроса​

Поле metrics​

Опции для отдельных метрик​

Пользовательские оси Y​

Пример: цена + объём с вертикальными зонами​

Пример: просадка с ограничением домена​

Формулы​

Скользящие средние и скользящая статистика​

Накопительные​

Изменения​

Математика​

Технические индикаторы​

Риск и доходность​

Манипуляции с рядами​

Операторы​

Ссылки​

Опорные линии и области​

Опции опорной линии​

Опции опорной области​

Пример: MVRV с зонами стоимости​

Пример: полоса на основе формулы​

Формат вывода​

Ответ с JSON-метаданными​

Примеры​

Отрисовка тепловых карт​

Параметры тепловой карты​

Пример​

Графики наложения производительности циклов​

Типы опорных точек​

Все доступные метрики циклов​

Параметры производительности циклов​

Пример: наложение с привязкой к ATH (пользовательские цвета для каждого цикла)​

Пример: наложение по минимуму цикла (сокращённая форма)​

Пример: наложение с привязкой к халвингу​

Эквивалент через MCP-инструмент​

Управление легендой для отдельных метрик​

Умные значения по умолчанию​

Ответы с ошибками​

MCP-инструмент: render_chart​

Параметры​

Примеры использования​

Конфигурация MCP​

Продвинутый пример: график LTH Supply​

Шаблоны графиков​

Водяной знак​

Кэширование​

Эндпоинты

Аутентификация

Доступ и лимиты запросов

GET `/v1/chart/snapshot`

Параметры

Доступные шаблоны

Примеры

Успешный ответ

POST `/v1/chart/snapshot`

Тело запроса

Поле metrics

Опции для отдельных метрик

Пользовательские оси Y

Пример: цена + объём с вертикальными зонами

Пример: просадка с ограничением домена

Формулы

Скользящие средние и скользящая статистика

Накопительные

Изменения

Математика

Технические индикаторы

Риск и доходность

Манипуляции с рядами

Операторы

Ссылки

Опорные линии и области

Опции опорной линии

Опции опорной области

Пример: MVRV с зонами стоимости

Пример: полоса на основе формулы

Формат вывода

Ответ с JSON-метаданными

Примеры

Отрисовка тепловых карт

Параметры тепловой карты

Пример

Графики наложения производительности циклов

Типы опорных точек

Все доступные метрики циклов

Параметры производительности циклов

Пример: наложение с привязкой к ATH (пользовательские цвета для каждого цикла)

Пример: наложение по минимуму цикла (сокращённая форма)

Пример: наложение с привязкой к халвингу

Эквивалент через MCP-инструмент

Управление легендой для отдельных метрик

Умные значения по умолчанию

Ответы с ошибками

MCP-инструмент: `render_chart`

Параметры

Примеры использования

Конфигурация MCP

Продвинутый пример: график LTH Supply

Шаблоны графиков

Водяной знак

Кэширование