render_chart
Render Bitcoin on-chain analytics charts as PNG images. Visualize single or multiple metrics with customizable templates, formulas, and axes.
Instructions
Render a Bitcoin on-chain analytics chart as a PNG image. Supports single metrics, multiple metrics, templates, computed formulas, and full customization.
Use this when the user asks to "show", "chart", "plot", "graph", or "visualize" any metric.
Smart defaults: just provide metric IDs and you get a beautiful chart. Customize with optional params.
Supports custom Y-axes with vertical zones (stack volume below price), domain clamping, reference lines, reference areas, and computed formula series.
IMPORTANT — Multi-axis guidance for different units: When combining metrics with different units (e.g., BTC supply + USD price, or a dimensionless ratio + USD), ALWAYS place them on separate Y-axes. Otherwise one metric will appear as a flat line near zero due to scale mismatch. Use list_metrics to check the "unit" field and assign metrics with different units to different axes (left vs right).
Examples:
Simple: render_chart({ metric: "price" })
Multi-metric: render_chart({ metrics: ["lth_supply", "sth_supply"], days: 730, style: "area" })
Template: render_chart({ template: "mvrv_ratio" })
Custom: render_chart({ metrics: [{ id: "price", axis: "right" }, { id: "lth_mvrv", axis: "left" }], days: 365, title: "Price vs MVRV" })
Multi-unit (separate axes): render_chart({ metrics: [{ id: "lth_supply", axis: "left" }, { id: "price", axis: "right" }], days: 365 })
Vertical zones: render_chart({ metrics: [{ id: "price", y_axis_id: "ax-p" }, { id: "volume", y_axis_id: "ax-v", style: "bar" }], y_axes: [{ id: "ax-p", side: "right", range: [20, 100] }, { id: "ax-v", side: "left", range: [0, 20] }] })
Reference line: render_chart({ metric: "lth_mvrv", reference_lines: [{ y: 3.5, label: "Overheated", stroke: "#ef4444", dash: "3 3" }] })
Reference area: render_chart({ metric: "lth_mvrv", reference_areas: [{ y1: 0, y2: 0.85, label: "Undervalued", fill: "#22c55e", fill_opacity: 0.15 }] })
Formula (ratio): render_chart({ metrics: [{ id: "lth_supply" }, { id: "sth_supply" }], formulas: [{ expression: "m1 / m2", label: "LTH/STH Ratio", color: "#f59e0b" }], days: 365 })
Formula on separate axis: render_chart({ metrics: [{ id: "lth_supply", axis: "left" }, { id: "sth_supply", axis: "left" }], formulas: [{ expression: "m1 / m2", label: "LTH/STH Ratio", y_axis_id: "ax-r" }], y_axes: [{ id: "ax-r", side: "right" }], days: 365 })
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days of history (default: 365) | |
| scale | No | Y-axis scale | linear |
| style | No | Default chart style for all metrics | |
| theme | No | Color theme: light or dark | light |
| title | No | Chart title (auto-generated if omitted) | |
| width | No | Image width in pixels | |
| format | No | Output format: png (image) or json (metadata) | png |
| height | No | Image height in pixels | |
| metric | No | Single metric ID (e.g., "price", "lth_supply", "lth_mvrv"). Use list_metrics to discover IDs. | |
| y_axes | No | Custom Y-axes with vertical zones. Use range to stack axes (e.g. volume [0,20], price [20,100]). Use domain_min/domain_max to clamp axis bounds. | |
| metrics | No | Multiple metrics. Pass as string array ["price", "lth_supply"] for simple, or objects for customization. | |
| overlay | No | Add BTC price overlay (subtle dashed line) | |
| end_date | No | End date (YYYY-MM-DD). Defaults to today. | |
| formulas | No | Computed series derived from metric data. Formulas reference metrics by position (m1, m2, ...) and support arithmetic (+, -, *, /). Use together with metrics to add derived indicators. | |
| template | No | Chart template ID. Templates: price, price_volume, market_cap, holder_supply, mvrv_ratio, realized_price, realized_cap, unrealized_pl, realized_pl, sopr, block_height, realized_volatility, coindays_destroyed, dormancy_flow, liveliness | |
| start_date | No | Start date (YYYY-MM-DD). Overrides days. | |
| reference_areas | No | Shaded reference zones between two Y values. Example: highlight when MVRV < 0.85 | |
| reference_lines | No | Horizontal reference lines on the chart |