API de Snapshot

A API de Snapshot renderiza gráficos de análise on-chain como imagens PNG ou gráficos vetoriais SVG. Envie IDs de métricas e parâmetros de exibição opcionais e receba uma imagem de gráfico totalmente renderizada, pronta para incorporar em relatórios, dashboards ou conversas com IA. Atualmente suporta métricas de Bitcoin, com cobertura multi-chain (ETH, TON, TRON) em expansão.

Endpoints

Método	Caminho	Descrição
`GET`	`/v1/chart/snapshot`	Gráficos simples via parâmetros de query
`POST`	`/v1/chart/snapshot`	Personalização completa via corpo JSON

Ambos os endpoints retornam image/png por padrão. Mude para SVG (image/svg+xml) ou metadados JSON (application/json) definindo o cabeçalho de requisição Accept ou — no POST — o campo format do corpo ("png", "svg", "json").

Respostas PNG e SVG bem-sucedidas incluem um cabeçalho X-Render-Id para que o gráfico renderizado possa ser obtido novamente por URL dentro de 1 hora:

Saída	Em cache em
PNG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.png`
SVG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.svg`

Autenticação

Todas as requisições exigem uma chave de API através do cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Consulte Autenticação para detalhes sobre como obter chaves de API.

Acesso e Limites de Taxa

A API de Snapshot exige o tier Pro ou Enterprise. Chaves dos tiers Demo e Free recebem 403 Forbidden.

A API de Snapshot segue os mesmos limites de taxa da Data API. Consulte Limites de Taxa para detalhes.

Quando o limite de taxa é atingido, a API retorna 429 Too Many Requests com um campo retry_after.

O acesso às métricas também é restrito por grau (grade): as métricas de grau 0 (price, supply, MVRV) estão disponíveis para todas as chaves Pro+, as de grau 1 (SOPR, P&L) exigem Pro e as de grau 2 (heatmaps de CBD) exigem Enterprise.

GET `/v1/chart/snapshot`

Gere um gráfico a partir de parâmetros de query. Ideal para gráficos simples, de métrica única ou baseados em templates.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`metric`	string	-	ID de uma única métrica (ex.: `price`, `lth_supply`). Mutuamente exclusivo com `metrics` e `template`.
`metrics`	string	-	IDs de métricas separados por vírgula, máximo 6 (ex.: `lth_supply,sth_supply`). Mutuamente exclusivo com `metric` e `template`.
`template`	string	-	ID de template predefinido. Mutuamente exclusivo com `metric` e `metrics`.
`days`	integer	365	Dias de dados históricos (7-10000).
`start_date`	string	-	Data inicial (`YYYY-MM-DD`). Sobrepõe `days`.
`end_date`	string	-	Data final (`YYYY-MM-DD`). Padrão: hoje.
`style`	string	auto	Estilo do gráfico: `line`, `area`, `bar`. Detectado automaticamente a partir do registro de métricas se omitido.
`scale`	string	`linear`	Escala do eixo Y: `linear` ou `log`.
`overlay`	string	-	Adiciona uma sobreposição de preço como uma linha tracejada sutil no eixo direito (use `price`). Atualmente preço do BTC.
`width`	integer	1200	Largura da imagem em pixels (600-2400).
`height`	integer	600	Altura da imagem em pixels (300-1200).
`title`	string	auto	Título do gráfico. Gerado automaticamente a partir dos nomes das métricas se omitido.
`theme`	string	`light`	Tema de cores: `light` ou `dark`.

Exatamente um entre metric, metrics ou template deve ser fornecido.

Templates Disponíveis

Template	Métricas
`price`	Preço do BTC
`price_volume`	Preço + 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`	Altura do Bloco

Exemplos

# 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

Resposta de Sucesso

PNG (padrão):

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 (com 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>

O valor X-Render-Id pode ser usado para obter novamente a mesma imagem em /v1/chart/renders/{render_id}.png ou /v1/chart/renders/{render_id}.svg por até 1 hora.

POST `/v1/chart/snapshot`

Personalização completa do gráfico via corpo JSON. Suporta estilização por métrica, eixos personalizados, fórmulas, linhas de referência, áreas de referência e mais. Projetado para agentes de IA (via MCP) e usuários avançados.

Corpo da Requisição

Forneça exatamente uma fonte de dados (metric, metrics ou 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"}
  ]
}

Nota: Exatamente um entre metric, metrics ou template deve ser fornecido.

Campo Metrics

O campo metrics suporta tipos mistos:

// 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"}
]

Algumas métricas exigem parâmetros adicionais (ex.: exchange, ticker, id). Inclua o objeto params da definição da métrica ao usar essas métricas.

Opções por Métrica

Campo	Tipo	Descrição
`id`	string	Obrigatório. ID da métrica do registro.
`params`	object	Parâmetros para métricas parametrizadas (ex.: `{"exchange": "binance"}`). Consulte a definição da métrica para os params obrigatórios.
`axis`	`left` / `right`	Lado do eixo Y. Atribuído automaticamente se omitido.
`y_axis_id`	string	Vincula a um eixo Y específico por ID (ex.: `axis-diff`). Sobrepõe `axis`.
`style`	`line` / `area` / `bar`	Estilo do gráfico. Padrão do registro se omitido.
`color`	string	Cor hexadecimal (ex.: `#2563eb`). Atribuída automaticamente se omitida.
`label`	string	Rótulo de exibição. Usa o nome da métrica se omitido.
`stroke_width`	integer	Largura da linha (0-5). Padrão: 2. Use 0 para barras sem bordas.
`fill_opacity`	float	Opacidade de preenchimento (0.0-1.0). Para barras transparentes, use valores baixos como 0.2.
`stroke_dash`	string	Padrão de tracejado (ex.: `5 5`).
`stack_group`	string	ID do grupo de empilhamento para gráficos empilhados.
`show_in_legend`	boolean	Se deve aparecer na legenda do gráfico. Padrão: true.
`visible`	boolean	Mostrar/ocultar. Padrão: true.

Eixos Y Personalizados

O campo y_axes define os eixos Y disponíveis para métricas e fórmulas. Cada eixo tem um id único que pode ser referenciado via y_axis_id em métricas ou fórmulas. Você pode definir mais de dois eixos — por exemplo, um eixo separado para diferenças computadas:

"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"}
]

Campo	Tipo	Descrição
`id`	string	Identificador único do eixo. Referenciado por `y_axis_id` em métricas/fórmulas.
`side`	`left` / `right`	Em qual lado do gráfico o eixo aparece.
`scale`	`linear` / `log`	Escala do eixo. Padrão: `linear`.
`format`	`number` / `currency` / `percent`	Formato numérico para os rótulos do eixo.
`range`	`[number, number]`	Zona vertical como `[from%, to%]`. `0` = inferior, `100` = superior. Padrão: altura total. Use para empilhar eixos verticalmente (ex.: volume nos 20% inferiores, preço nos 80% superiores).
`domain_min`	number	Limite mínimo rígido do domínio. O eixo nunca ficará abaixo desse valor.
`domain_max`	number	Limite máximo rígido do domínio. O eixo nunca ficará acima desse valor.
`no_padding`	`"top"` / `"bottom"` / `"both"`	Remove o padding automático de 10% das bordas. Útil quando um limite de domínio é uma fronteira rígida (ex.: drawdown limitado a 0).

Se y_axes for omitido, os eixos são gerados automaticamente com base nos valores de axis das métricas.

Exemplo: Preço + Volume com Zonas Verticais

Empilhe barras de volume nos 20% inferiores e o preço no espaço restante:

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

O que isso produz:

As barras de volume preenchem os 20% inferiores do gráfico (range: [0, 20]) sem padding na borda inferior
O preço ocupa os 80% superiores (range: [20, 100]) em escala log
As duas séries nunca se sobrepõem, criando um layout empilhado limpo

Exemplo: Drawdown com Limite de Domínio

Limite o drawdown a 0 (borda superior) para que a linha toque o topo da sua zona:

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

O que isso produz:

O drawdown é sempre ≤ 0, então domain_max: 0 limita a borda superior
no_padding: "top" remove o padding automático de 10% acima de 0, fazendo a linha tocar o topo quando o drawdown é 0%
O preço está no eixo direito com escala log

Fórmulas

O campo formulas permite definir séries computadas derivadas de suas métricas. As fórmulas podem referenciar métricas pelo seu id (ex.: lth_supply) ou por índice posicional (m1, m2, etc. com base na ordem no array 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
  }
]

Funções suportadas (30 no total):

Médias Móveis e Estatísticas de Janela Móvel

Função	Sintaxe	Descrição
`sma`	`sma(series, period)`	Média Móvel Simples
`ema`	`ema(series, period)`	Média Móvel Exponencial
`median`	`median(series, period)`	Mediana móvel
`sum`	`sum(series, period)`	Soma móvel
`std`	`std(series, period)`	Desvio padrão móvel

Cumulativas

Função	Sintaxe	Descrição
`cumsum`	`cumsum(series)`	Soma cumulativa expansiva
`cummean`	`cummean(series)`	Média cumulativa expansiva
`cummedian`	`cummedian(series)`	Mediana cumulativa expansiva
`cumstd`	`cumstd(series)`	Desvio padrão cumulativo expansivo
`cummax`	`cummax(series)`	Máximo cumulativo de todos os tempos
`cummin`	`cummin(series)`	Mínimo cumulativo de todos os tempos

Variações

Função	Sintaxe	Descrição
`percent_change`	`percent_change(series, period)`	Variação percentual (decimal: 0.20 = +20%)
`diff`	`diff(series, period)`	Variação em valor absoluto

Matemática

Função	Sintaxe	Descrição
`abs`	`abs(series)`	Valor absoluto
`pow`	`pow(series, n)`	Elevar à potência n
`log`	`log(series)`	Logaritmo de base 10
`round`	`round(series, digits)`	Arredondar para N casas decimais
`max`	`max(a, b, ...)`	Máximo ponto a ponto
`min`	`min(a, b, ...)`	Mínimo ponto a ponto

Indicadores Técnicos

Função	Sintaxe	Descrição
`rsi`	`rsi(series, period)`	Índice de Força Relativa (0-100)
`corr`	`corr(s1, s2, period)`	Correlação de Pearson (-1 a 1)
`drawdown`	`drawdown(series)`	Drawdown a partir do ATH (decimal negativo)

Risco e Retorno

Função	Sintaxe	Descrição
`mean_return`	`mean_return(series, period)`	Retorno médio móvel anualizado
`realized_vol`	`realized_vol(series, period)`	Volatilidade realizada anualizada
`sharpe_ratio_arithmetic`	`sharpe_ratio_arithmetic(series, period)`	Índice de Sharpe (aritmético)
`sharpe_ratio_geometric`	`sharpe_ratio_geometric(series, period)`	Índice de Sharpe (geométrico)

Manipulação de Séries

Função	Sintaxe	Descrição
`shift`	`shift(series, period)`	Desloca a série por N períodos
`if`	`if(a, "op", b, then, else)`	Condicional (op: `=`, `!=`, `>`, `>=`, `<`, `<=`)

Operadores

Aritméticos: +, -, *, / Agrupamento: (, )

Referenciamento

Métricas por nome: lth_supply + sth_supply — use os IDs das métricas diretamente
Métricas por posição: m1 + m2 — referências posicionais (m1 = primeira métrica, m2 = segunda, etc.)
Outras fórmulas: f1 * 2 — referenciar fórmulas anteriores (f1 = primeira fórmula, etc.)
As fórmulas são avaliadas em ordem, então f2 pode referenciar f1, mas não o contrário.

Opções de fórmula:

Campo	Tipo	Descrição
`expression`	string	Obrigatório. Expressão de fórmula usando IDs de métricas ou refs posicionais (`m1`, `m2`).
`label`	string	Obrigatório. Rótulo de exibição para a legenda.
`color`	string	Cor hexadecimal. Atribuída automaticamente se omitida.
`style`	`line` / `area` / `bar`	Estilo do gráfico. Padrão: `line`.
`y_axis_id`	string	Vincula a um eixo Y específico por ID (ex.: `axis-diff`). Sobrepõe `axis`.
`axis`	`left` / `right`	Lado do eixo Y. Padrão: `left`. Ignorado se `y_axis_id` for definido.
`fill_opacity`	float	Opacidade de preenchimento (0.0-1.0). Para barras transparentes, use valores baixos como 0.2.
`stroke_width`	integer	Largura do traço (0-5). Use 0 para barras sem bordas.
`stroke_dash`	string	Padrão de tracejado (ex.: `6 3`).
`stack_group`	string	ID do grupo de empilhamento para empilhar várias séries de fórmula.

Linhas e Áreas de Referência

Linhas de referência adicionam linhas-guia horizontais para destacar valores específicos (ex.: break-even em 1.0, limiar de sobrecompra). Áreas de referência adicionam zonas sombreadas para destacar faixas de valores (ex.: zona de subvalorização, bandas tipo Bollinger). Ambas suportam valores estáticos e fórmulas dinâmicas usando o mesmo motor de fórmulas do campo formulas.

Opções de Linha de Referência

Campo	Tipo	Descrição
`y`	number	Valor Y estático.
`y_formula`	string	Expressão de fórmula para Y dinâmico (ex.: `"sma(m1, 200)"`). Usa o mesmo motor que `formulas`.
`y_axis_id`	string	ID do eixo Y (padrão: primeiro eixo esquerdo).
`stroke`	string	Cor hexadecimal da linha (padrão: `#9ca3af`).
`stroke_dasharray`	string	Padrão de tracejado, ex.: `"3 3"` para tracejado.
`label`	string	Texto do rótulo.

Forneça y (estático) ou y_formula (dinâmico), não ambos. Máximo de 10 linhas de referência por gráfico.

Opções de Área de Referência

Campo	Tipo	Descrição
`y1`	number	Limite Y inferior estático.
`y2`	number	Limite Y superior estático.
`y1_formula`	string	Fórmula para o limite inferior dinâmico.
`y2_formula`	string	Fórmula para o limite superior dinâmico.
`y_axis_id`	string	ID do eixo Y (padrão: primeiro eixo esquerdo).
`fill`	string	Cor hexadecimal de preenchimento (padrão: `#3b82f6`).
`fill_opacity`	number	Opacidade de preenchimento 0–1 (padrão: `0.1`).
`label`	string	Texto do rótulo.

Forneça limites estáticos (y1/y2) ou baseados em fórmula (y1_formula/y2_formula) — você pode misturá-los (ex.: y1 estático com y2_formula dinâmico). Máximo de 10 áreas de referência por gráfico.

Exemplo: MVRV com Zonas de Valor

Adicione uma zona verde de subvalorização (0–0.85), uma zona vermelha de sobrevalorização (8–100) e uma linha de break-even tracejada em 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

Exemplo: Banda Baseada em Fórmula

Crie uma banda tipo Bollinger ao redor da primeira fórmula (envelope de ±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

Formato de Saída

O campo format controla a saída:

Formato	Content-Type	Descrição
`png` (padrão)	`image/png`	Imagem de gráfico rasterizada
`svg`	`image/svg+xml`	Gráficos vetoriais (escaláveis, incorporáveis)
`json`	`application/json`	Metadados do gráfico (sem renderização)

Alternativamente, use o cabeçalho Accept:

Accept: image/png - PNG (padrão)
Accept: image/svg+xml - SVG
Accept: application/json - metadados JSON

Resposta de Metadados JSON

Quando format=json ou 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
}

Exemplos

# 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

Renderização de Heatmap

A API de Snapshot pode renderizar gráficos de heatmap para métricas baseadas em distribuição, como a Distribuição de Cost Basis. Os heatmaps usam um conjunto de parâmetros separado dos gráficos de métricas padrão.

Parâmetros de Heatmap

Parâmetro	Tipo	Padrão	Descrição
`heatmap_id`	string	-	Identificador do heatmap (ex.: `cost-basis-distribution`)
`heatmap_period`	string	`1y`	Período de tempo: `3m`, `6m`, `1y`, `2y`, `3y`, `5y`, `all`
`heatmap_color_scale`	string	`viridis`	Escala de cores: `viridis`, `plasma`, `inferno`, `magma`, `cividis`
`heatmap_y_scale`	string	`linear`	Escala do eixo Y: `linear` ou `log`
`theme`	string	`light`	Tema de cores: `light` ou `dark`
`title`	string	auto	Título do gráfico
`width`	integer	1200	Largura da imagem em pixels
`height`	integer	600	Altura da imagem em pixels

Exemplo

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

Nota: Os parâmetros de heatmap (heatmap_id, etc.) são mutuamente exclusivos com os parâmetros de métrica padrão (metric, metrics, template). As métricas de heatmap exigem o tier Enterprise.

A legenda da escala de cores é incluída na imagem renderizada, mostrando a faixa de valores mapeada para a paleta de cores selecionada.

Gráficos de Sobreposição de Desempenho de Ciclo

Os gráficos de desempenho de ciclo sobrepõem múltiplos ciclos do Bitcoin no mesmo eixo X para que você possa compará-los de forma equivalente. Em vez de plotar contra datas de calendário, o preço de cada ciclo é indexado ao seu próprio evento âncora (fundo do ciclo, ATH ou halving) e plotado contra dias desde essa âncora.

Ative o modo de sobreposição definindo x_axis: "day_offset" em uma requisição POST /v1/chart/snapshot e fornecendo métricas de ciclo no array metrics. O renderizador usa o campo day_offset em cada ponto de dados em vez de date, de modo que todos os ciclos começam no Dia 0 no eixo X.

Os rótulos de marcação mostram datas de calendário do ciclo mais recente da família escolhida. Por exemplo, uma sobreposição de ATH (cycle_ath_1…cycle_ath_5) ancora em 2025-10-06 e as marcações exibem Oct '25, Jan '26, Apr '26, etc. — não Day 0, Day 90, Day 180. Os outros ciclos no mesmo gráfico são alinhados às mesmas posições do eixo X, então um valor na marcação Apr '26 em cycle_ath_3 significa "o que o BTC estava fazendo no 182º dia do ciclo de 2017". A numeração por dias reaparece como fallback apenas se o backend não conseguir determinar a âncora.

Tipos de Âncora

Três famílias de métricas de ciclo estão disponíveis, uma por evento âncora:

Âncora	Prefixo do ID da Métrica	Descrição	Dica de endpoint
Fundo do ciclo → próximo fundo	`cycle_low_*`	Preço indexado ao fundo do ciclo — cada série começa em 1.0 na data do fundo e vai até o fundo do próximo ciclo.	`endpoint: "cycle-performance?type=low"`
ATH → ATH	`cycle_ath_*`	Preço indexado ao recorde histórico do ciclo — cada série começa em 1.0 na data do ATH e vai até o próximo ATH.	`endpoint: "cycle-performance?type=ath"`
Halving → halving	`cycle_halving_*`	Preço indexado ao bloco do halving — cada série começa em 1.0 na data do halving e vai até o próximo halving.	`endpoint: "cycle-performance?type=halving"`

Dentro de uma família de âncora, cada ciclo é o mesmo formato de dados — um índice que começa em 1.0 e acompanha price(t) / price(anchor) até o próximo evento âncora (ou, para o ciclo atual, até hoje). É isso que torna a comparação por sobreposição significativa: um valor de 5.0 no dia 200 de cycle_ath_3 significa "o BTC valia 5× o seu ATH de 2017, 200 dias após esse ATH".

Todas as Métricas de Ciclo Disponíveis

ID da Métrica	Data da âncora	Âncora → data final
`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 → hoje (ciclo atual)
`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 → hoje (ciclo atual)
`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 → hoje (ciclo atual)

Regras de validação

Todas as metrics devem vir da mesma família de âncora. Misturar cycle_ath_* com cycle_low_* (ou qualquer coisa fora de daily_cycle_performance) retorna 400 invalid_params.
A flag x_axis: "day_offset" é válida apenas para métricas de ciclo — combiná-la com qualquer outra métrica retorna 400 invalid_params.
Aplica-se o limite padrão de "máximo 6 métricas por gráfico" — escolha até 6 ciclos por sobreposição.

Parâmetros de Desempenho de Ciclo

Além de todos os parâmetros de gráfico padrão (days, width, height, theme, scale, format, title, y_axes, reference_lines, reference_areas, formulas, etc.), o modo de sobreposição de ciclo usa estes campos:

Campo	Tipo	Padrão	Descrição
`x_axis`	`"date"` / `"day_offset"`	`"date"`	Defina como `"day_offset"` para habilitar a sobreposição de ciclo. Caso contrário, o eixo X é por data de calendário.
`metrics`	array	obrigatório	1–6 IDs de métricas de ciclo da mesma família de âncora. Strings ou objetos (`{id, color, style, label, stroke_width, fill_opacity, show_in_legend, y_axis_id}`).
`days`	integer	365	Limita o deslocamento máximo de dias renderizado (faixa do eixo X, não dias de calendário). Defina como `1500` para ver ~4 anos por ciclo.
`scale`	`"linear"` / `"log"`	`"linear"`	A escala log é quase sempre o que você quer — os multiplicadores dos primeiros ciclos podem ser de 100×–500×, o que é ilegível em escala linear.
`theme`	`"light"` / `"dark"`	`"light"`	O tema escuro é o padrão do dashboard para esses gráficos.

As linhas de referência (reference_lines) são particularmente úteis em gráficos de sobreposição — ex.: uma linha horizontal em y: 1.0 marca o nível da âncora, y: 2.0 marca "2× a âncora" e assim por diante.

Exemplo: Sobreposição Ancorada no ATH (Cores Personalizadas por Ciclo)

Esta receita corresponde ao gráfico "Price Performance Since ATH" do dashboard — cinco ciclos, cada um em uma cor distinta, em um eixo log.

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

Exemplo: Sobreposição de Fundo de Ciclo (Forma Abreviada)

Para uma comparação rápida sem estilização por ciclo, passe os IDs das métricas como strings simples — as cores vêm automaticamente da paleta do registro.

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

Exemplo: Sobreposição Ancorada no Halving

Mesmo formato, quatro ciclos ancorados em cada evento de halving.

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

Equivalente em Ferramenta MCP

A partir de um agente de IA conectado ao servidor MCP, o mesmo gráfico é uma única chamada de ferramenta:

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"
})

O servidor MCP aceita o mesmo enum x_axis, os mesmos IDs de métricas e as mesmas regras de validação que a API HTTP.

Controle de Legenda por Métrica

Use show_in_legend em objetos de configuração de métrica individuais para controlar se uma métrica aparece na legenda do gráfico. Isso é útil ao combinar muitas séries onde algumas são linhas de contexto/fundo.

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

Campo	Tipo	Padrão	Descrição
`show_in_legend`	boolean	`true`	Se a métrica aparece na legenda do gráfico

Padrões Inteligentes

A API de Snapshot usa padrões inteligentes para que você consiga gráficos com ótima aparência com configuração mínima:

Parâmetro	Como o Padrão É Determinado
Estilo do gráfico	A partir do registro de métricas (`chart_types[0]`)
Cor	A partir do registro de métricas, depois rotação de paleta
Lado do eixo Y	Primeira métrica à esquerda; métricas de mesmo formato compartilham o eixo; formato diferente à direita
Escala do eixo Y	`linear` (sobreponha com `scale=log`)
Faixa de tempo	Baseada em categoria: 365 dias para price/valuation/profit, 730 para supply, 180 para blockchain
Título	Métrica única: nome da métrica. Múltiplas: "Name1 vs Name2"
Tamanho da imagem	1200 x 600 pixels
Tema	`light`

Respostas de Erro

Todos os erros retornam 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."}

Ferramenta MCP: `render_chart`

O servidor MCP do Blocklens inclui uma ferramenta render_chart que permite a agentes de IA gerar imagens de gráficos diretamente nas conversas. A ferramenta chama a API de Snapshot e retorna a imagem inline como PNG (raster) ou SVG (vetorial).

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`metric`	string	-	ID de uma única métrica
`metrics`	array	-	Múltiplas métricas (strings ou objetos)
`template`	string	-	ID do template
`days`	integer	365	Dias de histórico
`start_date`	string	-	Data inicial (YYYY-MM-DD)
`end_date`	string	-	Data final (YYYY-MM-DD)
`overlay`	`price`	-	Adiciona sobreposição de preço (atualmente BTC)
`theme`	`light` / `dark`	`light`	Tema de cores
`width`	integer	1200	Largura da imagem
`height`	integer	600	Altura da imagem
`title`	string	auto	Título do gráfico
`style`	`line` / `area` / `bar`	auto	Estilo do gráfico
`scale`	`linear` / `log`	`linear`	Escala do eixo Y
`format`	`png` / `svg` / `json`	`png`	Formato de saída: `png` (imagem raster), `svg` (imagem vetorial, escala sem perda de qualidade) ou `json` (apenas metadados — sem renderização)
`y_axes`	array	-	Eixos Y personalizados com zonas (consulte Eixos Y Personalizados)
`x_axis`	`date` / `day_offset`	`date`	Modo do eixo X. Use `day_offset` para sobreposições de desempenho de ciclo — todas as `metrics` devem ser da mesma família de ciclo.
`heatmap_id`	`cost-basis-distribution`	-	Renderiza um heatmap em vez de um gráfico de linha (consulte Renderização de Heatmap). Mutuamente exclusivo com `metric` / `metrics` / `template`.
`heatmap_period`	`3m` / `6m` / `1y` / `2y` / `3y` / `5y` / `all`	`1y`	Janela de agrupamento do heatmap.
`heatmap_color_scale`	`viridis` / `plasma` / `inferno` / `magma` / `cividis`	`viridis`	Paleta de cores do heatmap.
`heatmap_y_scale`	`linear` / `log`	`linear`	Escala do eixo Y de faixas de preço do heatmap.
`params`	object	-	Parâmetros por chamada para métricas parametrizadas (ex.: `{ "exchange": "binance" }`, `{ "ticker": "IBIT" }`, `{ "entity": "tesla" }`).
`reference_lines`	array	-	Linhas de referência horizontais (consulte Linhas e Áreas de Referência)
`reference_areas`	array	-	Zonas de referência sombreadas (consulte Linhas e Áreas de Referência)

Exemplos de Uso

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

Configuração do MCP

Adicione à sua configuração do Claude Desktop ou Cursor para habilitar a renderização de gráficos:

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

Consulte Servidor MCP para instruções completas de configuração.

Exemplo Avançado: Gráfico de LTH Supply

Este exemplo replica o gráfico completo de Long-Term Holder Supply do dashboard do Blocklens — duas métricas, duas séries de fórmula computadas e três eixos 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

O que isso produz:

BTC Price — linha cinza no eixo direito (escala log)
LTH Supply — linha azul no eixo esquerdo (linear)
Acumulação positiva de 30 dias — barras verdes semitransparentes em um eixo axis-diff separado
Distribuição de 30 dias — barras vermelhas semitransparentes no mesmo eixo axis-diff

Técnicas-chave utilizadas:

shift(lth_supply, 30) calcula o valor retrospectivo de 30 dias
max(..., 0) e min(0, ...) separam variações positivas e negativas em séries distintas
y_axis_id: "axis-diff" vincula ambas as barras de fórmula a um eixo dedicado, independente dos eixos das métricas principais
fill_opacity: 0.2 + stroke_width: 0 cria barras transparentes sutis e sem bordas

Templates de Gráfico

Configurações completas de gráficos (incluindo métricas, fórmulas, eixos e estilização) estão disponíveis como templates apoiados por banco de dados via:

GET /api/lab/templates

Esses templates podem servir de referência para construir seus próprios corpos de requisição POST. Cada template contém a configuração completa que produz um gráfico específico no dashboard do Blocklens.

Marca d'água

Todas as imagens de gráficos renderizadas incluem uma marca d'água blocklens.co e um aviso de copyright. Isso se aplica tanto ao formato de saída PNG quanto SVG.

Cache

Os snapshots renderizados ficam em cache por 1 hora no Redis. Comportamento do cache:

Configurações de gráfico idênticas retornam resultados em cache instantaneamente
A chave de cache é derivada da configuração completa do gráfico (métricas, eixos, faixa de tempo, tema, tamanho) mais o formato de saída — as variantes PNG e SVG do mesmo gráfico são armazenadas em cache de forma independente
O cabeçalho de resposta X-Snapshot-Cache indica HIT ou MISS
O cabeçalho X-Snapshot-Render-Ms mostra o tempo de renderização (0 para acertos de cache)
Os arquivos renderizados também são persistidos em disco em /v1/chart/renders/{render_id}.png e /v1/chart/renders/{render_id}.svg por 1 hora, de modo que as URLs de gráfico retornadas no cabeçalho X-Render-Id permaneçam acessíveis
Os gráficos populares são pré-aquecidos após cada atualização diária de dados (05:00 UTC)

Endpoints​

Autenticação​

Acesso e Limites de Taxa​

GET /v1/chart/snapshot​

Parâmetros​

Templates Disponíveis​

Exemplos​

Resposta de Sucesso​

POST /v1/chart/snapshot​

Corpo da Requisição​

Campo Metrics​

Opções por Métrica​

Eixos Y Personalizados​

Exemplo: Preço + Volume com Zonas Verticais​

Exemplo: Drawdown com Limite de Domínio​

Fórmulas​

Médias Móveis e Estatísticas de Janela Móvel​

Cumulativas​

Variações​

Matemática​

Indicadores Técnicos​

Risco e Retorno​

Manipulação de Séries​

Operadores​

Referenciamento​

Linhas e Áreas de Referência​

Opções de Linha de Referência​

Opções de Área de Referência​

Exemplo: MVRV com Zonas de Valor​

Exemplo: Banda Baseada em Fórmula​

Formato de Saída​

Resposta de Metadados JSON​

Exemplos​

Renderização de Heatmap​

Parâmetros de Heatmap​

Exemplo​

Gráficos de Sobreposição de Desempenho de Ciclo​

Tipos de Âncora​

Todas as Métricas de Ciclo Disponíveis​

Parâmetros de Desempenho de Ciclo​

Exemplo: Sobreposição Ancorada no ATH (Cores Personalizadas por Ciclo)​

Exemplo: Sobreposição de Fundo de Ciclo (Forma Abreviada)​

Exemplo: Sobreposição Ancorada no Halving​

Equivalente em Ferramenta MCP​

Controle de Legenda por Métrica​

Padrões Inteligentes​

Respostas de Erro​

Ferramenta MCP: render_chart​

Parâmetros​

Exemplos de Uso​

Configuração do MCP​

Exemplo Avançado: Gráfico de LTH Supply​

Templates de Gráfico​

Marca d'água​

Cache​

Endpoints

Autenticação

Acesso e Limites de Taxa

GET `/v1/chart/snapshot`

Parâmetros

Templates Disponíveis

Exemplos

Resposta de Sucesso

POST `/v1/chart/snapshot`

Corpo da Requisição

Campo Metrics

Opções por Métrica

Eixos Y Personalizados

Exemplo: Preço + Volume com Zonas Verticais

Exemplo: Drawdown com Limite de Domínio

Fórmulas

Médias Móveis e Estatísticas de Janela Móvel

Cumulativas

Variações

Matemática

Indicadores Técnicos

Risco e Retorno

Manipulação de Séries

Operadores

Referenciamento

Linhas e Áreas de Referência

Opções de Linha de Referência

Opções de Área de Referência

Exemplo: MVRV com Zonas de Valor

Exemplo: Banda Baseada em Fórmula

Formato de Saída

Resposta de Metadados JSON

Exemplos

Renderização de Heatmap

Parâmetros de Heatmap

Exemplo

Gráficos de Sobreposição de Desempenho de Ciclo

Tipos de Âncora

Todas as Métricas de Ciclo Disponíveis

Parâmetros de Desempenho de Ciclo

Exemplo: Sobreposição Ancorada no ATH (Cores Personalizadas por Ciclo)

Exemplo: Sobreposição de Fundo de Ciclo (Forma Abreviada)

Exemplo: Sobreposição Ancorada no Halving

Equivalente em Ferramenta MCP

Controle de Legenda por Métrica

Padrões Inteligentes

Respostas de Erro

Ferramenta MCP: `render_chart`

Parâmetros

Exemplos de Uso

Configuração do MCP

Exemplo Avançado: Gráfico de LTH Supply

Templates de Gráfico

Marca d'água

Cache