Snapshot API

La Snapshot API genera grafici di analisi on-chain come immagini PNG o grafica vettoriale SVG. Invia gli ID delle metriche e i parametri di visualizzazione opzionali e ricevi un'immagine di grafico completamente renderizzata, pronta per essere incorporata in report, dashboard o conversazioni con l'IA. Attualmente supporta le metriche Bitcoin, con una copertura multi-chain (ETH, TON, TRON) in espansione.

Endpoint

Metodo	Percorso	Descrizione
`GET`	`/v1/chart/snapshot`	Grafici semplici tramite parametri di query
`POST`	`/v1/chart/snapshot`	Personalizzazione completa tramite corpo JSON

Entrambi gli endpoint restituiscono image/png per impostazione predefinita. Passa a SVG (image/svg+xml) o a metadati JSON (application/json) impostando l'header di richiesta Accept oppure — su POST — il campo format del corpo ("png", "svg", "json").

Le risposte PNG e SVG riuscite includono un header X-Render-Id così da poter recuperare nuovamente il grafico renderizzato tramite URL entro 1 ora:

Output	In cache su
PNG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.png`
SVG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.svg`

Autenticazione

Tutte le richieste richiedono una chiave API tramite l'header Authorization:

Authorization: Bearer YOUR_API_KEY

Consulta Autenticazione per i dettagli su come ottenere le chiavi API.

Accesso e limiti di frequenza

La Snapshot API richiede il piano Pro o Enterprise. Le chiavi dei piani Demo e Free ricevono 403 Forbidden.

La Snapshot API segue gli stessi limiti di frequenza della Data API. Consulta Limiti di frequenza per i dettagli.

In caso di limitazione della frequenza, l'API restituisce 429 Too Many Requests con un campo retry_after.

L'accesso alle metriche è inoltre regolato per livello (grade): le metriche di grade 0 (price, supply, MVRV) sono disponibili per tutte le chiavi Pro+, le metriche di grade 1 (SOPR, P&L) richiedono il piano Pro e le metriche di grade 2 (heatmap CBD) richiedono il piano Enterprise.

GET `/v1/chart/snapshot`

Genera un grafico a partire dai parametri di query. Ideale per grafici semplici, a metrica singola o basati su template.

Parametri

Parametro	Tipo	Predefinito	Descrizione
`metric`	string	-	ID di una singola metrica (es. `price`, `lth_supply`). Mutuamente esclusivo con `metrics` e `template`.
`metrics`	string	-	ID di metriche separati da virgola, max 6 (es. `lth_supply,sth_supply`). Mutuamente esclusivo con `metric` e `template`.
`template`	string	-	ID di un template predefinito. Mutuamente esclusivo con `metric` e `metrics`.
`days`	integer	365	Giorni di dati storici (7-10000).
`start_date`	string	-	Data di inizio (`YYYY-MM-DD`). Ha la precedenza su `days`.
`end_date`	string	-	Data di fine (`YYYY-MM-DD`). Predefinita a oggi.
`style`	string	auto	Stile del grafico: `line`, `area`, `bar`. Rilevato automaticamente dal registro delle metriche se omesso.
`scale`	string	`linear`	Scala dell'asse Y: `linear` o `log`.
`overlay`	string	-	Aggiunge una sovrapposizione del prezzo come sottile linea tratteggiata sull'asse destro (usa `price`). Attualmente il prezzo BTC.
`width`	integer	1200	Larghezza dell'immagine in pixel (600-2400).
`height`	integer	600	Altezza dell'immagine in pixel (300-1200).
`title`	string	auto	Titolo del grafico. Generato automaticamente dai nomi delle metriche se omesso.
`theme`	string	`light`	Tema dei colori: `light` o `dark`.

Deve essere fornito esattamente uno tra metric, metrics o template.

Template disponibili

Template	Metriche
`price`	Prezzo BTC
`price_volume`	Prezzo + 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`	Altezza del blocco

Esempi

# Esempio Bitcoin: prezzo BTC, 1 anno, grafico a linee
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" \
  --output price.png

# Esempio Bitcoin: due metriche con stile area
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 con tema scuro
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?template=mvrv_ratio&theme=dark" \
  --output mvrv_dark.png

# Scala logaritmica con sovrapposizione del prezzo
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

# Ottieni metadati JSON invece dell'immagine
curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" | jq

# Ottieni SVG invece di PNG
curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: image/svg+xml" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" \
  --output price.svg

Risposta in caso di successo

PNG (predefinito):

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

Il valore X-Render-Id può essere usato per recuperare nuovamente la stessa immagine su /v1/chart/renders/{render_id}.png o /v1/chart/renders/{render_id}.svg per un massimo di 1 ora.

POST `/v1/chart/snapshot`

Personalizzazione completa del grafico tramite corpo JSON. Supporta lo stile per singola metrica, assi personalizzati, formule, linee di riferimento, aree di riferimento e altro ancora. Progettato per gli agenti IA (tramite MCP) e per gli utenti avanzati.

Corpo della richiesta

Fornisci esattamente una fonte di dati (metric, metrics o 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: deve essere fornito esattamente uno tra metric, metrics o template.

Campo metrics

Il campo metrics supporta tipi misti:

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

Alcune metriche richiedono parametri aggiuntivi (es. exchange, ticker, id). Includi l'oggetto params dalla definizione della metrica quando usi queste metriche.

Opzioni per singola metrica

Campo	Tipo	Descrizione
`id`	string	Obbligatorio. ID della metrica dal registro.
`params`	object	Parametri per le metriche parametrizzate (es. `{"exchange": "binance"}`). Consulta la definizione della metrica per i parametri richiesti.
`axis`	`left` / `right`	Lato dell'asse Y. Assegnato automaticamente se omesso.
`y_axis_id`	string	Vincola a un asse Y specifico tramite ID (es. `axis-diff`). Ha la precedenza su `axis`.
`style`	`line` / `area` / `bar`	Stile del grafico. Predefinito del registro se omesso.
`color`	string	Colore esadecimale (es. `#2563eb`). Assegnato automaticamente se omesso.
`label`	string	Etichetta di visualizzazione. Usa il nome della metrica se omessa.
`stroke_width`	integer	Spessore della linea (0-5). Predefinito: 2. Usa 0 per barre senza bordi.
`fill_opacity`	float	Opacità del riempimento (0.0-1.0). Per barre trasparenti, usa valori bassi come 0.2.
`stroke_dash`	string	Pattern del tratteggio (es. `5 5`).
`stack_group`	string	ID del gruppo di impilamento per grafici impilati.
`show_in_legend`	boolean	Se mostrare nella legenda del grafico. Predefinito: true.
`visible`	boolean	Mostra/nasconde. Predefinito: true.

Assi Y personalizzati

Il campo y_axes definisce gli assi Y disponibili per metriche e formule. Ogni asse ha un id univoco che può essere referenziato tramite y_axis_id su metriche o formule. Puoi definire più di due assi — per esempio, un asse separato per le differenze calcolate:

"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	Descrizione
`id`	string	Identificatore univoco dell'asse. Referenziato da `y_axis_id` su metriche/formule.
`side`	`left` / `right`	Su quale lato del grafico appare l'asse.
`scale`	`linear` / `log`	Scala dell'asse. Predefinito: `linear`.
`format`	`number` / `currency` / `percent`	Formato numerico per le etichette dell'asse.
`range`	`[number, number]`	Zona verticale come `[from%, to%]`. `0` = in basso, `100` = in alto. Predefinito: altezza piena. Usalo per impilare gli assi verticalmente (es. volume nel 20% inferiore, prezzo nell'80% superiore).
`domain_min`	number	Vincolo rigido del dominio minimo. L'asse non scenderà mai sotto questo valore.
`domain_max`	number	Vincolo rigido del dominio massimo. L'asse non salirà mai sopra questo valore.
`no_padding`	`"top"` / `"bottom"` / `"both"`	Rimuove il padding automatico del 10% dai bordi. Utile quando un vincolo di dominio è un limite rigido (es. drawdown bloccato a 0).

Se y_axes è omesso, gli assi vengono generati automaticamente in base ai valori axis delle metriche.

Esempio: Prezzo + Volume con zone verticali

Impila le barre del volume nel 20% inferiore e il prezzo nello spazio rimanente:

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

Cosa produce:

Le barre del volume riempiono il 20% inferiore del grafico (range: [0, 20]) senza padding sul bordo inferiore
Il prezzo occupa l'80% superiore (range: [20, 100]) su scala logaritmica
Le due serie non si sovrappongono mai, creando un layout impilato e pulito

Esempio: Drawdown con vincolo di dominio

Blocca il drawdown a 0 (bordo superiore) così che la linea tocchi la parte alta della 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

Cosa produce:

Il drawdown è sempre ≤ 0, quindi domain_max: 0 blocca il bordo superiore
no_padding: "top" rimuove il padding automatico del 10% sopra lo 0, facendo sì che la linea tocchi il bordo superiore quando il drawdown è 0%
Il prezzo è sull'asse destro con scala logaritmica

Formule

Il campo formulas ti permette di definire serie calcolate derivate dalle tue metriche. Le formule possono referenziare le metriche tramite il loro id (es. lth_supply) o tramite indice posizionale (m1, m2, ecc., in base all'ordine nell'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
  }
]

Funzioni supportate (30 in totale):

Medie mobili e statistiche rolling

Funzione	Sintassi	Descrizione
`sma`	`sma(series, period)`	Media mobile semplice
`ema`	`ema(series, period)`	Media mobile esponenziale
`median`	`median(series, period)`	Mediana rolling
`sum`	`sum(series, period)`	Somma rolling
`std`	`std(series, period)`	Deviazione standard rolling

Cumulative

Funzione	Sintassi	Descrizione
`cumsum`	`cumsum(series)`	Somma cumulativa espansiva
`cummean`	`cummean(series)`	Media cumulativa espansiva
`cummedian`	`cummedian(series)`	Mediana cumulativa espansiva
`cumstd`	`cumstd(series)`	Deviazione standard cumulativa espansiva
`cummax`	`cummax(series)`	Massimo cumulativo di sempre
`cummin`	`cummin(series)`	Minimo cumulativo di sempre

Variazioni

Funzione	Sintassi	Descrizione
`percent_change`	`percent_change(series, period)`	Variazione percentuale (decimale: 0.20 = +20%)
`diff`	`diff(series, period)`	Variazione in valore assoluto

Matematica

Funzione	Sintassi	Descrizione
`abs`	`abs(series)`	Valore assoluto
`pow`	`pow(series, n)`	Elevazione a potenza n
`log`	`log(series)`	Logaritmo in base 10
`round`	`round(series, digits)`	Arrotondamento a N cifre decimali
`max`	`max(a, b, ...)`	Massimo puntuale
`min`	`min(a, b, ...)`	Minimo puntuale

Indicatori tecnici

Funzione	Sintassi	Descrizione
`rsi`	`rsi(series, period)`	Relative Strength Index (0-100)
`corr`	`corr(s1, s2, period)`	Correlazione di Pearson (da -1 a 1)
`drawdown`	`drawdown(series)`	Drawdown dall'ATH (decimale negativo)

Rischio e rendimento

Funzione	Sintassi	Descrizione
`mean_return`	`mean_return(series, period)`	Rendimento medio rolling annualizzato
`realized_vol`	`realized_vol(series, period)`	Volatilità realizzata annualizzata
`sharpe_ratio_arithmetic`	`sharpe_ratio_arithmetic(series, period)`	Sharpe ratio (aritmetico)
`sharpe_ratio_geometric`	`sharpe_ratio_geometric(series, period)`	Sharpe ratio (geometrico)

Manipolazione delle serie

Funzione	Sintassi	Descrizione
`shift`	`shift(series, period)`	Sposta la serie di N periodi
`if`	`if(a, "op", b, then, else)`	Condizionale (op: `=`, `!=`, `>`, `>=`, `<`, `<=`)

Operatori

Aritmetici: +, -, *, / Raggruppamento: (, )

Riferimenti

Metriche per nome: lth_supply + sth_supply — usa direttamente gli ID delle metriche
Metriche per posizione: m1 + m2 — riferimenti posizionali (m1 = prima metrica, m2 = seconda, ecc.)
Altre formule: f1 * 2 — referenzia formule precedenti (f1 = prima formula, ecc.)
Le formule vengono valutate in ordine, quindi f2 può referenziare f1, ma non viceversa.

Opzioni delle formule:

Campo	Tipo	Descrizione
`expression`	string	Obbligatorio. Espressione della formula con ID di metriche o riferimenti posizionali (`m1`, `m2`).
`label`	string	Obbligatorio. Etichetta di visualizzazione per la legenda.
`color`	string	Colore esadecimale. Assegnato automaticamente se omesso.
`style`	`line` / `area` / `bar`	Stile del grafico. Predefinito: `line`.
`y_axis_id`	string	Vincola a un asse Y specifico tramite ID (es. `axis-diff`). Ha la precedenza su `axis`.
`axis`	`left` / `right`	Lato dell'asse Y. Predefinito: `left`. Ignorato se `y_axis_id` è impostato.
`fill_opacity`	float	Opacità del riempimento (0.0-1.0). Per barre trasparenti, usa valori bassi come 0.2.
`stroke_width`	integer	Spessore del tratto (0-5). Usa 0 per barre senza bordi.
`stroke_dash`	string	Pattern del tratteggio (es. `6 3`).
`stack_group`	string	ID del gruppo di impilamento per impilare più serie di formule.

Linee e aree di riferimento

Le linee di riferimento aggiungono linee guida orizzontali per evidenziare valori specifici (es. break-even a 1.0, soglia di ipercomprato). Le aree di riferimento aggiungono zone ombreggiate per evidenziare intervalli di valori (es. zona di sottovalutazione, bande simili alle Bollinger). Entrambe supportano valori statici e formule dinamiche utilizzando lo stesso motore di formule del campo formulas.

Opzioni delle linee di riferimento

Campo	Tipo	Descrizione
`y`	number	Valore Y statico.
`y_formula`	string	Espressione di formula per un Y dinamico (es. `"sma(m1, 200)"`). Usa lo stesso motore di `formulas`.
`y_axis_id`	string	ID dell'asse Y (predefinito al primo asse sinistro).
`stroke`	string	Colore esadecimale della linea (predefinito: `#9ca3af`).
`stroke_dasharray`	string	Pattern del tratteggio, es. `"3 3"` per tratteggiato.
`label`	string	Testo dell'etichetta.

Fornisci y (statico) oppure y_formula (dinamico), non entrambi. Massimo 10 linee di riferimento per grafico.

Opzioni delle aree di riferimento

Campo	Tipo	Descrizione
`y1`	number	Limite Y inferiore statico.
`y2`	number	Limite Y superiore statico.
`y1_formula`	string	Formula per il limite inferiore dinamico.
`y2_formula`	string	Formula per il limite superiore dinamico.
`y_axis_id`	string	ID dell'asse Y (predefinito al primo asse sinistro).
`fill`	string	Colore esadecimale del riempimento (predefinito: `#3b82f6`).
`fill_opacity`	number	Opacità del riempimento 0–1 (predefinito: `0.1`).
`label`	string	Testo dell'etichetta.

Fornisci limiti statici (y1/y2) o basati su formula (y1_formula/y2_formula) — puoi mescolarli (es. y1 statico con y2_formula dinamico). Massimo 10 aree di riferimento per grafico.

Esempio: MVRV con zone di valore

Aggiungi una zona verde di sottovalutazione (0–0.85), una zona rossa di sopravvalutazione (8–100) e una linea di break-even tratteggiata a 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

Esempio: Banda basata su formula

Crea una banda simile alle Bollinger attorno alla prima formula (envelope ±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 di output

Il campo format controlla l'output:

Formato	Content-Type	Descrizione
`png` (predefinito)	`image/png`	Immagine del grafico rasterizzata
`svg`	`image/svg+xml`	Grafica vettoriale (scalabile, incorporabile)
`json`	`application/json`	Metadati del grafico (nessun rendering)

In alternativa, usa l'header Accept:

Accept: image/png - PNG (predefinito)
Accept: image/svg+xml - SVG
Accept: application/json - Metadati JSON

Risposta con metadati JSON

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

Esempi

# POST con singola metrica
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-metrica con stile personalizzato
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

# Output 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

# Metadati 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

Rendering delle heatmap

La Snapshot API può renderizzare grafici heatmap per metriche basate sulla distribuzione, come la Cost Basis Distribution. Le heatmap usano un set di parametri separato rispetto ai grafici delle metriche standard.

Parametri delle heatmap

Parametro	Tipo	Predefinito	Descrizione
`heatmap_id`	string	-	Identificatore della heatmap (es. `cost-basis-distribution`)
`heatmap_period`	string	`1y`	Periodo di tempo: `3m`, `6m`, `1y`, `2y`, `3y`, `5y`, `all`
`heatmap_color_scale`	string	`viridis`	Scala dei colori: `viridis`, `plasma`, `inferno`, `magma`, `cividis`
`heatmap_y_scale`	string	`linear`	Scala dell'asse Y: `linear` o `log`
`theme`	string	`light`	Tema dei colori: `light` o `dark`
`title`	string	auto	Titolo del grafico
`width`	integer	1200	Larghezza dell'immagine in pixel
`height`	integer	600	Altezza dell'immagine in pixel

Esempio

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: i parametri delle heatmap (heatmap_id, ecc.) sono mutuamente esclusivi con i parametri delle metriche standard (metric, metrics, template). Le metriche heatmap richiedono il piano Enterprise.

La legenda della scala dei colori è inclusa nell'immagine renderizzata e mostra l'intervallo di valori mappato sulla palette di colori selezionata.

Grafici di sovrapposizione delle performance di ciclo

I grafici delle performance di ciclo sovrappongono più cicli di Bitcoin sullo stesso asse X così da poterli confrontare in modo omogeneo. Invece di tracciare in base alle date di calendario, il prezzo di ogni ciclo è indicizzato al proprio evento di ancoraggio (minimo di ciclo, ATH o halving) e tracciato in base ai giorni trascorsi da quell'ancoraggio.

Attiva la modalità di sovrapposizione impostando x_axis: "day_offset" su una richiesta POST /v1/chart/snapshot e fornendo le metriche di ciclo nell'array metrics. Il renderer usa il campo day_offset su ogni punto dati invece di date, così tutti i cicli partono dal Giorno 0 sull'asse X.

Le etichette dei tick mostrano le date di calendario dell'ultimo ciclo della famiglia scelta. Per esempio, una sovrapposizione ATH (cycle_ath_1…cycle_ath_5) si ancora al 2025-10-06 e i tick riportano Oct '25, Jan '26, Apr '26, ecc. — non Day 0, Day 90, Day 180. Gli altri cicli nello stesso grafico sono allineati alle stesse posizioni dell'asse X, quindi un valore al tick Apr '26 su cycle_ath_3 significa "cosa stava facendo BTC 182 giorni dopo l'inizio del ciclo del 2017". La numerazione dei giorni riappare come fallback solo se il backend non riesce a determinare l'ancoraggio.

Tipi di ancoraggio

Sono disponibili tre famiglie di metriche di ciclo, una per ciascun evento di ancoraggio:

Ancoraggio	Prefisso ID metrica	Descrizione	Suggerimento endpoint
Minimo di ciclo → minimo successivo	`cycle_low_*`	Prezzo indicizzato al minimo del ciclo — ogni serie parte da 1.0 alla data del minimo e prosegue fino al minimo del ciclo successivo.	`endpoint: "cycle-performance?type=low"`
ATH → ATH	`cycle_ath_*`	Prezzo indicizzato al massimo storico del ciclo — ogni serie parte da 1.0 alla data dell'ATH e prosegue fino all'ATH successivo.	`endpoint: "cycle-performance?type=ath"`
Halving → halving	`cycle_halving_*`	Prezzo indicizzato al blocco dell'halving — ogni serie parte da 1.0 alla data dell'halving e prosegue fino all'halving successivo.	`endpoint: "cycle-performance?type=halving"`

All'interno di una famiglia di ancoraggio ogni ciclo è la stessa forma di dati — un indice che parte da 1.0 e traccia price(t) / price(anchor) fino all'evento di ancoraggio successivo (o, per il ciclo attuale, fino a oggi). È questo che rende significativo il confronto per sovrapposizione: un valore di 5.0 al giorno 200 di cycle_ath_3 significa "BTC valeva 5× il suo ATH del 2017, 200 giorni dopo quell'ATH".

Tutte le metriche di ciclo disponibili

ID metrica	Data di ancoraggio	Ancoraggio → data di fine
`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 → oggi (ciclo attuale)
`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 → oggi (ciclo attuale)
`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 → oggi (ciclo attuale)

Regole di validazione

Tutte le metrics devono provenire dalla stessa famiglia di ancoraggio. Mescolare cycle_ath_* con cycle_low_* (o qualsiasi cosa al di fuori di daily_cycle_performance) restituisce 400 invalid_params.
Il flag x_axis: "day_offset" è valido solo per le metriche di ciclo — abbinarlo a qualsiasi altra metrica restituisce 400 invalid_params.
Si applica il limite standard di "massimo 6 metriche per grafico" — scegli fino a 6 cicli per sovrapposizione.

Parametri delle performance di ciclo

Oltre a tutti i parametri standard del grafico (days, width, height, theme, scale, format, title, y_axes, reference_lines, reference_areas, formulas, ecc.), la modalità di sovrapposizione dei cicli usa questi campi:

Campo	Tipo	Predefinito	Descrizione
`x_axis`	`"date"` / `"day_offset"`	`"date"`	Imposta a `"day_offset"` per abilitare la sovrapposizione dei cicli. Altrimenti l'asse X è basato sulla data di calendario.
`metrics`	array	obbligatorio	Da 1 a 6 ID di metriche di ciclo della stessa famiglia di ancoraggio. Stringhe o oggetti (`{id, color, style, label, stroke_width, fill_opacity, show_in_legend, y_axis_id}`).
`days`	integer	365	Limita l'offset massimo di giorni renderizzato (intervallo dell'asse X, non giorni di calendario). Imposta a `1500` per vedere ~4 anni per ciclo.
`scale`	`"linear"` / `"log"`	`"linear"`	La scala logaritmica è quasi sempre la scelta giusta — i moltiplicatori dei primi cicli possono arrivare a 100×–500×, illeggibili su scala lineare.
`theme`	`"light"` / `"dark"`	`"light"`	Il tema scuro è quello predefinito della dashboard per questi grafici.

Le linee di riferimento (reference_lines) sono particolarmente utili sui grafici di sovrapposizione — es. una linea orizzontale a y: 1.0 segna il livello di ancoraggio, y: 2.0 segna "2× l'ancoraggio", e così via.

Esempio: Sovrapposizione ancorata all'ATH (colori personalizzati per ciclo)

Questo esempio riproduce il grafico "Price Performance Since ATH" della dashboard — cinque cicli, ciascuno in un colore distinto, su un asse logaritmico.

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

Esempio: Sovrapposizione del minimo di ciclo (forma abbreviata)

Per un confronto rapido senza stile per singolo ciclo, passa gli ID delle metriche come semplici stringhe — i colori provengono automaticamente dalla palette del 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

Esempio: Sovrapposizione ancorata all'halving

Stessa forma, quattro cicli ancorati a ciascun evento di 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 con strumento MCP

Da un agente IA connesso al server MCP, lo stesso grafico è una singola chiamata di strumento:

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

Il server MCP accetta lo stesso enum x_axis, gli stessi ID di metriche e le stesse regole di validazione dell'API HTTP.

Controllo della legenda per singola metrica

Usa show_in_legend sui singoli oggetti di configurazione delle metriche per controllare se una metrica appare nella legenda del grafico. È utile quando combini molte serie in cui alcune sono linee di contesto/sfondo.

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

Campo	Tipo	Predefinito	Descrizione
`show_in_legend`	boolean	`true`	Se la metrica appare nella legenda del grafico

Impostazioni predefinite intelligenti

La Snapshot API utilizza impostazioni predefinite intelligenti così da poter ottenere grafici dall'aspetto eccellente con una configurazione minima:

Parametro	Come viene determinato il valore predefinito
Stile del grafico	Dal registro delle metriche (`chart_types[0]`)
Colore	Dal registro delle metriche, poi rotazione della palette
Lato dell'asse Y	Prima metrica a sinistra; le metriche con lo stesso formato condividono l'asse; formato diverso a destra
Scala dell'asse Y	`linear` (sovrascrivibile con `scale=log`)
Intervallo temporale	In base alla categoria: 365 giorni per price/valuation/profit, 730 per supply, 180 per blockchain
Titolo	Metrica singola: nome della metrica. Multiple: "Name1 vs Name2"
Dimensione dell'immagine	1200 x 600 pixel
Tema	`light`

Risposte di errore

Tutti gli errori restituiscono 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."}

Strumento MCP: `render_chart`

Il server MCP di Blocklens include uno strumento render_chart che consente agli agenti IA di generare immagini di grafici direttamente nelle conversazioni. Lo strumento chiama la Snapshot API e restituisce l'immagine inline come PNG (raster) o SVG (vettoriale).

Parametri

Parametro	Tipo	Predefinito	Descrizione
`metric`	string	-	ID di una singola metrica
`metrics`	array	-	Più metriche (stringhe o oggetti)
`template`	string	-	ID del template
`days`	integer	365	Giorni di storico
`start_date`	string	-	Data di inizio (YYYY-MM-DD)
`end_date`	string	-	Data di fine (YYYY-MM-DD)
`overlay`	`price`	-	Aggiunge la sovrapposizione del prezzo (attualmente BTC)
`theme`	`light` / `dark`	`light`	Tema dei colori
`width`	integer	1200	Larghezza dell'immagine
`height`	integer	600	Altezza dell'immagine
`title`	string	auto	Titolo del grafico
`style`	`line` / `area` / `bar`	auto	Stile del grafico
`scale`	`linear` / `log`	`linear`	Scala dell'asse Y
`format`	`png` / `svg` / `json`	`png`	Formato di output: `png` (immagine raster), `svg` (immagine vettoriale, scala senza perdita di qualità) o `json` (solo metadati — nessun rendering)
`y_axes`	array	-	Assi Y personalizzati con zone (vedi Assi Y personalizzati)
`x_axis`	`date` / `day_offset`	`date`	Modalità dell'asse X. Usa `day_offset` per le sovrapposizioni delle performance di ciclo — tutte le `metrics` devono essere della stessa famiglia di ciclo.
`heatmap_id`	`cost-basis-distribution`	-	Renderizza una heatmap invece di un grafico a linee (vedi Rendering delle heatmap). Mutuamente esclusivo con `metric` / `metrics` / `template`.
`heatmap_period`	`3m` / `6m` / `1y` / `2y` / `3y` / `5y` / `all`	`1y`	Finestra di binning della heatmap.
`heatmap_color_scale`	`viridis` / `plasma` / `inferno` / `magma` / `cividis`	`viridis`	Palette di colori della heatmap.
`heatmap_y_scale`	`linear` / `log`	`linear`	Scala dell'asse Y dei bin di prezzo della heatmap.
`params`	object	-	Parametri per chiamata per le metriche parametrizzate (es. `{ "exchange": "binance" }`, `{ "ticker": "IBIT" }`, `{ "entity": "tesla" }`).
`reference_lines`	array	-	Linee di riferimento orizzontali (vedi Linee e aree di riferimento)
`reference_areas`	array	-	Zone di riferimento ombreggiate (vedi Linee e aree di riferimento)

Esempi di utilizzo

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

Configurazione MCP

Aggiungi quanto segue alla configurazione di Claude Desktop o Cursor per abilitare il rendering dei grafici:

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

Consulta Server MCP per le istruzioni complete di configurazione.

Esempio avanzato: Grafico LTH Supply

Questo esempio replica il grafico completo Long-Term Holder Supply della dashboard di Blocklens — due metriche, due serie calcolate da formula e tre assi 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

Cosa produce:

BTC Price — linea grigia sull'asse destro (scala logaritmica)
LTH Supply — linea blu sull'asse sinistro (lineare)
Accumulo positivo a 30 giorni — barre verdi semi-trasparenti su un asse axis-diff separato
Distribuzione a 30 giorni — barre rosse semi-trasparenti sullo stesso asse axis-diff

Tecniche chiave utilizzate:

shift(lth_supply, 30) calcola il valore di lookback a 30 giorni
max(..., 0) e min(0, ...) separano le variazioni positive e negative in serie distinte
y_axis_id: "axis-diff" vincola entrambe le barre delle formule a un asse dedicato, indipendente dagli assi delle metriche principali
fill_opacity: 0.2 + stroke_width: 0 crea barre trasparenti, sottili e senza bordi

Template di grafici

Le configurazioni complete dei grafici (incluse metriche, formule, assi e stile) sono disponibili come template basati su database tramite:

GET /api/lab/templates

Questi template possono fungere da riferimento per costruire i corpi delle tue richieste POST. Ogni template contiene la configurazione completa che produce uno specifico grafico sulla dashboard di Blocklens.

Filigrana

Tutte le immagini dei grafici renderizzate includono una filigrana blocklens.co e un avviso di copyright. Questo vale sia per i formati di output PNG che SVG.

Caching

Gli snapshot renderizzati vengono memorizzati nella cache per 1 ora in Redis. Comportamento della cache:

Configurazioni di grafici identiche restituiscono istantaneamente i risultati in cache
La chiave di cache deriva dalla configurazione completa del grafico (metriche, assi, intervallo temporale, tema, dimensione) più il formato di output — le varianti PNG e SVG dello stesso grafico vengono memorizzate in cache in modo indipendente
L'header di risposta X-Snapshot-Cache indica HIT o MISS
L'header X-Snapshot-Render-Ms mostra il tempo di rendering (0 per i cache hit)
I file renderizzati vengono inoltre conservati su disco sotto /v1/chart/renders/{render_id}.png e /v1/chart/renders/{render_id}.svg per 1 ora, così gli URL dei grafici restituiti nell'header X-Render-Id rimangono raggiungibili
I grafici più popolari vengono pre-riscaldati dopo ogni aggiornamento giornaliero dei dati (05:00 UTC)

Endpoint​

Autenticazione​

Accesso e limiti di frequenza​

GET /v1/chart/snapshot​

Parametri​

Template disponibili​

Esempi​

Risposta in caso di successo​

POST /v1/chart/snapshot​

Corpo della richiesta​

Campo metrics​

Opzioni per singola metrica​

Assi Y personalizzati​

Esempio: Prezzo + Volume con zone verticali​

Esempio: Drawdown con vincolo di dominio​

Formule​

Medie mobili e statistiche rolling​

Cumulative​

Variazioni​

Matematica​

Indicatori tecnici​

Rischio e rendimento​

Manipolazione delle serie​

Operatori​

Riferimenti​

Linee e aree di riferimento​

Opzioni delle linee di riferimento​

Opzioni delle aree di riferimento​

Esempio: MVRV con zone di valore​

Esempio: Banda basata su formula​

Formato di output​

Risposta con metadati JSON​

Esempi​

Rendering delle heatmap​

Parametri delle heatmap​

Esempio​

Grafici di sovrapposizione delle performance di ciclo​

Tipi di ancoraggio​

Tutte le metriche di ciclo disponibili​

Parametri delle performance di ciclo​

Esempio: Sovrapposizione ancorata all'ATH (colori personalizzati per ciclo)​

Esempio: Sovrapposizione del minimo di ciclo (forma abbreviata)​

Esempio: Sovrapposizione ancorata all'halving​

Equivalente con strumento MCP​

Controllo della legenda per singola metrica​

Impostazioni predefinite intelligenti​

Risposte di errore​

Strumento MCP: render_chart​

Parametri​

Esempi di utilizzo​

Configurazione MCP​

Esempio avanzato: Grafico LTH Supply​

Template di grafici​

Filigrana​

Caching​

Endpoint

Autenticazione

Accesso e limiti di frequenza

GET `/v1/chart/snapshot`

Parametri

Template disponibili

Esempi

Risposta in caso di successo

POST `/v1/chart/snapshot`

Corpo della richiesta

Campo metrics

Opzioni per singola metrica

Assi Y personalizzati

Esempio: Prezzo + Volume con zone verticali

Esempio: Drawdown con vincolo di dominio

Formule

Medie mobili e statistiche rolling

Cumulative

Variazioni

Matematica

Indicatori tecnici

Rischio e rendimento

Manipolazione delle serie

Operatori

Riferimenti

Linee e aree di riferimento

Opzioni delle linee di riferimento

Opzioni delle aree di riferimento

Esempio: MVRV con zone di valore

Esempio: Banda basata su formula

Formato di output

Risposta con metadati JSON

Esempi

Rendering delle heatmap

Parametri delle heatmap

Esempio

Grafici di sovrapposizione delle performance di ciclo

Tipi di ancoraggio

Tutte le metriche di ciclo disponibili

Parametri delle performance di ciclo

Esempio: Sovrapposizione ancorata all'ATH (colori personalizzati per ciclo)

Esempio: Sovrapposizione del minimo di ciclo (forma abbreviata)

Esempio: Sovrapposizione ancorata all'halving

Equivalente con strumento MCP

Controllo della legenda per singola metrica

Impostazioni predefinite intelligenti

Risposte di errore

Strumento MCP: `render_chart`

Parametri

Esempi di utilizzo

Configurazione MCP

Esempio avanzato: Grafico LTH Supply

Template di grafici

Filigrana

Caching