# Blocklens

> Bitcoin on-chain analytics platform — 177 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 18 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/futures/oi` — Futures open interest aggregate (total OI, delta, exchange count)
- `GET /v1/funding/aggregate` — Aggregate funding rate (OI-weighted across 7 exchanges)
- `GET /v1/funding/exchange?exchange=binance` — Per-exchange funding rate (requires Pro)
- `GET /v1/funding/exchanges` — List exchanges with funding data
- `GET /v1/oi/exchange?exchange=binance` — Per-exchange open interest (requires Pro)
- `GET /v1/oi/exchanges` — List exchanges with OI data
- `GET /v1/dat/aggregate` — Digital Asset Treasuries aggregate (total BTC, companies, flows)
- `GET /v1/dat/registry` — List tracked companies/entities with metadata
- `GET /v1/dat/entity?id=1` — Per-entity treasury data (holdings, USD value, net flow)
- `GET /v1/dat/company/{id}/holdings` — Historical holdings for a specific company
- `GET /v1/dat/stats` — DAT summary statistics
- `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 (171 total)

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

### Market Data — Futures (22)
Aggregate: annualized funding rate (OI-weighted), futures open interest, OI daily change (USD/%), active exchange count.
Per-exchange (7 exchanges each): funding rate by exchange, open interest by exchange.
Exchanges: Binance, Bybit, OKX, Deribit, Bitget, Gate.io, Hyperliquid.

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

### Profit & Loss (12)
NUPL (aggregate + LTH/STH), unrealized P/L, realized P/L, SOPR (aggregate + LTH/STH), supply in profit %

### 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 (18)
Aggregate (11): total BTC, 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.
Per-fund (7): BTC holdings, net flow, cumulative flow, market share, realized cap, realized price, AUM — parameterized by ticker (IBIT, FBTC, etc.)

### Digital Asset Treasuries (17)
Aggregate: total BTC, total companies, net change, cumulative money flow, % of supply, public/government/private BTC, total USD.
Per-entity (7): holdings, USD value, % of supply, net flow, cumulative flow, market share, AUM — parameterized by entity ID.

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