Bitcoin API for AI Agents & MCP
Connect your AI client through MCP or the REST API.
For Bitcoin OHLCV data, request open, high, low, close and volume through REST or the MCP get_candles tool. The reference documents supported intervals and BTC/USDT units.
The public /api/v2/catalog lists datasets, units, resolutions and request templates. No token required.
Teach any agent the API in < 30 seconds
You can answer questions about Bitcoin on-chain, market, mining, and macro
metrics by calling the Newhedge API.
Discovery (free, no auth):
GET https://newhedge.io/api/v2/catalog
The catalog returns every available chart and metric, with `slug`, `name`,
`shape`, `units`, `update_frequency`, a `sample`, and a
`request_url_template`. Use it to pick the right metric before issuing any
data call.
Auth: every data call needs your key (24-character alphanumeric, paid plans
only: Pro, Advanced or Enterprise). Send it as `Authorization: Bearer YOUR_TOKEN`
(recommended). `X-API-Key: YOUR_TOKEN` and the `api_token` query parameter also
work. Two different keys in one request are refused with HTTP 400 and
`code: conflicting_credentials`.
Endpoints:
curl -H "Authorization: Bearer YOUR_TOKEN" "https://newhedge.io/api/v2/metrics/{chart_slug}/{metric_name}"
curl -H "Authorization: Bearer YOUR_TOKEN" "https://newhedge.io/api/v2/news/{query_type}"
curl -H "Authorization: Bearer YOUR_TOKEN" "https://newhedge.io/api/v2/price/historical"
curl -H "Authorization: Bearer YOUR_TOKEN" "https://newhedge.io/api/v2/price/live"
curl -H "Authorization: Bearer YOUR_TOKEN" "https://newhedge.io/api/v2/candles/btc?interval=1d"
Bitcoin OHLCV data: open, high, low, close and volume.
Resolution: metric series are daily by default. Advanced and Enterprise tokens
may add &resolution=12h|4h|1h|30m|10m|block, coarsest to
finest, on the metrics endpoint only. The older names
(day1|hour12|hour4|hour1|30mn|10mn|block) are still accepted and mean the same buckets.
A value outside that list is HTTP 400 naming the list. A finer bucket this
token is not entitled to is HTTP 401. A bucket this metric does not ingest is
HTTP 400 naming what it does offer. Leave resolution off for the daily series.
Read X-Newhedge-Resolution for what was served, and
X-Newhedge-Available-Resolutions for what this token may request. Finer
responses page newest-first via &limit= and an exclusive &before= cursor.
Quota: per token, by plan. See `quotas` in https://newhedge.io/api/v2/catalog
for the numbers. Only a successful response spends a call; any refused or
failed call is free. Cache catalog responses; metric data
updates daily for most series.
Errors: a 404 or 400 carries `code`, up to 3 `did_you_mean` suggestions,
`catalog_url` and `docs_url`. Read `did_you_mean` and retry instead of guessing.
A renamed chart still answers 200 at its old slug with `X-Newhedge-Canonical-Slug`
and `Deprecation`; move to the new slug.
Project-level rule
Save the prompt above as .cursor/rules/newhedge-api.mdc or a Claude Code memory note. Then ask in chat:
Show me the Mayer Multiple over the last 90 days as a chart, and tell me
whether the current value is above or below its long-term average.
The agent should fetch /api/v2/catalog, find the mayer-multiple slug, call /api/v2/metrics/mayer-multiple/{metric_name}, and plot the last 90 entries. If your editor supports OpenAPI tool imports, point it at https://newhedge.io/api/v2/openapi.json for typed parameter hints.
Catalog-driven Python snippet
Requires Python with requests and matplotlib.
import os
import requests
import matplotlib.pyplot as plt
from datetime import datetime
API_TOKEN = os.environ["NEWHEDGE_API_TOKEN"]
# 1. Discover (no token required).
catalog = requests.get("https://newhedge.io/api/v2/catalog", timeout=15).json()
# 2. Find the chart you want.
mayer = next(
chart
for group in catalog["groups"]
for chart in group["charts"]
if chart["slug"] == "mayer-multiple"
)
metric = mayer["metrics"][0]
# The template shows the query form; send the key in a header instead.
url = metric["request_url_template"].split("?")[0]
# 3. Fetch and plot.
headers = {"Authorization": f"Bearer {API_TOKEN}"}
series = requests.get(url, headers=headers, timeout=15).json()
xs = [datetime.utcfromtimestamp(p[0] / 1000) for p in series[-180:]]
ys = [p[1] for p in series[-180:]]
plt.plot(xs, ys)
plt.title(f"{mayer['extended_name']} - last 180 days")
plt.show()
Paste the index, then chat
When tool use isn't available, paste the contents of https://docs.newhedge.io/llms.txt (a few KB) at the top of the conversation and tell Claude:
The above is the index for the Newhedge API. When I ask you about Bitcoin
on-chain or market metrics, identify the right metric from the catalog,
show me the request URL with `YOUR_TOKEN` placeholder, and explain how to
interpret the response shape. Don't hallucinate data — only describe what
the API returns.
For longer sessions paste llms-full.txt instead (everything inlined, larger). Both files are regenerated whenever a chart or metric changes.
Model Context Protocol (hosted)
Connect an MCP-aware client to the Newhedge v2 API with JSON-RPC POST and your existing API key (same three key sources as REST: Authorization: Bearer, X-API-Key, or the api_token query parameter). Use https:// in production.
Endpoint: POST https://newhedge.io/api/v2/mcp with Authorization: Bearer YOUR_TOKEN. Send the key on every request, including initialize and tools/list. A client that cannot set a header may keep the key in the URL as ?api_token=YOUR_TOKEN. Two different keys in one request are refused with a JSON-RPC error whose data.code is conflicting_credentials. An error inside a tool result carries the same hint fields as REST (code, did_you_mean, catalog_url, docs_url), and a get_metric call for a renamed chart returns data with canonical_slug and deprecated_slug: true. Tools: list_metrics, search_metrics, get_metric, get_latest_value, compare_metrics, list_companies, get_company_profile, get_company_metric, get_candles, get_api_docs, list_groups, get_market_snapshot, get_derivatives_data. Discovery and docs tools cost no monthly quota; each data fetch counts like one REST metrics call (compare_metrics counts one per spec). compare_metrics takes at most 20 specs per call. MCP data tools serve daily (1d) resolution unless a tool takes a resolution argument. get_metric and get_latest_value take an optional resolution (1d, 12h, 4h, 1h, 30m, 10m, block) with the same rules as GET /api/v2/metrics/...: a finer bucket needs an Advanced or Enterprise token and a metric that ingests it, and costs the same quota unit. A refusal is a tool error that carries the plan fields (code, required_plan, current_plan, feature, upgrade_url) or the message naming what the metric does offer. A finer get_metric result carries resolution and has_more; convert the oldest returned at to epoch milliseconds, subtract one, and send it as end_ms to walk back. Without the argument nothing changes. For Bitcoin OHLCV data, get_candles accepts an interval of 5m, 1h, 1d; intraday intervals require Advanced or Enterprise.
Derivatives data tool. get_derivatives_data reads one dataset of the derivatives data API, the same data as its REST routes under /api/v2/derivatives, described on the Derivatives Data API page.
get_derivatives_data. Arguments:dataset; optionalstart,end,exchange,side,min_amount_usd,limit,cursor,window,direction,block_only,maturity,strike_min,strike_max,instrument_name,option_type,min_premium_usd,min_notional. Monthly quota: one unit per call that returns data.- Datasets:
basis-term-structure,liquidation-events,futures-term-structure,futures-term-structure-daily,basis-by-exchange,funding-contracts,funding-heatmap,futures-contracts,perp-contracts,liquidation-heatmap,futures-trades,options-gex,options-oi-by-strike,options-max-pain,options-put-call,options-iv-surface,options-iv-rv,options-iv-term-lapse,options-iv-zscores,options-realized-vol,options-chain,options-expiries,options-flows,options-strategies,options-oi-changes,options-trades,options-instrument-history.datasettakes one of them. - Access: Tokens that hold the Derivatives API add-on. Enterprise includes it.
- Quota: each call costs one unit only when it returns data. Errors, refused calls and answers with nothing found cost nothing.
- Size: a result larger than 256 KB is an error that names the arguments that narrow the call.
- Paging: a tape dataset returns
next_cursorwhen more rows exist; send it back ascursor. - Rate limit: A token may make at most 120 derivatives data calls per minute, shared by the REST routes and this tool, and at most 2 uncached reads at once. A call over either limit returns an error and costs no quota.
Claude custom connector, Claude Code and Claude Desktop
Register the server as a remote server with a request header. In Claude Code, run the command below. For a project .mcp.json or a Claude Desktop remote-server entry, use the JSON block. A connector form that takes only a URL cannot set a header: use https://newhedge.io/api/v2/mcp?api_token=YOUR_TOKEN there.
claude mcp add --transport http newhedge https://newhedge.io/api/v2/mcp --header "Authorization: Bearer YOUR_TOKEN"
{
"mcpServers": {
"newhedge": {
"type": "http",
"url": "https://newhedge.io/api/v2/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
Cursor
{
"mcpServers": {
"newhedge": {
"url": "https://newhedge.io/api/v2/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
Continue
{
"mcpServers": [
{
"name": "newhedge",
"url": "https://newhedge.io/api/v2/mcp",
"requestOptions": { "headers": { "Authorization": "Bearer YOUR_TOKEN" } }
}
]
}
Price WebSocket
Live BTC/USD ticks over a WebSocket. Enterprise accounts with the price WebSocket feature only.
Connect in two steps so the key never appears in the WebSocket URL. First trade your key for a one-time ticket. This call spends nothing from your monthly allowance.
curl -sS -X POST -H "Authorization: Bearer YOUR_TOKEN" "https://newhedge.io/api/v2/cable/ticket"
{"ticket":"TICKET_VALUE","expires_in":60,"url":"wss://ws.newhedge.io/cable?ticket=TICKET_VALUE"}
Then open the url from the answer: wss://ws.newhedge.io/cable?ticket=TICKET_VALUE. A ticket is valid for 60 seconds and for one connection only. Ask for a new ticket for each connection or reconnect. The ticket call takes the key any of the three ways. A browser cannot set a header on a WebSocket, so request the ticket from your own server. The older form wss://ws.newhedge.io/cable?api_token=YOUR_TOKEN still works.
Subscribe to the PriceChannel channel. The default stream is the weighted aggregate. Add source (aggregate, binance, coinbase, kraken) to the subscription identifier for one venue. Each tick carries price, fetched_at and sequence.
{"command":"subscribe","identifier":"{\"channel\":\"PriceChannel\",\"source\":\"binance\"}"}
A paid token without the feature is accepted, then sent one error frame, and the subscription is rejected:
{"type":"error","error":"Price WebSocket requires an Enterprise plan","code":"plan_required","required_plan":"enterprise","current_plan":"advanced","feature":"price_websocket","upgrade_url":"https://newhedge.io/pricing#enterprise"}
An unknown source is sent {"type":"error","error":"Invalid source. Use aggregate, binance, coinbase, or kraken.","code":"invalid_source"} and the subscription is rejected. A token that matches no account, or an account with no API access (free or lapsed), is refused at connection with no frame.
Common errors
Parameters & responses
No key in the request. Send Authorization: Bearer YOUR_TOKEN (or X-API-Key, or ?api_token=).
The request carried two different keys, for example an Authorization header and another api_token. The body is {"error":"Conflicting API credentials in request","code":"conflicting_credentials"}. Send one key. The same key sent twice is accepted.
Token is wrong or not 24 chars, or the account has no API access today. A real token on a free or lapsed account also carries "code":"subscription_inactive", required_plan and current_plan; a token that matches no account carries only error. Regenerate at your API settings, or restore a Pro, Advanced or Enterprise plan.
Token has hit its monthly cap, which depends on the plan (quotas in the catalog). The body adds "code":"quota_exceeded", limit, resets_at and, below Enterprise, an upgrade_url. Wait until resets_at, or move to the plan in upgrade_url. An MCP tool call returns the same body as an isError result at HTTP 200.
Wrong slug or metric name, or a metric withdrawn on purpose (the body then adds withdrawn, withdrawn_on and reason, and the metric has no replacement). The body carries code (chart_not_found, metric_not_found) and up to 3 did_you_mean spellings: use one, or re-fetch the catalog and pick a valid (chart_slug, metric_name) pair from x-newhedge-allowed-pairs in the OpenAPI spec. A successor field, when present, is the slug to request instead.
The path under /api/v2 is not an endpoint. The body carries "code":"endpoint_not_found" and the nearest real paths in did_you_mean. No key is needed and no call is spent.
Use a code from the currencies array in the catalog.
The token is not entitled to finer buckets. The body adds "code":"plan_required", required_plan, current_plan, feature and upgrade_url. Leave resolution off for the daily series, or upgrade.
The series, or the finer resolution you asked for, needs the Derivatives API add-on. The body is {"error":"This data requires the Derivatives API add-on, available on an Advanced plan"} and adds "code":"plan_required", "required_plan":"derivatives_addon", "feature":"derivatives_addon", current_plan and upgrade_url. No call is spent. Add the add-on from API settings, or request a series Advanced includes.
The metric does not ingest that bucket. The message lists what it does offer, as does X-Newhedge-Available-Resolutions on any 200 — every value listed is served verbatim.
The value was misspelled; matching is exact. Use one of the listed names.