API Snapshot

L'API Snapshot restitue les graphiques d'analyse on-chain sous forme d'images PNG ou de graphiques vectoriels SVG. Envoyez des identifiants de métriques et des paramètres d'affichage optionnels, et recevez une image de graphique entièrement rendue, prête à être intégrée dans des rapports, des tableaux de bord ou des conversations avec une IA. Prend actuellement en charge les métriques Bitcoin, avec une couverture multi-chaînes (ETH, TON, TRON) en cours d'extension.

Endpoints

Méthode	Chemin	Description
`GET`	`/v1/chart/snapshot`	Graphiques simples via paramètres de requête
`POST`	`/v1/chart/snapshot`	Personnalisation complète via corps JSON

Les deux endpoints renvoient image/png par défaut. Passez en SVG (image/svg+xml) ou en métadonnées JSON (application/json) en définissant l'en-tête de requête Accept, ou — en POST — le champ format du corps ("png", "svg", "json").

Les réponses PNG et SVG réussies incluent un en-tête X-Render-Id permettant de récupérer à nouveau le graphique rendu par URL pendant 1 heure :

Sortie	Mis en cache à
PNG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.png`
SVG	`https://api.blocklens.co/v1/chart/renders/{X-Render-Id}.svg`

Authentification

Toutes les requêtes nécessitent une clé API via l'en-tête Authorization :

Authorization: Bearer YOUR_API_KEY

Consultez Authentification pour plus de détails sur l'obtention de clés API.

Accès et limites de débit

L'API Snapshot nécessite le niveau Pro ou Enterprise. Les clés des niveaux Demo et Free reçoivent 403 Forbidden.

L'API Snapshot suit les mêmes limites de débit que l'API Data. Consultez Limites de débit pour plus de détails.

En cas de limitation de débit, l'API renvoie 429 Too Many Requests avec un champ retry_after.

L'accès aux métriques est également restreint par grade : les métriques de grade 0 (prix, offre, MVRV) sont disponibles pour toutes les clés Pro+, les métriques de grade 1 (SOPR, P&L) nécessitent Pro, et les métriques de grade 2 (cartes thermiques CBD) nécessitent Enterprise.

GET `/v1/chart/snapshot`

Génère un graphique à partir de paramètres de requête. Idéal pour les graphiques simples, à métrique unique ou basés sur un modèle.

Paramètres

Paramètre	Type	Défaut	Description
`metric`	string	-	Identifiant de métrique unique (par ex. `price`, `lth_supply`). Mutuellement exclusif avec `metrics` et `template`.
`metrics`	string	-	Identifiants de métriques séparés par des virgules, max 6 (par ex. `lth_supply,sth_supply`). Mutuellement exclusif avec `metric` et `template`.
`template`	string	-	Identifiant de modèle prédéfini. Mutuellement exclusif avec `metric` et `metrics`.
`days`	integer	365	Jours de données historiques (7-10000).
`start_date`	string	-	Date de début (`YYYY-MM-DD`). Remplace `days`.
`end_date`	string	-	Date de fin (`YYYY-MM-DD`). Par défaut aujourd'hui.
`style`	string	auto	Style de graphique : `line`, `area`, `bar`. Détecté automatiquement à partir du registre des métriques si omis.
`scale`	string	`linear`	Échelle de l'axe Y : `linear` ou `log`.
`overlay`	string	-	Ajoute une superposition de prix sous forme de ligne pointillée discrète sur l'axe de droite (utilisez `price`). Actuellement le prix du BTC.
`width`	integer	1200	Largeur de l'image en pixels (600-2400).
`height`	integer	600	Hauteur de l'image en pixels (300-1200).
`title`	string	auto	Titre du graphique. Généré automatiquement à partir des noms de métriques si omis.
`theme`	string	`light`	Thème de couleur : `light` ou `dark`.

Exactement un parmi metric, metrics ou template doit être fourni.

Modèles disponibles

Modèle	Métriques
`price`	Prix du BTC
`price_volume`	Prix + Volume
`market_cap`	Capitalisation boursière
`holder_supply`	Offre LTH + Offre STH
`mvrv_ratio`	MVRV LTH + MVRV STH
`realized_price`	Prix réalisé LTH + Prix réalisé STH
`realized_cap`	Capitalisation réalisée LTH + Capitalisation réalisée STH
`unrealized_pl`	P/L non réalisé LTH + P/L non réalisé STH
`realized_pl`	P/L réalisé LTH + P/L réalisé STH
`sopr`	SOPR LTH + SOPR STH
`block_height`	Hauteur de bloc

Exemples

# Exemple Bitcoin : prix du BTC, 1 an, graphique en ligne
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" \
  --output price.png

# Exemple Bitcoin : deux métriques avec style en aires
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

# Modèle avec thème sombre
curl -H "Authorization: Bearer YOUR_KEY" \
  "https://api.blocklens.co/v1/chart/snapshot?template=mvrv_ratio&theme=dark" \
  --output mvrv_dark.png

# Échelle logarithmique avec superposition de prix
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

# Obtenir les métadonnées JSON au lieu de l'image
curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: application/json" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" | jq

# Obtenir du SVG au lieu de PNG
curl -H "Authorization: Bearer YOUR_KEY" \
  -H "Accept: image/svg+xml" \
  "https://api.blocklens.co/v1/chart/snapshot?metric=price" \
  --output price.svg

Réponse en cas de succès

PNG (par défaut) :

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

La valeur X-Render-Id peut être utilisée pour récupérer à nouveau la même image à /v1/chart/renders/{render_id}.png ou /v1/chart/renders/{render_id}.svg pendant 1 heure maximum.

POST `/v1/chart/snapshot`

Personnalisation complète du graphique via corps JSON. Prend en charge la mise en forme par métrique, des axes personnalisés, des formules, des lignes de référence, des zones de référence, et plus encore. Conçu pour les agents IA (via MCP) et les utilisateurs avancés.

Corps de la requête

Fournissez exactement une source de données (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"}
  ]
}

Note : Exactement un parmi metric, metrics ou template doit être fourni.

Champ Metrics

Le champ metrics prend en charge des types mixtes :

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

Certaines métriques nécessitent des paramètres supplémentaires (par ex. exchange, ticker, id). Incluez l'objet params issu de la définition de la métrique lorsque vous utilisez ces métriques.

Options par métrique

Champ	Type	Description
`id`	string	Requis. Identifiant de métrique issu du registre.
`params`	object	Paramètres pour les métriques paramétrées (par ex. `{"exchange": "binance"}`). Voir la définition de la métrique pour les paramètres requis.
`axis`	`left` / `right`	Côté de l'axe Y. Attribué automatiquement si omis.
`y_axis_id`	string	Lier à un axe Y spécifique par son ID (par ex. `axis-diff`). Remplace `axis`.
`style`	`line` / `area` / `bar`	Style de graphique. Valeur par défaut du registre si omis.
`color`	string	Couleur hexadécimale (par ex. `#2563eb`). Attribuée automatiquement si omise.
`label`	string	Libellé d'affichage. Utilise le nom de la métrique si omis.
`stroke_width`	integer	Épaisseur de ligne (0-5). Défaut : 2. Utilisez 0 pour des barres sans bordures.
`fill_opacity`	float	Opacité du remplissage (0.0-1.0). Pour des barres transparentes, utilisez des valeurs basses comme 0.2.
`stroke_dash`	string	Motif de pointillés (par ex. `5 5`).
`stack_group`	string	ID du groupe d'empilement pour les graphiques empilés.
`show_in_legend`	boolean	Indique s'il faut afficher dans la légende du graphique. Défaut : true.
`visible`	boolean	Afficher/masquer. Défaut : true.

Axes Y personnalisés

Le champ y_axes définit les axes Y disponibles pour les métriques et les formules. Chaque axe possède un id unique pouvant être référencé via y_axis_id sur les métriques ou les formules. Vous pouvez définir plus de deux axes — par exemple, un axe distinct pour les différences calculées :

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

Champ	Type	Description
`id`	string	Identifiant d'axe unique. Référencé par `y_axis_id` sur les métriques/formules.
`side`	`left` / `right`	Côté du graphique où apparaît l'axe.
`scale`	`linear` / `log`	Échelle de l'axe. Défaut : `linear`.
`format`	`number` / `currency` / `percent`	Format numérique des libellés d'axe.
`range`	`[number, number]`	Zone verticale sous la forme `[from%, to%]`. `0` = bas, `100` = haut. Défaut : pleine hauteur. À utiliser pour empiler les axes verticalement (par ex. volume dans les 20 % du bas, prix dans les 80 % du haut).
`domain_min`	number	Bornage minimum strict du domaine. L'axe ne descendra jamais en dessous de cette valeur.
`domain_max`	number	Bornage maximum strict du domaine. L'axe ne dépassera jamais cette valeur.
`no_padding`	`"top"` / `"bottom"` / `"both"`	Supprime la marge automatique de 10 % des bords. Utile lorsqu'un bornage de domaine constitue une limite stricte (par ex. drawdown plafonné à 0).

Si y_axes est omis, les axes sont générés automatiquement en fonction des valeurs axis des métriques.

Exemple : Prix + Volume avec zones verticales

Empilez les barres de volume dans les 20 % du bas et le prix dans l'espace restant :

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

Ce que cela produit :

Les barres de volume occupent les 20 % du bas du graphique (range: [0, 20]) sans marge sur le bord inférieur
Le prix occupe les 80 % du haut (range: [20, 100]) sur une échelle logarithmique
Les deux séries ne se chevauchent jamais, créant une disposition empilée nette

Exemple : Drawdown avec bornage de domaine

Plafonnez le drawdown à 0 (bord supérieur) pour que la ligne touche le haut de sa zone :

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

Ce que cela produit :

Le drawdown est toujours ≤ 0, donc domain_max: 0 borne le bord supérieur
no_padding: "top" supprime la marge automatique de 10 % au-dessus de 0, faisant que la ligne touche le haut lorsque le drawdown est de 0 %
Le prix est sur l'axe de droite avec une échelle logarithmique

Formules

Le champ formulas vous permet de définir des séries calculées dérivées de vos métriques. Les formules peuvent référencer les métriques par leur id (par ex. lth_supply) ou par index positionnel (m1, m2, etc. selon l'ordre dans le tableau 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
  }
]

Fonctions prises en charge (30 au total) :

Moyennes mobiles et statistiques glissantes

Fonction	Syntaxe	Description
`sma`	`sma(series, period)`	Moyenne mobile simple
`ema`	`ema(series, period)`	Moyenne mobile exponentielle
`median`	`median(series, period)`	Médiane glissante
`sum`	`sum(series, period)`	Somme glissante
`std`	`std(series, period)`	Écart-type glissant

Cumulatif

Fonction	Syntaxe	Description
`cumsum`	`cumsum(series)`	Somme cumulée extensible
`cummean`	`cummean(series)`	Moyenne cumulée extensible
`cummedian`	`cummedian(series)`	Médiane cumulée extensible
`cumstd`	`cumstd(series)`	Écart-type cumulé extensible
`cummax`	`cummax(series)`	Maximum cumulé historique
`cummin`	`cummin(series)`	Minimum cumulé historique

Variations

Fonction	Syntaxe	Description
`percent_change`	`percent_change(series, period)`	Variation en pourcentage (décimal : 0.20 = +20%)
`diff`	`diff(series, period)`	Variation en valeur absolue

Mathématiques

Fonction	Syntaxe	Description
`abs`	`abs(series)`	Valeur absolue
`pow`	`pow(series, n)`	Élévation à la puissance n
`log`	`log(series)`	Logarithme en base 10
`round`	`round(series, digits)`	Arrondi à N décimales
`max`	`max(a, b, ...)`	Maximum point par point
`min`	`min(a, b, ...)`	Minimum point par point

Indicateurs techniques

Fonction	Syntaxe	Description
`rsi`	`rsi(series, period)`	Indice de force relative (0-100)
`corr`	`corr(s1, s2, period)`	Corrélation de Pearson (-1 à 1)
`drawdown`	`drawdown(series)`	Drawdown depuis l'ATH (décimal négatif)

Risque et rendement

Fonction	Syntaxe	Description
`mean_return`	`mean_return(series, period)`	Rendement moyen glissant annualisé
`realized_vol`	`realized_vol(series, period)`	Volatilité réalisée annualisée
`sharpe_ratio_arithmetic`	`sharpe_ratio_arithmetic(series, period)`	Ratio de Sharpe (arithmétique)
`sharpe_ratio_geometric`	`sharpe_ratio_geometric(series, period)`	Ratio de Sharpe (géométrique)

Manipulation de séries

Fonction	Syntaxe	Description
`shift`	`shift(series, period)`	Décale la série de N périodes
`if`	`if(a, "op", b, then, else)`	Condition (op : `=`, `!=`, `>`, `>=`, `<`, `<=`)

Opérateurs

Arithmétique : +, -, *, / Groupement : (, )

Référencement

Métriques par nom : lth_supply + sth_supply — utilisez directement les identifiants de métriques
Métriques par position : m1 + m2 — références positionnelles (m1 = première métrique, m2 = deuxième, etc.)
Autres formules : f1 * 2 — référence aux formules précédentes (f1 = première formule, etc.)
Les formules sont évaluées dans l'ordre, donc f2 peut référencer f1, mais pas l'inverse.

Options de formule :

Champ	Type	Description
`expression`	string	Requis. Expression de formule utilisant des identifiants de métriques ou des références positionnelles (`m1`, `m2`).
`label`	string	Requis. Libellé d'affichage pour la légende.
`color`	string	Couleur hexadécimale. Attribuée automatiquement si omise.
`style`	`line` / `area` / `bar`	Style de graphique. Défaut : `line`.
`y_axis_id`	string	Lier à un axe Y spécifique par son ID (par ex. `axis-diff`). Remplace `axis`.
`axis`	`left` / `right`	Côté de l'axe Y. Défaut : `left`. Ignoré si `y_axis_id` est défini.
`fill_opacity`	float	Opacité du remplissage (0.0-1.0). Pour des barres transparentes, utilisez des valeurs basses comme 0.2.
`stroke_width`	integer	Épaisseur du trait (0-5). Utilisez 0 pour des barres sans bordures.
`stroke_dash`	string	Motif de pointillés (par ex. `6 3`).
`stack_group`	string	ID du groupe d'empilement pour empiler plusieurs séries de formules.

Lignes et zones de référence

Les lignes de référence ajoutent des lignes de repère horizontales pour mettre en évidence des valeurs spécifiques (par ex. seuil de rentabilité à 1.0, seuil de surachat). Les zones de référence ajoutent des zones ombrées pour mettre en évidence des plages de valeurs (par ex. zone de sous-évaluation, bandes de type Bollinger). Les deux prennent en charge les valeurs statiques et les formules dynamiques en utilisant le même moteur de formules que le champ formulas.

Options de ligne de référence

Champ	Type	Description
`y`	number	Valeur Y statique.
`y_formula`	string	Expression de formule pour un Y dynamique (par ex. `"sma(m1, 200)"`). Utilise le même moteur que `formulas`.
`y_axis_id`	string	ID de l'axe Y (par défaut le premier axe gauche).
`stroke`	string	Couleur de ligne hexadécimale (défaut : `#9ca3af`).
`stroke_dasharray`	string	Motif de pointillés, par ex. `"3 3"` pour des tirets.
`label`	string	Texte du libellé.

Fournissez soit y (statique) soit y_formula (dynamique), pas les deux. Maximum 10 lignes de référence par graphique.

Options de zone de référence

Champ	Type	Description
`y1`	number	Borne Y inférieure statique.
`y2`	number	Borne Y supérieure statique.
`y1_formula`	string	Formule pour la borne inférieure dynamique.
`y2_formula`	string	Formule pour la borne supérieure dynamique.
`y_axis_id`	string	ID de l'axe Y (par défaut le premier axe gauche).
`fill`	string	Couleur de remplissage hexadécimale (défaut : `#3b82f6`).
`fill_opacity`	number	Opacité du remplissage 0–1 (défaut : `0.1`).
`label`	string	Texte du libellé.

Fournissez des bornes statiques (y1/y2) ou basées sur des formules (y1_formula/y2_formula) — vous pouvez les mélanger (par ex. y1 statique avec y2_formula dynamique). Maximum 10 zones de référence par graphique.

Exemple : MVRV avec zones de valeur

Ajoutez une zone verte de sous-évaluation (0–0.85), une zone rouge de surévaluation (8–100) et une ligne de seuil de rentabilité en pointillés à 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

Exemple : Bande basée sur une formule

Créez une bande de type Bollinger autour de la première formule (enveloppe ±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 de sortie

Le champ format contrôle la sortie :

Format	Content-Type	Description
`png` (défaut)	`image/png`	Image de graphique rasterisée
`svg`	`image/svg+xml`	Graphiques vectoriels (évolutifs, intégrables)
`json`	`application/json`	Métadonnées du graphique (sans rendu)

Vous pouvez également utiliser l'en-tête Accept :

Accept: image/png - PNG (défaut)
Accept: image/svg+xml - SVG
Accept: application/json - Métadonnées JSON

Réponse de métadonnées JSON

Lorsque 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
}

Exemples

# POST avec une seule métrique
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-métrique avec mise en forme personnalisée
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

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

# Métadonnées 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

Rendu de cartes thermiques

L'API Snapshot peut restituer des cartes thermiques pour les métriques basées sur des distributions comme la distribution du coût de base (Cost Basis Distribution). Les cartes thermiques utilisent un ensemble de paramètres distinct de celui des graphiques de métriques standard.

Paramètres de carte thermique

Paramètre	Type	Défaut	Description
`heatmap_id`	string	-	Identifiant de carte thermique (par ex. `cost-basis-distribution`)
`heatmap_period`	string	`1y`	Période : `3m`, `6m`, `1y`, `2y`, `3y`, `5y`, `all`
`heatmap_color_scale`	string	`viridis`	Échelle de couleur : `viridis`, `plasma`, `inferno`, `magma`, `cividis`
`heatmap_y_scale`	string	`linear`	Échelle de l'axe Y : `linear` ou `log`
`theme`	string	`light`	Thème de couleur : `light` ou `dark`
`title`	string	auto	Titre du graphique
`width`	integer	1200	Largeur de l'image en pixels
`height`	integer	600	Hauteur de l'image en pixels

Exemple

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

Note : Les paramètres de carte thermique (heatmap_id, etc.) sont mutuellement exclusifs avec les paramètres de métriques standard (metric, metrics, template). Les métriques de carte thermique nécessitent le niveau Enterprise.

La légende de l'échelle de couleur est incluse dans l'image rendue, montrant la plage de valeurs associée à la palette de couleurs sélectionnée.

Graphiques de superposition de performance de cycle

Les graphiques de performance de cycle superposent plusieurs cycles Bitcoin sur le même axe X afin de pouvoir les comparer à l'identique. Au lieu d'être tracé par rapport aux dates calendaires, le prix de chaque cycle est indexé sur son propre événement d'ancrage (creux de cycle, ATH ou halving) et tracé par rapport aux jours écoulés depuis cet ancrage.

Activez le mode superposition en définissant x_axis: "day_offset" sur une requête POST /v1/chart/snapshot et en fournissant des métriques de cycle dans le tableau metrics. Le moteur de rendu utilise le champ day_offset de chaque point de données au lieu de date, de sorte que tous les cycles commencent au Jour 0 sur l'axe X.

Les libellés des graduations affichent les dates calendaires du cycle le plus récent de la famille choisie. Par exemple, une superposition ATH (cycle_ath_1…cycle_ath_5) s'ancre sur 2025-10-06 et les graduations indiquent Oct '25, Jan '26, Apr '26, etc. — et non Day 0, Day 90, Day 180. Les autres cycles du même graphique sont alignés sur les mêmes positions de l'axe X, de sorte qu'une valeur à la graduation Apr '26 sur cycle_ath_3 signifie « ce que faisait le BTC 182 jours après le début du cycle 2017 ». La numérotation par jours réapparaît en solution de repli uniquement si le backend ne parvient pas à déterminer l'ancrage.

Types d'ancrage

Trois familles de métriques de cycle sont disponibles, une par événement d'ancrage :

Ancrage	Préfixe d'identifiant de métrique	Description	Indication d'endpoint
Creux de cycle → creux suivant	`cycle_low_*`	Prix indexé sur le creux du cycle — chaque série commence à 1.0 à la date du creux et court jusqu'au creux du cycle suivant.	`endpoint: "cycle-performance?type=low"`
ATH → ATH	`cycle_ath_*`	Prix indexé sur le plus haut historique du cycle — chaque série commence à 1.0 à la date de l'ATH et court jusqu'au prochain ATH.	`endpoint: "cycle-performance?type=ath"`
Halving → halving	`cycle_halving_*`	Prix indexé sur le bloc de halving — chaque série commence à 1.0 à la date du halving et court jusqu'au halving suivant.	`endpoint: "cycle-performance?type=halving"`

Au sein d'une famille d'ancrage, chaque cycle présente la même forme de données — un indice qui commence à 1.0 et suit price(t) / price(anchor) jusqu'au prochain événement d'ancrage (ou, pour le cycle en cours, jusqu'à aujourd'hui). C'est ce qui rend la comparaison par superposition pertinente : une valeur de 5.0 au jour 200 de cycle_ath_3 signifie « le BTC valait 5× son ATH de 2017, 200 jours après cet ATH ».

Toutes les métriques de cycle disponibles

Identifiant de métrique	Date d'ancrage	Ancrage → date de fin
`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 → aujourd'hui (cycle en cours)
`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 → aujourd'hui (cycle en cours)
`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 → aujourd'hui (cycle en cours)

Règles de validation

Toutes les metrics doivent provenir de la même famille d'ancrage. Mélanger cycle_ath_* avec cycle_low_* (ou tout ce qui est en dehors de daily_cycle_performance) renvoie 400 invalid_params.
Le drapeau x_axis: "day_offset" n'est valide que pour les métriques de cycle — l'associer à toute autre métrique renvoie 400 invalid_params.
La limite standard de « max 6 métriques par graphique » s'applique — choisissez jusqu'à 6 cycles par superposition.

Paramètres de performance de cycle

En plus de tous les paramètres de graphique standard (days, width, height, theme, scale, format, title, y_axes, reference_lines, reference_areas, formulas, etc.), le mode superposition de cycle utilise ces champs :

Champ	Type	Défaut	Description
`x_axis`	`"date"` / `"day_offset"`	`"date"`	Définissez sur `"day_offset"` pour activer la superposition de cycle. Sinon, l'axe X est en dates calendaires.
`metrics`	array	requis	1 à 6 identifiants de métriques de cycle de la même famille d'ancrage. Chaînes ou objets (`{id, color, style, label, stroke_width, fill_opacity, show_in_legend, y_axis_id}`).
`days`	integer	365	Plafonne le décalage de jour maximum rendu (plage de l'axe X, et non jours calendaires). Définissez sur `1500` pour voir environ 4 ans par cycle.
`scale`	`"linear"` / `"log"`	`"linear"`	L'échelle logarithmique est presque toujours ce que vous voulez — les multiplicateurs de début de cycle peuvent atteindre 100×–500×, ce qui est illisible en échelle linéaire.
`theme`	`"light"` / `"dark"`	`"light"`	Le thème sombre est la valeur par défaut du tableau de bord pour ces graphiques.

Les lignes de référence (reference_lines) sont particulièrement utiles sur les graphiques de superposition — par ex. une ligne horizontale à y: 1.0 marque le niveau d'ancrage, y: 2.0 marque « 2× l'ancrage », et ainsi de suite.

Exemple : Superposition ancrée sur l'ATH (couleurs personnalisées par cycle)

Cette recette reproduit le graphique « Price Performance Since ATH » du tableau de bord — cinq cycles, chacun dans une couleur distincte, sur un axe logarithmique.

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

Exemple : Superposition de creux de cycle (forme abrégée)

Pour une comparaison rapide sans mise en forme par cycle, passez les identifiants de métriques sous forme de chaînes simples — les couleurs proviennent automatiquement de la palette du registre.

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

Exemple : Superposition ancrée sur le halving

Même forme, quatre cycles ancrés sur chaque événement 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

Équivalent en outil MCP

Depuis un agent IA connecté au serveur MCP, le même graphique tient en un seul appel d'outil :

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

Le serveur MCP accepte le même enum x_axis, les mêmes identifiants de métriques et les mêmes règles de validation que l'API HTTP.

Contrôle de la légende par métrique

Utilisez show_in_legend sur les objets de configuration de métrique individuels pour contrôler si une métrique apparaît dans la légende du graphique. C'est utile lorsque vous combinez de nombreuses séries dont certaines sont des lignes de contexte/d'arrière-plan.

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

Champ	Type	Défaut	Description
`show_in_legend`	boolean	`true`	Indique si la métrique apparaît dans la légende du graphique

Valeurs par défaut intelligentes

L'API Snapshot utilise des valeurs par défaut intelligentes afin que vous puissiez obtenir de superbes graphiques avec un minimum de configuration :

Paramètre	Comment la valeur par défaut est déterminée
Style de graphique	À partir du registre des métriques (`chart_types[0]`)
Couleur	À partir du registre des métriques, puis rotation de la palette
Côté de l'axe Y	Première métrique à gauche ; les métriques de même format partagent l'axe ; format différent à droite
Échelle de l'axe Y	`linear` (remplacez avec `scale=log`)
Plage temporelle	Selon la catégorie : 365 jours pour prix/valorisation/profit, 730 pour l'offre, 180 pour la blockchain
Titre	Métrique unique : nom de la métrique. Plusieurs : « Nom1 vs Nom2 »
Taille de l'image	1200 x 600 pixels
Thème	`light`

Réponses d'erreur

Toutes les erreurs renvoient du 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."}

Outil MCP : `render_chart`

Le serveur MCP de Blocklens inclut un outil render_chart qui permet aux agents IA de générer des images de graphiques directement dans les conversations. L'outil appelle l'API Snapshot et renvoie l'image en ligne sous forme de PNG (raster) ou de SVG (vectoriel).

Paramètres

Paramètre	Type	Défaut	Description
`metric`	string	-	Identifiant de métrique unique
`metrics`	array	-	Plusieurs métriques (chaînes ou objets)
`template`	string	-	Identifiant de modèle
`days`	integer	365	Jours d'historique
`start_date`	string	-	Date de début (YYYY-MM-DD)
`end_date`	string	-	Date de fin (YYYY-MM-DD)
`overlay`	`price`	-	Ajoute une superposition de prix (actuellement BTC)
`theme`	`light` / `dark`	`light`	Thème de couleur
`width`	integer	1200	Largeur de l'image
`height`	integer	600	Hauteur de l'image
`title`	string	auto	Titre du graphique
`style`	`line` / `area` / `bar`	auto	Style de graphique
`scale`	`linear` / `log`	`linear`	Échelle de l'axe Y
`format`	`png` / `svg` / `json`	`png`	Format de sortie : `png` (image raster), `svg` (image vectorielle, s'agrandit sans perte de qualité) ou `json` (métadonnées uniquement — sans rendu)
`y_axes`	array	-	Axes Y personnalisés avec zones (voir Axes Y personnalisés)
`x_axis`	`date` / `day_offset`	`date`	Mode de l'axe X. Utilisez `day_offset` pour les superpositions de performance de cycle — toutes les `metrics` doivent provenir de la même famille de cycle.
`heatmap_id`	`cost-basis-distribution`	-	Restitue une carte thermique au lieu d'un graphique en ligne (voir Rendu de cartes thermiques). Mutuellement exclusif avec `metric` / `metrics` / `template`.
`heatmap_period`	`3m` / `6m` / `1y` / `2y` / `3y` / `5y` / `all`	`1y`	Fenêtre de regroupement de la carte thermique.
`heatmap_color_scale`	`viridis` / `plasma` / `inferno` / `magma` / `cividis`	`viridis`	Palette de couleurs de la carte thermique.
`heatmap_y_scale`	`linear` / `log`	`linear`	Échelle de l'axe Y des paliers de prix de la carte thermique.
`params`	object	-	Paramètres par appel pour les métriques paramétrées (par ex. `{ "exchange": "binance" }`, `{ "ticker": "IBIT" }`, `{ "entity": "tesla" }`).
`reference_lines`	array	-	Lignes de référence horizontales (voir Lignes et zones de référence)
`reference_areas`	array	-	Zones de référence ombrées (voir Lignes et zones de référence)

Exemples d'utilisation

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

Configuration MCP

Ajoutez ceci à votre configuration Claude Desktop ou Cursor pour activer le rendu de graphiques :

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

Consultez Serveur MCP pour les instructions de configuration complètes.

Exemple avancé : graphique de l'offre LTH

Cet exemple reproduit l'intégralité du graphique Long-Term Holder Supply (offre des détenteurs à long terme) du tableau de bord Blocklens — deux métriques, deux séries de formules calculées et trois axes 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

Ce que cela produit :

Prix du BTC — ligne grise sur l'axe de droite (échelle logarithmique)
Offre LTH — ligne bleue sur l'axe de gauche (linéaire)
Accumulation positive sur 30 jours — barres vertes semi-transparentes sur un axe axis-diff distinct
Distribution sur 30 jours — barres rouges semi-transparentes sur le même axe axis-diff

Techniques clés utilisées :

shift(lth_supply, 30) calcule la valeur 30 jours en arrière
max(..., 0) et min(0, ...) séparent les variations positives et négatives en séries distinctes
y_axis_id: "axis-diff" lie les deux barres de formule à un axe dédié indépendant des axes de métrique principaux
fill_opacity: 0.2 + stroke_width: 0 crée des barres transparentes discrètes et sans bordures

Modèles de graphiques

Des configurations de graphiques complètes (y compris métriques, formules, axes et mise en forme) sont disponibles sous forme de modèles stockés en base de données via :

GET /api/lab/templates

Ces modèles peuvent servir de référence pour construire vos propres corps de requête POST. Chaque modèle contient la configuration complète qui produit un graphique spécifique sur le tableau de bord Blocklens.

Filigrane

Toutes les images de graphiques rendues incluent un filigrane blocklens.co et une mention de copyright. Cela s'applique aux formats de sortie PNG et SVG.

Mise en cache

Les snapshots rendus sont mis en cache pendant 1 heure dans Redis. Comportement du cache :

Les configurations de graphiques identiques renvoient instantanément les résultats mis en cache
La clé de cache est dérivée de la configuration complète du graphique (métriques, axes, plage temporelle, thème, taille) plus le format de sortie — les variantes PNG et SVG du même graphique sont mises en cache indépendamment
L'en-tête de réponse X-Snapshot-Cache indique HIT ou MISS
L'en-tête X-Snapshot-Render-Ms indique le temps de rendu (0 pour les accès au cache)
Les fichiers rendus sont également persistés sur disque sous /v1/chart/renders/{render_id}.png et /v1/chart/renders/{render_id}.svg pendant 1 heure, de sorte que les URL de graphiques renvoyées dans l'en-tête X-Render-Id restent accessibles
Les graphiques populaires sont préchargés dans le cache après chaque mise à jour quotidienne des données (05:00 UTC)

Endpoints​

Authentification​

Accès et limites de débit​

GET /v1/chart/snapshot​

Paramètres​

Modèles disponibles​

Exemples​

Réponse en cas de succès​

POST /v1/chart/snapshot​

Corps de la requête​

Champ Metrics​

Options par métrique​

Axes Y personnalisés​

Exemple : Prix + Volume avec zones verticales​

Exemple : Drawdown avec bornage de domaine​

Formules​

Moyennes mobiles et statistiques glissantes​

Cumulatif​

Variations​

Mathématiques​

Indicateurs techniques​

Risque et rendement​

Manipulation de séries​

Opérateurs​

Référencement​

Lignes et zones de référence​

Options de ligne de référence​

Options de zone de référence​

Exemple : MVRV avec zones de valeur​

Exemple : Bande basée sur une formule​

Format de sortie​

Réponse de métadonnées JSON​

Exemples​

Rendu de cartes thermiques​

Paramètres de carte thermique​

Exemple​

Graphiques de superposition de performance de cycle​

Types d'ancrage​

Toutes les métriques de cycle disponibles​

Paramètres de performance de cycle​

Exemple : Superposition ancrée sur l'ATH (couleurs personnalisées par cycle)​

Exemple : Superposition de creux de cycle (forme abrégée)​

Exemple : Superposition ancrée sur le halving​

Équivalent en outil MCP​

Contrôle de la légende par métrique​

Valeurs par défaut intelligentes​

Réponses d'erreur​

Outil MCP : render_chart​

Paramètres​

Exemples d'utilisation​

Configuration MCP​

Exemple avancé : graphique de l'offre LTH​

Modèles de graphiques​

Filigrane​

Mise en cache​

Endpoints

Authentification

Accès et limites de débit

GET `/v1/chart/snapshot`

Paramètres

Modèles disponibles

Exemples

Réponse en cas de succès

POST `/v1/chart/snapshot`

Corps de la requête

Champ Metrics

Options par métrique

Axes Y personnalisés

Exemple : Prix + Volume avec zones verticales

Exemple : Drawdown avec bornage de domaine

Formules

Moyennes mobiles et statistiques glissantes

Cumulatif

Variations

Mathématiques

Indicateurs techniques

Risque et rendement

Manipulation de séries

Opérateurs

Référencement

Lignes et zones de référence

Options de ligne de référence

Options de zone de référence

Exemple : MVRV avec zones de valeur

Exemple : Bande basée sur une formule

Format de sortie

Réponse de métadonnées JSON

Exemples

Rendu de cartes thermiques

Paramètres de carte thermique

Exemple

Graphiques de superposition de performance de cycle

Types d'ancrage

Toutes les métriques de cycle disponibles

Paramètres de performance de cycle

Exemple : Superposition ancrée sur l'ATH (couleurs personnalisées par cycle)

Exemple : Superposition de creux de cycle (forme abrégée)

Exemple : Superposition ancrée sur le halving

Équivalent en outil MCP

Contrôle de la légende par métrique

Valeurs par défaut intelligentes

Réponses d'erreur

Outil MCP : `render_chart`

Paramètres

Exemples d'utilisation

Configuration MCP

Exemple avancé : graphique de l'offre LTH

Modèles de graphiques

Filigrane

Mise en cache