Newhedge API Reference

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.

The older names (day1, hour12, hour4, hour1, 30mn, 10mn) 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.

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.

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