--- name: glassnode description: Reliable and accurate crypto market and on-chain data for Bitcoin, Ethereum, and major assets from Glassnode, a pioneer in crypto data — pay per request in USDC via x402, with no API key or subscription required. Covers market data (price, marketcap, open interest, funding rates, futures/options volume, ETF and treasury balances, realized volatility, and more) and on-chain analytics (MVRV, SOPR, NUPL, exchange balances, long/short-term holder supply, active addresses, realized cap, profit/loss, and more). Discover what is available through metadata endpoints, then request the time series you need. tags: [glassnode, crypto, bitcoin, ethereum, market-data, on-chain, analytics, derivatives, funding-rates, open-interest, volatility, mvrv, sopr, nupl, exchange-balances, etf, treasury, addresses, supply, micropayments, x402, usdc, base] homepage: https://x402.glassnode.com metadata: version: "1.0" --- # Glassnode Glassnode provides institutional-grade **crypto market data** and **on-chain intelligence** for Bitcoin, Ethereum, and major assets. This skill exposes Glassnode over the [x402](https://docs.cdp.coinbase.com/x402/welcome) payment protocol: agents pay per request in USDC on Base — no API key, no subscription, no accounts. ## When to use Use this skill whenever the user needs reliable crypto data for analytics. The platform provides a holistic, fully integrated datalayer covering spot, futures, and options markets, as well as ETFs, DATs, and on-chain data. **Market data** - Spot markets: OHLC and close prices, realized price, price drawdowns, regional 30-day price changes - Market cap & valuation: market cap, realized cap, delta cap - Derivatives: open interest, funding rates, futures & options volume, liquidations, put/call ratios, estimated leverage - ETFs & treasuries: US spot ETF flows/balances, Purpose ETF AUM, corporate & government treasury balances - Volatility & ratios: realized volatility (1w–1y), NVT, SSR, Puell Multiple, Stock-to-Flow - Institutional holdings: government, corporate, and custodial/entity balances - Mining economics: hash rate, difficulty, miner revenue, thermocap **On-chain intelligence** - Valuation: MVRV, MVRV Z-Score, SOPR, NUPL, realized cap - Indicators: Reserve Risk, RHODL, NVT/NVTS, Liveliness, Dormancy, CDD, Accumulation Trend Score, Puell Multiple, Fear & Greed - Supply dynamics: long/short-term holder (LTH/STH) supply, HODL/age bands, active supply, issuance, lost/burned supply - Addresses & cohorts: active/new addresses, balance cohorts, holder accumulation/retention behavior - Transactions: transfer counts & volumes, exchange in/outflows, SegWit/Taproot adoption - Exchange & holder flows: exchange balances & net position change, supply concentration (Gini/Herfindahl) - Network & blockchain: block and UTXO statistics, transaction rates, fees - Fees & mempool: gas prices, transaction fees, mempool size & congestion - Staking & ecosystem: ETH 2.0 validators/deposits/staking volume, Lightning Network capacity, bridge & DeFi TVL ## Base URL ``` https://x402.glassnode.com ``` The x402 service mirrors the standard Glassnode API (`https://api.glassnode.com`) one‑to‑one. The path, query parameters, and response format are identical — the only differences are the subdomain and that requests are authorized by **payment** instead of an API key. Always trust the live `402` payment challenge for the authoritative price of a request. ## Core flow: discover, then request Work in two steps. First discover **what is available** via the metadata endpoints, then **request the data** via the metrics endpoints. ### 1. Discover — `GET /v1/metadata/*` ($0.01 per call) Use metadata to find the right asset, metric path, supported parameters, and allowed values **before** paying for data. - `GET /v1/metadata/assets` — list all supported assets (symbol, name, type, blockchains, tags). Optional CEL `filter`, e.g. `asset.semantic_tags.exists(tag,tag=='stablecoin')`. - `GET /v1/metadata/metrics` — list all available metric paths. Optional filters (`a`, `e`, `i`, `c`) narrow the catalog to metrics that support a given combination. - `GET /v1/metadata/metric?path=/addresses/count` — metadata for a single metric: supported parameters and their allowed values, available time range, documentation links, and descriptors (name, group, tags). The `path` parameter is **required**. ### 2. Request data — `GET /v1/metrics/{category}/{metric}` ($0.05 per call) Call the metric path using the parameters you discovered from metadata. The asset parameter `a` is **always required** — every metric request must specify an asset (e.g. `a=BTC`). ``` GET https://x402.glassnode.com/v1/metrics/market/mvrv?a=BTC&i=24h ``` ## Parameters Common query parameters (use the exact values reported by `/v1/metadata/metric`): | Param | Description | Example | |-------|-------------|---------| | `a` | **Required.** Asset symbol | `BTC`, `ETH` | | `i` | Resolution / interval | `24h`, `1w`, `1month` | | `c` | Currency for denominated values | `native`, `usd` | | `e` | Exchange (for exchange-specific metrics) | `binance`, `coinbase` | | `network` | Network / chain (for multi-chain metrics) | `eth`, `base` | | `s` | Start time (UNIX seconds, UTC) | `1746662400` | | `u` | End time (UNIX seconds, UTC) | `1749340800` | | `f` | Response format | `json`, `csv` | Supported resolutions are `24h`, `1w`, and `1month`. Not every metric supports every parameter — check `/v1/metadata/metric` for the exact set. The live `402` response also carries a machine-readable input schema per endpoint (an x402 Bazaar discovery extension: typed properties, enum values for bounded parameters, the required `a` parameter, and an example request), so an agent can determine how to call an endpoint programmatically without scraping this table. ## Errors: retryable vs fatal Every response carries a standard HTTP status. Use it to decide whether to retry or fix the request. Upstream errors are returned verbatim as a JSON `{ "message": ... }` body — read it before retrying. | Status | Meaning | Action | |--------|---------|--------| | `200` | Success | Use the body. | | `402 Payment Required` | Expected first response; no valid payment attached | **Retryable** — sign the payment and resend (your x402 client does this automatically). | | `400 Bad Request` | Invalid, missing, or unsupported parameter, metric, or value | **Fatal** — fix the request; consult `/v1/metadata/metric` for allowed values. Do not blind-retry. | | `404 Not Found` | Unknown metric path | **Fatal** — correct the path (list valid paths via `/v1/metadata/metrics`). | | `429 Too Many Requests` | Rate limited | **Retryable** — back off and retry. | | `5xx` (`500`, `502`, `503`) | Transient upstream or proxy error | **Retryable** — retry with exponential backoff. | Fatal (`400`/`404`) errors will not succeed on retry with the same request — change the metric, parameter, or value first. For example, an unsupported resolution: ``` GET /v1/metrics/addresses/count?a=BTC&i=10m ``` ```json { "message": "Resolution 10m is not allowed. Allowed resolutions: [24h, 1w, 1month]" } ``` Do not guess — when in doubt, inspect the metric via `/v1/metadata/metric` first, and let the error message tell you what to fix. ## Response format Metric responses are arrays of timestamped points. Single-value metrics use `v`: ```json [ { "t": 1782172800, "v": 63490.91 } ] ``` Multi-value metrics use a nested object `o`: ```json [ { "t": 1782172800, "o": { "10_100": 0.21, "100_1k": 0.26 } } ] ``` `t` is a UNIX timestamp in seconds (UTC). ## Pricing | Endpoint type | Price per request | |---------------|-------------------| | Metrics (`/v1/metrics/...`) | **$0.05 USDC** | | Metadata (`/v1/metadata/...`) | **$0.01 USDC** | - Payment network: **Base mainnet**, settled in **USDC**. - The live `402` response is authoritative for both the accepted network (`accepts[].network`) and the price — always read it before paying. - Pricing may change; always read the latest price from the live `402` response before paying. ## Payment (x402) 1. Send a normal `GET` request. If payment is required, the server responds with `402 Payment Required` and a `PAYMENT-REQUIRED` header describing the payment. 2. Your x402-aware client signs a USDC payment authorization and resends the request with a `PAYMENT-SIGNATURE` header. 3. The server returns the data. Use an x402-aware client (see the [x402 Quickstart for Buyers](https://docs.cdp.coinbase.com/x402/quickstart-for-buyers)) rather than plain `curl` for paid calls. If a plain request returns `402`, retry with the payment-aware client. ## Examples A typical discover-then-request flow: ```bash # 1. Discover metrics available for an asset (paid) curl "https://x402.glassnode.com/v1/metadata/metrics?a=BTC" # 2. Inspect a metric's supported parameters and allowed values (paid) curl "https://x402.glassnode.com/v1/metadata/metric?path=/market/mvrv" # 3. Request the data (paid) curl "https://x402.glassnode.com/v1/metrics/market/mvrv?a=BTC&i=24h" ``` ## Popular metrics High-signal metrics with the exact paths to call and when to reach for each. Append `?a=BTC` (or another asset); verify parameters via `/v1/metadata/metric`, and call `/v1/metadata/metrics` for the full catalog. - **Price (USD, close)** (`/v1/metrics/market/price_usd_close`) — spot close price; the baseline series for most analysis. - **Market cap (USD)** (`/v1/metrics/market/marketcap_usd`) — total network valuation. - **Futures volume** (`/v1/metrics/derivatives/futures_volume_daily_sum`) — gauge derivatives activity and liquidity; spikes confirm whether a sudden price move has real conviction and capital behind it. - **Open interest** (`/v1/metrics/derivatives/futures_open_interest_sum`) — track total outstanding futures/options contracts to read leverage changes and speculation. - **Funding rates** (`/v1/metrics/derivatives/futures_funding_rate_perpetual`) — identify leveraged directional bias (long vs. short); extreme values flag potential squeeze conditions. - **Realized volatility** (`/v1/metrics/market/realized_volatility_1_month`) — assess recent price turbulence and market risk to adjust position sizing and leverage. - **MVRV (Market Value to Realized Value)** (`/v1/metrics/market/mvrv`) — spot over/undervaluation by comparing market cap against realized cap (aggregate cost basis). - **SOPR (Spent Output Profit Ratio)** (`/v1/metrics/indicators/sopr`) — see whether spenders are realizing profit or capitulating at a loss. - **NUPL (Net Unrealized Profit/Loss)** (`/v1/metrics/indicators/net_unrealized_profit_loss`) — map macro sentiment (fear vs. greed) via the network's unrealized profit/loss state. - **Exchange balances** (`/v1/metrics/distribution/balance_exchanges`) — track coins held on exchanges; falling balances suggest accumulation/self-custody, rising suggests potential sell pressure. - **ETF & treasury balances** (`/v1/metrics/institutions/us_spot_etf_balances_all`, `/v1/metrics/treasuries/balance_companies`) — monitor institutional accumulation and structural demand: BTC held by spot ETFs and corporate treasuries. - **Long-term holder supply** (`/v1/metrics/supply/lth_sum`) — track "smart money" behavior, i.e. whether long-term holders are accumulating or distributing. - **Short-term holder supply** (`/v1/metrics/supply/sth_sum`) — supply held by recent buyers; a proxy for near-term speculative sell pressure. ## Availability This service exposes the Glassnode **Advanced** dataset plus full metadata. Rather than tracking exactly which metrics, assets, or resolutions are available, discover them at request time via `/v1/metadata/*`; anything unavailable on the plan surfaces as a descriptive error message that names what is required or allowed. - Metadata reference: - Endpoint reference: ## Discovery These endpoints are also discoverable through the [Coinbase x402 Bazaar](https://docs.cdp.coinbase.com/x402/bazaar), where agents can find and rank Glassnode metrics and metadata automatically. ## Invariants - Discover with `/v1/metadata/*` before requesting data; use the exact metric paths and parameter values it reports. - Metric data always comes from `/v1/metrics/{category}/{metric}`, and every metric request must include the required asset parameter `a`. - Trust the live `402` challenge for the authoritative price. - On an error, read the `message` and retry with an allowed metric, parameter, or value. - Use an x402-aware client; pay in USDC on Base.