Newhedge API Reference
Access real-time and historical data from any of the 2087 metrics that power Newhedge dashboards, charts, and company treasury pages. Our RESTful API provides programmatic access to comprehensive Bitcoin and financial market data.
Overview
The Newhedge API enables developers to integrate our extensive dataset into their applications, dashboards, and analysis tools. All endpoints return JSON responses with time-series data that mirrors what you see on our platform.
Each chart and treasury company exposes one or more metrics that can be queried individually. Metrics return either arrays of [timestamp, value] pairs or keyed objects, depending on the data structure.
Quick Start
To get started, you'll need an API token from your account settings. Once you have your token, you can make requests to any endpoint using the base URL:
GET /api/v2/metrics/:chart_slug/:metric_name?api_token=YOUR_TOKEN
GET /api/v2/companies/:company_slug/:metric_name?api_token=YOUR_TOKEN
Browse the available charts and companies in the sidebar to find the metrics you need. Each page shows all available metrics, sample requests, and response formats.
For Cursor, Claude, ChatGPT Code Interpreter, and MCP clients, see AI agents & MCP (markdown).
Resolutions
Series are daily (1d) by default. Advanced and Enterprise accounts may request finer buckets, coarsest to finest: 12h, 4h, 1h, 30m, 10m, block.
The older names (day1, hour12, hour4, hour1, 30mn, 10mn, block) are still accepted on input and name the same buckets, so an existing integration keeps working. Responses always carry the names above.
GET /api/v2/metrics/:chart_slug/:metric_name?resolution=1h&api_token=YOUR_TOKEN
Only the metrics endpoint accepts resolution. The company, news, and price endpoints are daily-only.
A resolution you cannot have is refused, not substituted. A value outside the list above is HTTP 400 naming the list. A finer bucket the calling account is not entitled to is HTTP 401 naming the requirement. A bucket this metric does not ingest is HTTP 400 naming what it does offer. You never receive 1d data in place of something you asked for — leave resolution off to get the daily series. X-Newhedge-Resolution still echoes what was served.
X-Newhedge-Available-Resolutions lists, coarsest to finest, exactly what the calling token may request for that metric, and any value it lists is served verbatim — so read it rather than probing each bucket. It is per-metric, not per-chart: two metrics on the same chart can offer different sets, because a metric only offers a bucket it actually ingests.
Before you call, metrics[].resolutions in the catalog lists what each metric ingests, and every per-chart page repeats it per metric. Most metrics are 1d only.
Definitions
A definition answers what the number is before you plot it: a plain value definition, its units, what the timestamp marks (which day or instant the point describes), the calendar it follows, and the revision policy — whether a stored point can change later, and inside what window.
Every metric whose chart has a published description has a definition. Declared definitions add the revision policy, the universe, and a methodology version; definition_source tells you which you got — declared or chart_description. A chart-description definition leaves revision_policy null rather than guessing it.
Ask for it with include=definition. Three endpoints accept it: /api/v2/metrics/:chart_slug/:metric_name (which returns the definition for the resolution it served, so timestamp_semantics and calendar follow X-Newhedge-Resolution), /api/v2/price/historical, and /api/v2/candles/btc (which returns the definition for the interval you requested).
GET /api/v2/metrics/:chart_slug/:metric_name?include=definition&api_token=YOUR_TOKEN
The response is then an envelope instead of the bare body — { "definition": { … }, "data": … } — where data is byte for byte what the same request returns without the parameter. Omit the parameter and nothing changes. Any other value is rejected with 400.
The same record is printed as a Definition block on each per-chart page and its .md variant, on the price and candles pages, and it is available through MCP by passing include_definition: true to get_metric, get_latest_value, or get_candles.
metrics[].has_definition in the catalog tells you before you call; the few metrics whose chart publishes no description return "definition": null. units_source says whether a unit was declared by Newhedge, taken from the unit the metric's own chart renders, or heuristic, meaning inferred from the metric name. A metric whose unit is not established publishes units: null rather than a guess, and carries no units_source. Treat a heuristic unit as a hint, not a contract.
These are definitions, not methodology. Newhedge does not publish how its own aggregates are computed.
Pagination
Responses are paged newest-first, on every resolution.
The most recent N observations. Maximum 5000.
Exclusive timestamp_ms cursor — returns observations strictly older than it.
A finer response is paged whether you ask or not: without limit you receive the newest 2500 observations. A 1d response is not, and returns the whole series unless you send limit or before.
Both parameters narrow a time series. A response with no single time axis, such as a hash keyed by venue or a labelled snapshot table, has nothing to cut on. It is returned whole, and both parameters are ignored rather than rejected.
A before that is not a positive epoch-millisecond timestamp is a 400. It is the one paging value we reject rather than ignore, because a page size has a sensible default and a cursor does not: ignoring a bad cursor returns the whole series to a caller who asked for a narrow slice of it.
Page backwards by sending the previous response's X-Newhedge-Next-Before as before, or by following the Link header. The Link URL omits api_token — re-attach your own token before requesting it.
Neither parameter widens a response. Both are applied after your plan's history window, so they can only narrow what you were already entitled to.
Finer series are sparse. A bucket with no observation is absent rather than forward-filled, so consecutive points are not always evenly spaced.
Response headers
Timestamps are epoch milliseconds.
X-Newhedge-Resolution — resolution actually served.
X-Newhedge-Available-Resolutions — resolutions this token may request for this metric.
X-Newhedge-Canonical-Slug: only when the requested chart_slug is a previous slug. It holds the current slug; the request still returns 200 with data.
X-Newhedge-Limit — page size used, when one applied.
X-Newhedge-Has-More — true when older observations remain.
X-Newhedge-From / X-Newhedge-To — oldest / newest timestamp in this page.
X-Newhedge-Available-From / X-Newhedge-Available-To — oldest / newest timestamp in the whole series.
X-Newhedge-Next-Before — cursor for the next older page.
Link — RFC 8288 rel="next", without api_token.
X-Newhedge-Points-Limited — true. X-Newhedge-Points-Limit — how many most recent points the chart returns to your plan.
X-Newhedge-Plan and X-Newhedge-Upgrade-Url are sent with them. The body is unchanged.
X-Newhedge-History-Truncated — true.
X-Newhedge-History-Window-Days — window length in days.
X-Newhedge-Plan — your plan. X-Newhedge-Upgrade-Url — pricing link for full history. The body is unchanged; see Errors and plan limits.
X-Newhedge-Attribution — the credit to show with the data, for example Source: Bitcoin Is Dead (bitcoindeaths.com). The response body is unchanged.
Link — RFC 8288 rel="via", the credited source's site. Joins any rel="next" value in the same header.
Errors and plan limits
Every refusal keeps its HTTP status and its error text. A plan or quota refusal adds fields beside error, so you can branch on code instead of matching the text. A field that does not apply to a refusal is absent.
code — plan_required, subscription_inactive, quota_exceeded.
required_plan — pro, advanced, enterprise. The lowest plan that has what you asked for. Absent on quota_exceeded.
current_plan — free, pro, advanced, enterprise. A lapsed subscription reads free.
feature — finer_resolution, intraday_candles, network_fees, price_websocket, onchain_tools. Present with plan_required.
upgrade_url — the pricing section of the plan to move to. Absent when there is none.
limit, resets_at — quota_exceeded only. The monthly allowance, and when the count resets (ISO 8601, UTC).
The plan does not include a finer resolution, a 5m or 1h candle interval, the network fee estimator, the on-chain MCP tools or the price WebSocket. error keeps its text.
The token matches an account with no API access today (free plan or lapsed subscription). error stays Invalid token. A token that matches no account gets only {"error":"Invalid token"}.
The monthly allowance is used up. error stays Monthly API calls limit reached. upgrade_url points to the next plan up and is absent on Enterprise. Allowances: Pro 100, Advanced 50000, Enterprise a custom limit (1000000 by default). The count resets on the first day of each month, 00:00 UTC.
History window. Pro tokens receive a rolling 365 days of history on the metrics, price history, candles and company endpoints. When the window removed at least one point from a response, the response carries X-Newhedge-History-Truncated: true, X-Newhedge-History-Window-Days, X-Newhedge-Plan and X-Newhedge-Upgrade-Url. The body is unchanged. For a Pro token X-Newhedge-Available-From is the start of the window, not of the stored series. MCP tools add a meta object beside the data under the same condition.
Chart point limit. A few charts also return only their most recent points to Pro tokens. When that limit removed points from a metrics response, the response carries X-Newhedge-Points-Limited: true, X-Newhedge-Points-Limit (the number of points returned), X-Newhedge-Plan and X-Newhedge-Upgrade-Url. The body is unchanged. MCP tools add points_limited: true and points_limit to the meta object under the same condition. Advanced and Enterprise tokens are never cut.
Data operations
How a published value can change, what a sign or a gap means, and what the API does not offer. The same facts are in the data_operations section of the catalog and the OpenAPI x-newhedge-data-operations extension.
Revisions by family
- Price reference and most daily series (
append_only): A stored day is not overwritten. - On-chain holder cohorts and cost basis (
append_only): A stored day is not rewritten by the regular daily update. - Spot Bitcoin ETF flows, holdings and totals observed on-chain (
full_replace): Every daily update re-applies the provider's full history, so holdings, flows and totals can restate on any day, not only the latest. - Spot Bitcoin ETF flows reported by the fund (
window_revised): The most recent 7 US trading days can be revised. Older days are not revisited. - Liquidations (
window_revised): A venue-day can be revised or added for up to 8 days after it ends. - Macro series from public economic data (
full_replace): The full series is re-pulled and replaced every day. Values are the latest vintage, forward-filled to a daily grid. Series published monthly or weekly (for example M2 or the federal funds rate) hold the latest published value forward on the daily grid until the next publication. - Treasury company holdings (
window_revised): Acquisitions are replaced from the provider on each run. Daily holdings are forward-filled and restate over 45 days. Holdings in US dollars equal holdings times the daily Bitcoin price and restate with them.
Per-metric detail is in the revision_policy and revision_notes of the definition (include=definition).
Sign conventions
- Per-venue liquidation series `bitcoin_liquidations_<venue>_long` are stored positive and `bitcoin_liquidations_<venue>_short` are stored negative.
- `liquidations_daily` and the intraday liquidation series are positive for both sides.
- ETF flows are positive for net inflow and negative for net outflow.
- Realized loss means coins spent below their cost basis. It is a loss amount, not a negative flow.
Zero versus absent
- A venue-day of liquidations is written, including 0, only when collection coverage for that day is at least 95%. Otherwise the day is absent. Absent is not 0 and not null.
- A fund that has not reported a US trading day has no point for that day yet. A 0 is a reported 0.
Publication lags
- A US trading day of ETF flows reported by the fund is final once 14 hours of the next UTC day have passed. Before then the latest day can hold only the funds reported so far.
- ETF flows observed on-chain run a few days behind the trading day.
- On-chain series are labelled with the UTC day they describe and appear after that day ends.
- Daily market series (total crypto market capitalisation, Bitcoin dominance and exchange trading volume) are labelled with the UTC day they describe and appear after that day ends, in the early hours of the next UTC day.
Refresh fields
- `update_frequency` is the refresh cadence of the series: `minute`, `intraday`, `hourly`, `daily`, `weekday`, `weekly`, `monthly`, `quarterly`, `irregular`, `manual`, `ended`. A series published once a day reports `daily` even when its source is polled more often.
- `ended` marks a series that has stopped updating for good. It stays in the catalog with its history, and its `next_expected_at` is null.
- `next_expected_at` is the next scheduled refresh attempt. It is not a promise of publication.
- Health and staleness are not exposed.
- There are no per-point revision flags. Use the revision policy of the metric definition.
News
- News rows are kept for 5 days.
- A row is a duplicate when its title or its link was already stored. The first version wins.
- Sentiment is automated keyword scoring, not an editorial judgment.
- The news endpoint has no paging.
Identifiers
- Metric names never change.
- A renamed chart keeps serving at its previous slug. The data response carries the header `X-Newhedge-Canonical-Slug` with the current slug, and only when it differs from the slug you requested. Chart pages answer a previous slug with a 301 to the current slug.
- An unknown chart slug returns 404 with `{"error":"Chart not found"}`. A `successor` field is added only when a removed chart has a successor. The 404 for a removed company adds `successor` the same way.
- A metric withdrawn on purpose returns 404 with `{"error":"Metric not found"}` plus `withdrawn`, `withdrawn_on` and `reason`. It has no replacement.
- Each news row has a stable `id`, the first key of the row.
Not offered
- Futures term structure by expiry.
- Order-book depth.
- Per-point revision flags.
What You Can Do
- Query real-time and historical Bitcoin metrics
- Access on-chain data, market indicators, and analytics
- Access Bitcoin treasury company holdings, acquisitions, and profile data
- Build custom dashboards and data visualizations
- Integrate Newhedge data into custom algorithms and research tools
- Monitor market trends and perform quantitative analysis
GET /api/v2/metrics/:chart_slug/:metric_name
GET /api/v2/companies/:company_slug/:metric_name
Authenticate
Send your 24-character API token via the `api_token` query param. Requests without it return 401.
Choose a dataset
Pick any chart or company from the sidebar. Each page exposes one or more metrics you can query individually.
Call the endpoint
Hit the chart or company metric or news endpoint to receive the JSON used on the site.
Curl
curl -X GET "https://newhedge.io/api/v2/metrics/bitcoin-dominance/btc_dominance?api_token=YOUR_TOKEN"Swap `YOUR_TOKEN` with the secret from your account. Replace the chart and metric to target other datasets.
Bitcoin Dominance (BTC.D)
[
[
1792972800000,
59.93
],
[
1793059200000,
60.1
],
[
1793145600000,
60.2
]
]Responses are either arrays of `[timestamp, value]` pairs or keyed hashes, depending on the metric.
API-ready datasets
These charts and companies expose metrics through the API. Select one on the left to view its metric list and sample responses.
On-Chain Analytics
Network activity, transaction volumes, address analytics, and blockchain health indicators.
Treasury Companies
Company profile, price, performance, treasury, holdings, and acquisition datasets.
Market Intelligence
Exchange volumes, trading pairs, liquidity metrics, and market dominance indicators.
Network Metrics
Network health, difficulty adjustments, hash rate, and network growth indicators.
Mining Analytics
Mining profitability, hash rate distribution, miner revenue, and pool dominance.
ETFs & Structured Products
Bitcoin ETF holdings, flows, premiums, discounts, and institutional product data.
Exchanges
Exchange trading volumes, liquidity metrics, exchange flows, and market share data.
Futures
Futures trading volumes, futures prices, and futures contracts.
Transactions
Transaction volumes, transaction fees, and transaction patterns.