快照 API

快照 API 将链上分析图表渲染为 PNG 图像或 SVG 矢量图形。发送指标 ID 和可选的显示参数，即可获得完整渲染的图表图像，可直接嵌入报告、仪表盘或 AI 对话中。目前支持 Bitcoin 指标，并正在扩展多链覆盖（ETH、TON、TRON）。

端点

方法	路径	说明
`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 响应头，因此可在 1 小时内通过 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`

身份验证

所有请求都需通过 Authorization 请求头提供 API 密钥：

Authorization: Bearer YOUR_API_KEY

有关获取 API 密钥的详细信息，请参阅身份验证。

访问权限与速率限制

快照 API 需要 Pro 或 Enterprise 级别。Demo 和 Free 级别的密钥将收到 403 Forbidden。

快照 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`

通过查询参数生成图表。最适合简单的单指标或基于模板的图表。

参数

参数	类型	默认值	说明
`metric`	string	-	单个指标 ID（例如 `price`、`lth_supply`）。与 `metrics` 和 `template` 互斥。
`metrics`	string	-	逗号分隔的指标 ID，最多 6 个（例如 `lth_supply,sth_supply`）。与 `metric` 和 `template` 互斥。
`template`	string	-	预定义模板 ID。与 `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 请求体进行完整的图表自定义。支持逐指标样式、自定义坐标轴、公式、参考线、参考区域等。专为 AI 智能体（通过 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	必填。注册表中的指标 ID。
`params`	object	参数化指标的参数（例如 `{"exchange": "binance"}`）。所需参数请参阅指标定义。
`axis`	`left` / `right`	Y 轴侧。若省略则自动分配。
`y_axis_id`	string	通过 ID 绑定到特定 Y 轴（例如 `axis-diff`）。覆盖 `axis`。
`style`	`line` / `area` / `bar`	图表样式。若省略则使用注册表默认值。
`color`	string	十六进制颜色（例如 `#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	堆叠图表的堆叠组 ID。
`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% 的留白。当域值钳制是硬边界时很有用（例如回撤封顶为 0）。

如果省略 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]）
两个序列永不重叠，形成清晰的堆叠布局

示例：带域值钳制的回撤

将回撤封顶为 0（顶边缘），使线条触及其区域的顶部：

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" 移除 0 上方自动的 10% 留白，使回撤为 0% 时线条触及顶部
价格位于右轴，采用对数刻度

公式

formulas 字段允许你定义从指标派生的计算序列。公式可以通过 id（例如 lth_supply）或按位置索引（基于 metrics 数组中的顺序的 m1、m2 等）引用指标。

"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——直接使用指标 ID
按位置引用指标： m1 + m2——位置引用（m1 = 第一个指标，m2 = 第二个，依此类推）
引用其他公式： f1 * 2——引用更早的公式（f1 = 第一个公式，依此类推）
公式按顺序求值，因此 f2 可以引用 f1，但反之不行。

公式选项：

字段	类型	说明
`expression`	string	必填。使用指标 ID 或位置引用（`m1`、`m2`）的公式表达式。
`label`	string	必填。图例的显示标签。
`color`	string	十六进制颜色。若省略则自动分配。
`style`	`line` / `area` / `bar`	图表样式。默认值：`line`。
`y_axis_id`	string	通过 ID 绑定到特定 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	用于堆叠多个公式序列的堆叠组 ID。

参考线与参考区域

参考线添加水平引导线以突出特定值（例如 1.0 处的盈亏平衡、超买阈值）。参考区域添加阴影区域以突出值范围（例如低估区域、类布林带）。两者都支持静态值，以及使用与 formulas 字段相同公式引擎的动态公式。

参考线选项

字段	类型	说明
`y`	number	静态 Y 值。
`y_formula`	string	用于动态 Y 的公式表达式（例如 `"sma(m1, 200)"`）。使用与 `formulas` 相同的引擎。
`y_axis_id`	string	Y 轴 ID（默认为第一个左轴）。
`stroke`	string	线条颜色十六进制（默认值：`#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 轴 ID（默认为第一个左轴）。
`fill`	string	填充颜色十六进制（默认值：`#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

热力图渲染

快照 API 可以为基于分布的指标（如成本基础分布）渲染热力图。热力图使用与标准指标图表不同的一组参数。

热力图参数

参数	类型	默认值	说明
`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 或减半）建立索引，并相对于自该锚点以来的天数绘制。

通过在 POST /v1/chart/snapshot 请求上设置 x_axis: "day_offset" 并在 metrics 数组中提供周期指标，即可开启叠加模式。渲染器使用每个数据点上的 day_offset 字段而非 date，因此所有周期在 X 轴上都从第 0 天开始。

刻度标签显示所选系列中最新周期的日历日期。 例如，ATH 叠加（cycle_ath_1…cycle_ath_5）锚定于 2025-10-06，刻度读作 Oct '25、Jan '26、Apr '26 等——而非 Day 0、Day 90、Day 180。同一图表中的其他周期对齐到相同的 X 轴位置，因此 cycle_ath_3 上 Apr '26 刻度处的值意味着“2017 周期第 182 天时 BTC 的表现”。仅当后端无法确定锚点时，才会回退到天数编号显示。

锚点类型

提供三个周期指标系列，每个对应一种锚定事件：

锚点	指标 ID 前缀	说明	端点提示
周期低点 → 下一个低点	`cycle_low_*`	价格相对于周期底部建立索引——每个序列在低点日期从 1.0 开始，持续到下一周期的低点。	`endpoint: "cycle-performance?type=low"`
ATH → ATH	`cycle_ath_*`	价格相对于周期的历史最高点建立索引——每个序列在 ATH 日期从 1.0 开始，持续到下一个 ATH。	`endpoint: "cycle-performance?type=ath"`
减半 → 减半	`cycle_halving_*`	价格相对于减半区块建立索引——每个序列在减半日期从 1.0 开始，持续到下一次减半。	`endpoint: "cycle-performance?type=halving"`

在一个锚点系列内，每个周期都是相同形状的数据——一个从 1.0 开始并跟踪 price(t) / price(anchor) 直到下一个锚定事件（或对于当前周期，直到今天）的索引。这正是叠加对比有意义的原因：cycle_ath_3 第 200 天处值为 5.0 意味着“BTC 在 2017 ATH 之后 200 天时是其 ATH 的 5 倍”。

所有可用的周期指标

指标 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 → 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。
适用标准的“每张图表最多 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。字符串或对象（`{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

示例：周期低点叠加（简写形式）

如需在不进行逐周期样式设置的情况下快速对比，将指标 ID 作为纯字符串传入——颜色会自动从注册表调色板获取。

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 服务器的 AI 智能体来看，同一图表只需一次工具调用：

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 服务器接受与 HTTP API 相同的 x_axis 枚举、相同的指标 ID 和相同的验证规则。

逐指标图例控制

在单个指标配置对象上使用 show_in_legend 来控制某个指标是否出现在图表图例中。当组合多个序列且其中一些是上下文/背景线时，这很有用。

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

字段	类型	默认值	说明
`show_in_legend`	boolean	`true`	指标是否出现在图表图例中

智能默认值

快照 API 使用智能默认值，让你只需极少配置即可获得美观的图表：

参数	默认值的确定方式
图表样式	来自指标注册表（`chart_types[0]`）
颜色	来自指标注册表，然后是调色板轮换
Y 轴侧	第一个指标在左侧；相同格式的指标共享坐标轴；不同格式置于右侧
Y 轴刻度	`linear`（用 `scale=log` 覆盖）
时间范围	基于类别：price/valuation/profit 为 365 天，supply 为 730 天，blockchain 为 180 天
标题	单个指标：指标名称。多个：“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`

Blocklens MCP 服务器包含一个 render_chart 工具，可让 AI 智能体直接在对话中生成图表图像。该工具调用快照 API，并以 PNG（栅格）或 SVG（矢量）形式内联返回图像。

参数

参数	类型	默认值	说明
`metric`	string	-	单个指标 ID
`metrics`	array	-	多个指标（字符串或对象）
`template`	string	-	模板 ID
`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 Supply 图表

此示例复现 Blocklens 仪表盘上完整的 Long-Term Holder Supply 图表——两个指标、两个计算公式序列和三个 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 仪表盘上特定图表的完整配置。

水印

缓存

渲染的快照在 Redis 中缓存 1 小时。缓存行为：

相同的图表配置会立即返回缓存结果
缓存键派生自完整的图表配置（指标、坐标轴、时间范围、主题、尺寸）外加输出格式——同一图表的 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 小时，因此 X-Render-Id 响应头返回的图表 URL 在此期间保持可访问
热门图表会在每次每日数据更新（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 图表

图表模板

水印

缓存