Clearer API data definitions and data operations

API

View as Markdown

What's new

The API definitions now answer the questions a data governance review asks: what the number is, what its units and sign are, what its timestamp marks, and whether a published value can change later. A new Data operations section on the API introduction page, in the catalog, and in the OpenAPI document lists the revision behavior of each metric family, the sign conventions, the difference between a zero and an absent day, publication lags, and what the API does not offer.

A renamed chart keeps working at its previous slug. The API answers with the data and adds the header X-Newhedge-Canonical-Slug with the current slug, and chart pages redirect to the current slug. Metric names never change. Each news row now has a stable id.

Methodology

Version 2026-10-09.

  • Holder cohorts. Long-term holders (LTH) hold outputs at least 150 days old. Short-term holders (STH) hold outputs younger than 150 days. Earlier chart text said 155 days and has been corrected. Cohorts are UTXO-based and not entity-adjusted.
  • Realized profit and loss. These are trailing 24 hour sums taken at the day's final block. Realized loss counts coins spent below their cost basis. The change in 30 days of long-term and short-term supply is a trailing 30 day change in bitcoin. Short-term realized profit, loss, and net now come from the same data source as the long-term and total series, so they are additive: short-term plus long-term equals the total, and short-term profit minus short-term loss equals short-term net. Realized loss is a positive magnitude.
  • NUPL and MVRV. NUPL equals 1 - 1/MVRV, where MVRV is the spot price divided by the realized price. NUPL is served multiplied by 100, so its scale is 0 to 100. The spot price is the data provider's on-chain price estimate at the day's final block, not the Newhedge exchange sample.
  • Cost basis. The per coin percentiles are weighted by unspent bitcoin. The per dollar percentiles are weighted by US dollars at creation. The 5th percentile and the minimum are 0 by provider design, because coins created before 2010-08-16 (about 18.6% of supply) are priced at $0. The provider does not state how it interpolates between levels. The realized price and the investor price (also called capitalized price) differ by design.
  • Active addresses. Active addresses are the unique addresses that sent or received bitcoin on the UTC day. Each day is now labelled with the day it describes, and history was restated once. The per block address activity averages are a different metric.
  • Liquidations. Per venue short series are stored negative and long series positive. The daily total and the intraday series are positive for both sides. A venue-day is written, including 0, only when collection coverage is at least 95%. Otherwise the day is absent. Values can be revised for 8 days.
  • Options volume. Version 2026-09-14. Late-arriving trades can revise the most recent three UTC days of the daily options volume series.
  • ETF flows reported by the fund. Version 2026-10-06. The latest US trading day can be partial until every fund has reported, and the most recent seven US trading days can be revised.
  • ETF flows observed on-chain. The daily update re-applies the provider's full history, so holdings, flows, and totals can restate on any day.
  • Macro series. The full series is re-pulled and replaced every day as the latest vintage, forward-filled to a daily grid. Series published monthly or weekly hold the latest published value forward until the next publication.
  • Treasury companies. Price data is daily OHLCV in the local currency of the listing and is adjusted for splits and not adjusted for dividends. A listing quoted in GBX is in pence. The company-data snapshot gives the exchange, currency, and ISIN. Acquisition and holdings restatement rules, and the acquisition field dictionary, are on the company docs pages.
  • News. Rows are kept for 5 days. Duplicates are found by title or link and the first version is kept. Sentiment is automated keyword scoring, not editorial.