스냅샷 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는 데이터 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 중 정확히 하나를 제공해야 합니다.

사용 가능한 템플릿

템플릿	지표
`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를 사용하는) AI 에이전트와 고급 사용자를 위해 설계되었습니다.

요청 본문

정확히 하나의 데이터 소스(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	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로 참조할 수 있습니다. 두 개 이상의 축을 정의할 수 있습니다 — 예를 들어, 계산된 차이를 위한 별도의 축을 만들 수 있습니다.

"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 값에 따라 축이 자동 생성됩니다.

예시: 수직 영역을 사용한 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])를 차지합니다
두 시리즈가 절대 겹치지 않아 깔끔한 누적 레이아웃이 만들어집니다

예시: 도메인 클램프를 사용한 드로다운

드로다운을 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	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 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는 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축의 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가 어떤 상태였는지"를 뜻합니다. 백엔드가 기준 시점을 판단하지 못할 때에만 일수 번호 매기기(Day 0, Day 90 …)가 대체 표시로 다시 사용됩니다.

기준 유형

기준 이벤트별로 하나씩, 세 가지 사이클 지표 계열을 사용할 수 있습니다.

기준	지표 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축 범위). 사이클당 약 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" 차트와 일치합니다 — 다섯 개의 사이클이 각각 다른 색상으로 로그 축에 표시됩니다.

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 서버에는 AI 에이전트가 대화에서 직접 차트 이미지를 생성할 수 있게 하는 render_chart 도구가 포함되어 있습니다. 이 도구는 스냅샷 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축​

예시: 수직 영역을 사용한 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 차트

차트 템플릿

워터마크

캐싱