# Blocklens

> Bitcoin on-chain analytics platform — 210+ metrics, REST API, MCP server, interactive charts, heatmap rendering.

Blocklens provides Bitcoin on-chain analytics derived from self-hosted full nodes with raw UTXO-level analysis since the genesis block (2009). Also tracks Bitcoin ETF data across 27 global ETF products.

## AI Integration (MCP)

**Recommended way to access Blocklens data from AI assistants:**

### Remote MCP Server (No Install)

Connect directly to the hosted endpoint — no packages, no local setup:

- **Endpoint:** `https://mcp.blocklens.co` (Streamable HTTP transport)
- **Claude.ai:** Settings → Connectors → Add → URL: `https://mcp.blocklens.co`
- **Claude Desktop (via mcp-remote):**
```json
{
  "mcpServers": {
    "blocklens": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.blocklens.co"]
    }
  }
}
```

### Local Install (Alternative)

Install via npm for stdio-based MCP clients:
```
npx blocklens-mcp-server
```

Or add to your MCP config (Claude Desktop, Cursor, etc.):
```json
{
  "mcpServers": {
    "blocklens": {
      "command": "npx",
      "args": ["blocklens-mcp-server"]
    }
  }
}
```

Both methods provide the same 19 tools covering all Blocklens analytics — no API key needed for demo-tier data.

### Key MCP Capabilities
- **render_chart**: Generate PNG chart images with any metric combination
- **Cycle overlay charts**: Compare Bitcoin cycles using `x_axis: "day_offset"` — all cycles start at Day 0 for visual comparison. Metrics: cycle_ath_1..5, cycle_low_1..4, cycle_halving_1..4
- **Heatmap rendering**: Cost basis distribution heatmap via `heatmap_id: "cost-basis-distribution"` with viridis/soft/plasma color scales
- **Formulas**: Compute derived metrics (ratios, differences) with `m1 / m2` expressions
- **Custom axes**: Multi-axis charts with vertical zones, reference lines, shaded areas

- Remote endpoint: https://mcp.blocklens.co
- npm: https://www.npmjs.com/package/blocklens-mcp-server
- GitHub: https://github.com/blocklens/blocklens-mcp-server

## REST API

Base URL: `https://api.blocklens.co/v1`
Auth: `Authorization: Bearer <API_KEY>` (get a key at https://blocklens.co/api-keys)
OpenAPI spec: `https://api.blocklens.co/docs`

### Tiers
- **Demo** (no auth): 60 days history, basic metrics (grade 0), no API key needed
- **Free** (account required): 365 days history, basic metrics (grade 0)
- **Pro** ($50/mo): Unlimited history, all metrics (grade 0-1), API access, 10,000 requests/day
- **Enterprise** ($900/mo): Unlimited history, all metrics (grade 0-2), API access, 100,000 requests/day

### Endpoints

- `GET /v1/prices` — BTC price (OHLC), market cap, volume
- `GET /v1/holder/supply` — LTH/STH supply, circulating supply, age-band supply
- `GET /v1/holder/valuation` — Realized cap/price, MVRV, thermo cap, delta cap, balanced price, and more
- `GET /v1/holder/profit` — Realized/unrealized P/L, SOPR, NUPL
- `GET /v1/cohort/metrics/{cohort}` — Age cohort supply, realized cap, realized price
- `GET /v1/utxo/history` — UTXO set breakdown by age cohort
- `GET /v1/coindays` — Coin Days Destroyed, liveliness, vaultedness, dormancy
- `GET /v1/etf/aggregate` — ETF holdings, AUM, flows, dominance, realized price
- `GET /v1/etf/registry` — ETF product metadata (ticker, issuer, country)
- `GET /v1/blockchain` — Block height, blocks mined
- `GET /v1/cycle-boundaries` — Bitcoin halving cycle start/end dates and durations
- `GET /v1/metrics` — List all available metrics with definitions (no auth)
- `GET /v1/metrics/categories` — Metric categories with counts (no auth)
- `GET /v1/metrics/{metric_id}` — Single metric definition (no auth)
- `GET /v1/metrics/latest` — Latest snapshot across all categories

### Common Query Parameters
- `limit` (int, 1-10000): Number of daily data points (default: 100)
- `start_date` / `end_date` (YYYY-MM-DD): Date range filter
- `symbol` (string): Cryptocurrency symbol (default: "BTC", prices endpoint only)

### Response Format
```json
{"success": true, "data": [...], "count": N, "timestamp": "ISO-8601"}
```

### Rate Limits
- Per-endpoint: 100 requests/minute (50/min for UTXO history)
- Per-user daily: Based on tier
- HTTP 429 returned when limits exceeded

### Example
```
curl "https://api.blocklens.co/v1/holder/supply?limit=30"
```

## Available Metrics (210+ total)

### Market Data (27)
Price, OHLC, market cap, volume, drawdown from ATH, cycle performance comparisons, realized volatility (1W/2W/1M/3M/6M/1Y)

### Supply (16)
Circulating supply, LTH/STH supply, 12 age-band supply cohorts (24h through 10y+), cost basis distribution heatmap (Enterprise)

### Valuation (48)
Realized cap/price, MVRV (aggregate + LTH/STH), thermo cap, delta cap/price, average cap, balanced price, investor cap, Mayer multiple, BPT, VPT, MFI, OBV, ADL, 12 age-band realized prices, 12 age-band realized caps

### Profitability (12)
NUPL (aggregate + LTH/STH), unrealized P/L, realized P/L, SOPR (aggregate + LTH/STH)

### Coin Days (11)
CDD, net coin days, accumulated coin days, liveliness, vaultedness, binary CDD, supply-adjusted CDD, transferred price, transfer volume, dormancy, dormancy flow

### ETF Analytics (11)
Total BTC in ETFs, total AUM, daily net flow, cumulative flow (BTC), cumulative money flow (USD), ETF realized price, US spot ETF realized price, BTC dominance, US ETF holdings, premium/discount

### Exchanges & Derivatives (50+)
Funding rates, open interest, and liquidation data across major exchanges (Binance, Bybit, OKX, etc.)

### Digital Asset Treasuries (30+)
Corporate and sovereign BTC holdings, realized prices by entity type, aggregate flows

## Links

- [Website](https://blocklens.co)
- [API docs](https://api.blocklens.co/docs)
- [Metric documentation](https://docs.blocklens.co)
- [Pricing](https://blocklens.co/pricing)
- [MCP Server](https://github.com/blocklens/blocklens-mcp-server)
- [Full API reference for LLMs](https://blocklens.co/llms-full.txt)