Snapshot API

Snapshot 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 キーの取得方法の詳細については、認証を参照してください。

アクセスとレート制限

Snapshot API は Pro または Enterprise プランが必要です。Demo および Free プランのキーには 403 Forbidden が返されます。

Snapshot API は Data API と同じレート制限に従います。詳細についてはレート制限を参照してください。

レート制限に達すると、API は retry_after フィールドを含む 429 Too Many Requests を返します。

メトリクスへのアクセスもグレードによって制限されます。グレード 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 のいずれか 1 つを必ず指定する必要があります。

利用可能なテンプレート

テンプレート	メトリクス
`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 の例：BTC 価格、1 年間、折れ線チャート
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" \
  --output price.png

# Bitcoin の例：エリアスタイルの 2 つのメトリクス
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

# ダークテーマのテンプレート
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?template=mvrv_ratio&theme=dark" \
  --output mvrv_dark.png

# 価格オーバーレイ付きの対数スケール
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

# 画像の代わりに JSON メタデータを取得
curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" | jq

# PNG の代わりに SVG を取得
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）を必ず 1 つだけ指定してください。

{
  "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 のいずれか 1 つを必ず指定する必要があります。

Metrics フィールド

metrics フィールドは複数の型に対応しています。

// 文字列のショートハンド
["price", "lth_supply"]

// 完全な設定オブジェクト
[{"id": "price", "axis": "right", "style": "line", "color": "#374151"}]

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

// パラメータ化されたメトリクス向けの params 付き
[
  {"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	16 進数カラー（例：`#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 から参照できます。3 つ以上の軸を定義することもできます。たとえば、計算した差分用に別の軸を用意できます。

"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` = 上端。デフォルト：全高。軸を垂直方向に積み重ねる際に使用します（例：volume を下端 20%、price を上端 80% に配置）。
`domain_min`	number	ドメインの下限を固定するクランプ。軸はこの値を下回りません。
`domain_max`	number	ドメインの上限を固定するクランプ。軸はこの値を上回りません。
`no_padding`	`"top"` / `"bottom"` / `"both"`	端の自動 10% パディングを削除します。ドメインクランプが厳密な境界となる場合に有用です（例：ドローダウンを 0 で上限とする場合）。

y_axes を省略した場合、メトリクスの axis 値に基づいて軸が自動生成されます。

例：垂直ゾーン付きの Price + Volume

出来高バーを下端 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]）を対数スケールで占めます
2 つの系列が重ならないため、整然とした積み上げレイアウトになります

例：ドメインクランプ付きのドローダウン

ドローダウンを 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 = 2 番目など）
他の数式： f1 * 2 — 先行する数式を参照します（f1 = 最初の数式など）
数式は順番に評価されるため、f2 は f1 を参照できますが、その逆はできません。

数式オプション：

フィールド	型	説明
`expression`	string	必須。メトリクス ID または位置参照（`m1`、`m2`）を使用する数式。
`label`	string	必須。凡例に表示するラベル。
`color`	string	16 進数カラー。省略時は自動割り当て。
`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	線の色の 16 進数（デフォルト：`#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	塗りつぶしの色の 16 進数（デフォルト：`#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
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

# カスタムスタイルの複数メトリクス
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 出力
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 メタデータ
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、または半減期）を基準にインデックス化し、そのアンカーからの経過日数に対してプロットします。

POST /v1/chart/snapshot リクエストで x_axis: "day_offset" を設定し、metrics 配列にサイクルメトリクスを指定することで、オーバーレイモードを有効にします。レンダラーは各データポイントの date ではなく day_offset フィールドを使用するため、すべてのサイクルが X 軸上の Day 0 から始まります。

目盛りラベルには、選択したファミリーの最新サイクルのカレンダー日付が表示されます。 たとえば、ATH オーバーレイ（cycle_ath_1…cycle_ath_5）は 2025-10-06 にアンカーされ、目盛りは Day 0、Day 90、Day 180 ではなく Oct '25、Jan '26、Apr '26 などと表示されます。同じチャート内の他のサイクルも同じ X 軸位置に揃えられるため、cycle_ath_3 の Apr '26 目盛りにおける値は「2017 年サイクルの 182 日目に BTC がどうなっていたか」を意味します。バックエンドがアンカーを判定できない場合のフォールバックとして、日数による番号付けが再び表示されます。

アンカーの種類

サイクルメトリクスには 3 つのファミリーがあり、それぞれが 1 つのアンカーイベントに対応します。

アンカー	メトリクス 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 という値は、「その ATH の 200 日後に BTC が 2017 年の 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 → 本日（現在のサイクル）
`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。文字列またはオブジェクト（`{id, color, style, label, stroke_width, fill_opacity, show_in_legend, y_axis_id}`）。
`days`	integer	365	レンダリングされる最大日数オフセット（カレンダー日数ではなく X 軸の範囲）を制限します。サイクルあたり約 4 年を表示するには `1500` に設定します。
`scale`	`"linear"` / `"log"`	`"linear"`	対数スケールがほぼ常に望ましい選択です。サイクル初期の倍率は 100×〜500× になることがあり、線形では判読できません。
`theme`	`"light"` / `"dark"`	`"light"`	これらのチャートではダークテーマがダッシュボードのデフォルトです。

参照線（reference_lines）はオーバーレイチャートで特に有用です。たとえば、y: 1.0 の水平線はアンカーレベルを示し、y: 2.0 は「アンカーの 2 倍」を示す、といった具合です。

例：ATH を基準としたオーバーレイ（サイクルごとのカスタムカラー）

このレシピは、ダッシュボードの「Price Performance Since ATH」チャートに対応します。5 つのサイクルをそれぞれ異なる色で、対数軸に表示します。

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

例：半減期を基準としたオーバーレイ

同じ形で、各半減期イベントを基準とした 4 つのサイクル。

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 エージェントからは、同じチャートを 1 回のツール呼び出しで生成できます。

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`	メトリクスをチャートの凡例に表示するかどうか

スマートデフォルト

Snapshot 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 サーバーには、AI エージェントが対話の中で直接チャート画像を生成できる render_chart ツールが含まれています。このツールは Snapshot 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 チャートを完全に再現します。2 つのメトリクス、2 つの計算された数式系列、および 3 つの 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 の両方の出力フォーマットに適用されます。

キャッシュ

レンダリングされたスナップショットは、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 軸​

例：垂直ゾーン付きの Price + Volume​

例：ドメインクランプ付きのドローダウン​

数式​

移動平均とローリング統計​

累積​

変化​

数学​

テクニカル指標​

リスクとリターン​

系列の操作​

演算子​

参照​

参照線と参照エリア​

参照線オプション​

参照エリアオプション​

例：価格ゾーン付きの MVRV​

例：数式ベースのバンド​

出力フォーマット​

JSON メタデータレスポンス​

例​

ヒートマップのレンダリング​

ヒートマップパラメータ​

例​

サイクルパフォーマンスのオーバーレイチャート​

アンカーの種類​

利用可能なすべてのサイクルメトリクス​

サイクルパフォーマンスパラメータ​

例：ATH を基準としたオーバーレイ（サイクルごとのカスタムカラー）​

例：サイクル安値オーバーレイ（ショートハンド形式）​

例：半減期を基準としたオーバーレイ​

MCP ツールの同等処理​

メトリクスごとの凡例制御​

スマートデフォルト​

エラーレスポンス​

MCP ツール：render_chart​

パラメータ​

使用例​

MCP の設定​

応用例：LTH Supply チャート​

チャートテンプレート​

ウォーターマーク​

キャッシュ​

エンドポイント

認証

アクセスとレート制限

GET `/v1/chart/snapshot`

パラメータ

利用可能なテンプレート

例

成功レスポンス

POST `/v1/chart/snapshot`

リクエストボディ

Metrics フィールド

メトリクスごとのオプション

カスタム Y 軸

例：垂直ゾーン付きの Price + Volume

例：ドメインクランプ付きのドローダウン

数式

移動平均とローリング統計

累積

変化

数学

テクニカル指標

リスクとリターン

系列の操作

演算子

参照

参照線と参照エリア

参照線オプション

参照エリアオプション

例：価格ゾーン付きの MVRV

例：数式ベースのバンド

出力フォーマット

JSON メタデータレスポンス

例

ヒートマップのレンダリング

ヒートマップパラメータ

例

サイクルパフォーマンスのオーバーレイチャート

アンカーの種類

利用可能なすべてのサイクルメトリクス

サイクルパフォーマンスパラメータ

例：ATH を基準としたオーバーレイ（サイクルごとのカスタムカラー）

例：サイクル安値オーバーレイ（ショートハンド形式）

例：半減期を基準としたオーバーレイ

MCP ツールの同等処理

メトリクスごとの凡例制御

スマートデフォルト

エラーレスポンス

MCP ツール：`render_chart`

パラメータ

使用例

MCP の設定

応用例：LTH Supply チャート

チャートテンプレート

ウォーターマーク

キャッシュ