# Blocklens — Full Documentation for LLMs

> Complete API reference with 56+ on-chain metrics.
> See [llms.txt](https://blocklens.co/llms.txt) for a compact overview.

## API Basics

- Base URL: `https://api.blocklens.co/v1`
- Auth: `Authorization: Bearer <API_KEY>`
- Get API key: https://blocklens.co/api-keys
- Response format: `{"success": true, "data": [...], "count": N, "timestamp": "ISO-8601"}`
- Error format: `{"success": false, "message": "Error description", "timestamp": "ISO-8601"}`
- Date format: YYYY-MM-DD
- Numeric values are returned as numbers (some large values may be strings — parse as float)

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

### Rate Limits
- Per-endpoint: 100 requests/minute (50/min for `/v1/utxo/history`)
- Per-user daily: Based on subscription tier
- Metrics registry endpoints (`/v1/metrics*`): 200 requests/minute, no auth required
- HTTP 429 returned when limits exceeded

## Endpoints

### Prices
`GET /v1/prices?symbol=BTC&limit=365`
Fields: date, symbol, price (USD), open, high, low, close, volume (USD), market_cap (USD)
Parameters: `symbol` (default: BTC), `start_date`, `end_date`, `limit` (1-10000, default: 100)

### Holder Supply
`GET /v1/holder/supply?limit=365`
Fields: date_processed, lth_supply (BTC), sth_supply (BTC), circulating_supply (BTC)
Parameters: `start_date`, `end_date`, `limit` (1-10000, default: 100)

### Holder Valuation
`GET /v1/holder/valuation?limit=365`
Fields: date_processed, realized_cap (USD), realized_price (USD), lth_realized_cap, sth_realized_cap, lth_realized_price, sth_realized_price, lth_mvrv, sth_mvrv, lth_unrealized_pl (Pro+), sth_unrealized_pl (Pro+)
Parameters: `start_date`, `end_date`, `limit` (1-10000, default: 100)

### Holder Profit
`GET /v1/holder/profit?limit=365`
Fields: date_processed, lth_realized_pl (USD), sth_realized_pl (USD), lth_sopr (ratio), sth_sopr (ratio)
Parameters: `start_date`, `end_date`, `limit` (1-10000, default: 100)
Tier: Pro+ only

### Age Cohort Metrics
`GET /v1/cohort/metrics/{cohort}?limit=365`
Also available as: `GET /v1/cohort/metrics?cohort={cohort}`
Cohorts: 24h, 1d_1w, 1w_1m, 1m_3m, 3m_6m, 6m_12m, 1y_2y, 2y_3y, 3y_5y, 5y_7y, 7y_10y, 10y_plus
Fields: date_processed, supply_{cohort} (BTC), realized_cap_{cohort} (USD), realized_price_{cohort} (USD)
Parameters: `start_date`, `end_date`, `limit` (1-10000, default: 100)

### UTXO History
`GET /v1/utxo/history?date_processed=2026-01-15&limit=1000`
Fields: date_processed, cohort_date, token_amount (BTC), usd_value (USD)
Parameters: `date_processed` (specific date), `cohort_start`, `cohort_end`, `limit` (1-50000, default: 1000)
Rate limit: 50 requests/minute

### Metrics Catalog
`GET /v1/metrics?active_only=true` (no auth required)
Returns all metric definitions with metadata, endpoints, units, and access grades.
Parameters: `category` (price|supply|valuation|profit), `grade` (0|1|2), `active_only` (default: true)

### Metrics Categories
`GET /v1/metrics/categories?active_only=true` (no auth required)
Returns category names, metric counts, and metric ID lists.

### Single Metric Definition
`GET /v1/metrics/{metric_id}` (no auth required)
Returns full definition for a single metric by ID (e.g., `lth_supply`, `price`).

### Latest Metrics Snapshot
`GET /v1/metrics/latest`
Returns the most recent data point from all major categories (prices, supply, valuation, profit) in a single call.

---

## All Metrics Reference

### Price (3 metrics)

#### Price (`price`)
- Endpoint: `/v1/prices`
- Field: `price`
- Unit: USD
- Tier: Free
- The daily market price of Bitcoin in USD, sourced from major spot exchanges. Price serves as the baseline for all valuation and profitability calculations on the platform.

#### Market Cap (`market_cap`)
- Endpoint: `/v1/prices`
- Field: `market_cap`
- Unit: USD
- Tier: Free
- Total market capitalization of Bitcoin, calculated as Price x Circulating Supply. Provides a high-level view of Bitcoin's relative size and is used for institutional benchmarking and cross-asset comparison.

#### Volume (`volume`)
- Endpoint: `/v1/prices`
- Field: `volume`
- Unit: USD
- Tier: Free
- Total USD value of Bitcoin traded across major exchanges in a 24-hour period. High volume confirms price trend conviction, while low volume suggests weak momentum and potential reversals.

### Supply (15 metrics)

#### Circulating Supply (`circulating_supply`)
- Endpoint: `/v1/holder/supply`
- Field: `circulating_supply`
- Unit: BTC
- Tier: Free
- Total number of Bitcoin that have ever been mined and are currently in circulation.

#### LTH Supply (`lth_supply`)
- Endpoint: `/v1/holder/supply`
- Field: `lth_supply`
- Unit: BTC
- Tier: Free
- Total Bitcoin held by Long-Term Holders (LTH), weighted using a logistic function centered at 155 days. Rising LTH supply indicates accumulation and holder conviction; falling LTH supply signals distribution, often seen near market tops.

#### STH Supply (`sth_supply`)
- Endpoint: `/v1/holder/supply`
- Field: `sth_supply`
- Unit: BTC
- Tier: Free
- Total Bitcoin held by Short-Term Holders (STH), weighted as the complement of the LTH weight (1 - W_LTH). Rising STH supply indicates increased speculative activity and new market participants; falling STH supply means coins are maturing into long-term holdings.

#### Supply <24h (`supply_24h`)
- Endpoint: `/v1/cohort/metrics/24h`
- Field: `supply_24h`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs younger than 24 hours

#### Supply 1d-1w (`supply_1d_1w`)
- Endpoint: `/v1/cohort/metrics/1d_1w`
- Field: `supply_1d_1w`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 1 day to 1 week

#### Supply 1w-1m (`supply_1w_1m`)
- Endpoint: `/v1/cohort/metrics/1w_1m`
- Field: `supply_1w_1m`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 1 week to 1 month

#### Supply 1m-3m (`supply_1m_3m`)
- Endpoint: `/v1/cohort/metrics/1m_3m`
- Field: `supply_1m_3m`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 1 month to 3 months

#### Supply 3m-6m (`supply_3m_6m`)
- Endpoint: `/v1/cohort/metrics/3m_6m`
- Field: `supply_3m_6m`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 3 months to 6 months

#### Supply 6m-12m (`supply_6m_12m`)
- Endpoint: `/v1/cohort/metrics/6m_12m`
- Field: `supply_6m_12m`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 6 months to 12 months

#### Supply 1y-2y (`supply_1y_2y`)
- Endpoint: `/v1/cohort/metrics/1y_2y`
- Field: `supply_1y_2y`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 1 year to 2 years

#### Supply 2y-3y (`supply_2y_3y`)
- Endpoint: `/v1/cohort/metrics/2y_3y`
- Field: `supply_2y_3y`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 2 years to 3 years

#### Supply 3y-5y (`supply_3y_5y`)
- Endpoint: `/v1/cohort/metrics/3y_5y`
- Field: `supply_3y_5y`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 3 years to 5 years

#### Supply 5y-7y (`supply_5y_7y`)
- Endpoint: `/v1/cohort/metrics/5y_7y`
- Field: `supply_5y_7y`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 5 years to 7 years

#### Supply 7y-10y (`supply_7y_10y`)
- Endpoint: `/v1/cohort/metrics/7y_10y`
- Field: `supply_7y_10y`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 7 years to 10 years

#### Supply 10y+ (`supply_10y_plus`)
- Endpoint: `/v1/cohort/metrics/10y_plus`
- Field: `supply_10y_plus`
- Unit: BTC
- Tier: Free
- Bitcoin held in UTXOs aged 10 years or more

### Valuation (32 metrics)

#### Realized Cap (`realized_cap`)
- Endpoint: `/v1/holder/valuation`
- Field: `realized_cap`
- Unit: USD
- Tier: Free
- Total realized capitalization — the sum of all UTXOs valued at the price when they last moved. Represents the aggregate cost basis of the network.

#### Realized Price (`realized_price`)
- Endpoint: `/v1/holder/valuation`
- Field: `realized_price`
- Unit: USD
- Tier: Free
- Realized capitalization divided by circulating supply. Represents the average cost basis per BTC across the network.

#### LTH Realized Cap (`lth_realized_cap`)
- Endpoint: `/v1/holder/valuation`
- Field: `lth_realized_cap`
- Unit: USD
- Tier: Free
- Aggregate USD value of all LTH coins, each valued at the price when last moved on-chain. Represents the collective cost basis of long-term holders and provides a fundamental "fair value" floor for Bitcoin.

#### STH Realized Cap (`sth_realized_cap`)
- Endpoint: `/v1/holder/valuation`
- Field: `sth_realized_cap`
- Unit: USD
- Tier: Free
- Aggregate USD value of all STH coins, each valued at the price when last moved on-chain. Represents the collective cost basis of recent market participants. Rapid growth indicates significant new capital inflows.

#### LTH Realized Price (`lth_realized_price`)
- Endpoint: `/v1/holder/valuation`
- Field: `lth_realized_price`
- Unit: USD
- Tier: Free
- Average acquisition price of all coins held by Long-Term Holders (LTH Realized Cap / LTH Supply). Acts as a key dynamic support level in bull markets — price historically rarely falls below it during healthy uptrends.

#### STH Realized Price (`sth_realized_price`)
- Endpoint: `/v1/holder/valuation`
- Field: `sth_realized_price`
- Unit: USD
- Tier: Free
- Average acquisition price of all coins held by Short-Term Holders (STH Realized Cap / STH Supply). Serves as a critical trend pivot: bull markets maintain price above STH realized price, bear markets below.

#### LTH MVRV (`lth_mvrv`)
- Endpoint: `/v1/holder/valuation`
- Field: `lth_mvrv`
- Unit: ratio
- Tier: Free
- Ratio of Bitcoin's market price to the average LTH cost basis (Market Price / LTH Realized Price). Values above 1 indicate LTH aggregate profit; values above 3.5 have historically marked overheated cycle tops. Below 1 signals generational buying opportunities.

#### STH MVRV (`sth_mvrv`)
- Endpoint: `/v1/holder/valuation`
- Field: `sth_mvrv`
- Unit: ratio
- Tier: Free
- Ratio of Bitcoin's market price to the average STH cost basis (Market Price / STH Realized Price). Oscillates around 1 more frequently than LTH MVRV, making it useful for shorter-term trend signals and capitulation detection.

#### Realized Price <24h (`realized_price_24h`)
- Endpoint: `/v1/cohort/metrics/24h`
- Field: `realized_price_24h`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs younger than 24 hours

#### Realized Price 1d-1w (`realized_price_1d_1w`)
- Endpoint: `/v1/cohort/metrics/1d_1w`
- Field: `realized_price_1d_1w`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 1 day to 1 week

#### Realized Price 1w-1m (`realized_price_1w_1m`)
- Endpoint: `/v1/cohort/metrics/1w_1m`
- Field: `realized_price_1w_1m`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 1 week to 1 month

#### Realized Price 1m-3m (`realized_price_1m_3m`)
- Endpoint: `/v1/cohort/metrics/1m_3m`
- Field: `realized_price_1m_3m`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 1 month to 3 months

#### Realized Price 3m-6m (`realized_price_3m_6m`)
- Endpoint: `/v1/cohort/metrics/3m_6m`
- Field: `realized_price_3m_6m`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 3 months to 6 months

#### Realized Price 6m-12m (`realized_price_6m_12m`)
- Endpoint: `/v1/cohort/metrics/6m_12m`
- Field: `realized_price_6m_12m`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 6 months to 12 months

#### Realized Price 1y-2y (`realized_price_1y_2y`)
- Endpoint: `/v1/cohort/metrics/1y_2y`
- Field: `realized_price_1y_2y`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 1 year to 2 years

#### Realized Price 2y-3y (`realized_price_2y_3y`)
- Endpoint: `/v1/cohort/metrics/2y_3y`
- Field: `realized_price_2y_3y`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 2 years to 3 years

#### Realized Price 3y-5y (`realized_price_3y_5y`)
- Endpoint: `/v1/cohort/metrics/3y_5y`
- Field: `realized_price_3y_5y`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 3 years to 5 years

#### Realized Price 5y-7y (`realized_price_5y_7y`)
- Endpoint: `/v1/cohort/metrics/5y_7y`
- Field: `realized_price_5y_7y`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 5 years to 7 years

#### Realized Price 7y-10y (`realized_price_7y_10y`)
- Endpoint: `/v1/cohort/metrics/7y_10y`
- Field: `realized_price_7y_10y`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 7 years to 10 years

#### Realized Price 10y+ (`realized_price_10y_plus`)
- Endpoint: `/v1/cohort/metrics/10y_plus`
- Field: `realized_price_10y_plus`
- Unit: USD
- Tier: Free
- Average cost basis of UTXOs aged 10 years or more

#### Realized Cap <24h (`realized_cap_24h`)
- Endpoint: `/v1/cohort/metrics/24h`
- Field: `realized_cap_24h`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs younger than 24 hours

#### Realized Cap 1d-1w (`realized_cap_1d_1w`)
- Endpoint: `/v1/cohort/metrics/1d_1w`
- Field: `realized_cap_1d_1w`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 1 day to 1 week

#### Realized Cap 1w-1m (`realized_cap_1w_1m`)
- Endpoint: `/v1/cohort/metrics/1w_1m`
- Field: `realized_cap_1w_1m`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 1 week to 1 month

#### Realized Cap 1m-3m (`realized_cap_1m_3m`)
- Endpoint: `/v1/cohort/metrics/1m_3m`
- Field: `realized_cap_1m_3m`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 1 month to 3 months

#### Realized Cap 3m-6m (`realized_cap_3m_6m`)
- Endpoint: `/v1/cohort/metrics/3m_6m`
- Field: `realized_cap_3m_6m`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 3 months to 6 months

#### Realized Cap 6m-12m (`realized_cap_6m_12m`)
- Endpoint: `/v1/cohort/metrics/6m_12m`
- Field: `realized_cap_6m_12m`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 6 months to 12 months

#### Realized Cap 1y-2y (`realized_cap_1y_2y`)
- Endpoint: `/v1/cohort/metrics/1y_2y`
- Field: `realized_cap_1y_2y`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 1 year to 2 years

#### Realized Cap 2y-3y (`realized_cap_2y_3y`)
- Endpoint: `/v1/cohort/metrics/2y_3y`
- Field: `realized_cap_2y_3y`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 2 years to 3 years

#### Realized Cap 3y-5y (`realized_cap_3y_5y`)
- Endpoint: `/v1/cohort/metrics/3y_5y`
- Field: `realized_cap_3y_5y`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 3 years to 5 years

#### Realized Cap 5y-7y (`realized_cap_5y_7y`)
- Endpoint: `/v1/cohort/metrics/5y_7y`
- Field: `realized_cap_5y_7y`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 5 years to 7 years

#### Realized Cap 7y-10y (`realized_cap_7y_10y`)
- Endpoint: `/v1/cohort/metrics/7y_10y`
- Field: `realized_cap_7y_10y`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 7 years to 10 years

#### Realized Cap 10y+ (`realized_cap_10y_plus`)
- Endpoint: `/v1/cohort/metrics/10y_plus`
- Field: `realized_cap_10y_plus`
- Unit: USD
- Tier: Free
- Realized capitalization of UTXOs aged 10 years or more

### Profit (6 metrics)

#### LTH Unrealized P/L (`lth_unrealized_pl`)
- Endpoint: `/v1/holder/valuation`
- Field: `lth_unrealized_pl`
- Unit: USD
- Tier: Pro+
- Aggregate unrealized (paper) profit or loss of all LTH coins at current market prices. Large positive values may incentivize profit-taking; negative values are rare and have historically marked capitulation zones.

#### STH Unrealized P/L (`sth_unrealized_pl`)
- Endpoint: `/v1/holder/valuation`
- Field: `sth_unrealized_pl`
- Unit: USD
- Tier: Pro+
- Aggregate unrealized (paper) profit or loss of all STH coins at current market prices. More volatile than LTH unrealized P/L and closely reflects current market sentiment — negative values signal fear and potential capitulation.

#### LTH Realized P/L (`lth_realized_pl`)
- Endpoint: `/v1/holder/profit`
- Field: `lth_realized_pl`
- Unit: USD
- Tier: Pro+
- Daily aggregate profit or loss realized by Long-Term Holders when spending coins on-chain. Large positive values indicate active profit-taking (late bull market); large negative values indicate capitulation (cycle bottoms).

#### STH Realized P/L (`sth_realized_pl`)
- Endpoint: `/v1/holder/profit`
- Field: `sth_realized_pl`
- Unit: USD
- Tier: Pro+
- Daily aggregate profit or loss realized by Short-Term Holders when spending coins on-chain. Positive spikes indicate local profit-taking; negative spikes indicate panic selling and often mark local bottoms.

#### LTH SOPR (`lth_sopr`)
- Endpoint: `/v1/holder/profit`
- Field: `lth_sopr`
- Unit: ratio
- Tier: Pro+
- Ratio of the USD value of LTH coins at spending time to their value at creation time. SOPR > 1 means profit-taking; SOPR < 1 means capitulation. In bull markets, SOPR bouncing off 1.0 confirms support.

#### STH SOPR (`sth_sopr`)
- Endpoint: `/v1/holder/profit`
- Field: `sth_sopr`
- Unit: ratio
- Tier: Pro+
- Ratio of the USD value of STH coins at spending time to their value at creation time. More sensitive than LTH SOPR and crosses 1.0 more frequently. Persistent values above 1 confirm healthy bull market conditions.