# Blocklens

> Bitcoin on-chain analytics platform — 127 metrics, REST API, MCP server, interactive charts.

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 15 tools covering all Blocklens analytics — no API key needed for demo-tier data.

- 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/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 (127 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 (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

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