Use Newhedge with AI agents
Copy-paste prompts and code snippets for Cursor, Claude Code, ChatGPT Code Interpreter, plain Claude.ai, and MCP clients.
The fastest way to teach an LLM what Newhedge offers is to point it at the free machine catalog at https://newhedge.io/api/v2/catalog. One HTTP call, no token, returns every chart, every metric, sample values, units, update frequency, and the full request URL template — enough context for the agent to answer most questions on its own.
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 `?api_token=YOUR_TOKEN` (24-character
alphanumeric, paid plans only: Pro, Advanced or Enterprise). Header auth is not supported.
Endpoints:
GET https://newhedge.io/api/v2/metrics/{chart_slug}/{metric_name}?api_token=YOUR_TOKEN
GET https://newhedge.io/api/v2/news/{query_type}?api_token=YOUR_TOKEN
GET https://newhedge.io/api/v2/price/historical?api_token=YOUR_TOKEN
GET https://newhedge.io/api/v2/price/live?api_token=YOUR_TOKEN
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. Cache catalog responses; metric data
updates daily for most series.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
requests and matplotlib are pre-installed, so this runs as-is.
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]
url = metric["request_url_template"].replace("{token}", API_TOKEN)
# 3. Fetch and plot.
series = requests.get(url, 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_token query parameter (same auth model as REST). Use https:// in production.
Endpoint: POST https://newhedge.io/api/v2/mcp?api_token=YOUR_TOKEN. Tools: list_metrics, search_metrics, get_metric, get_latest_value, compare_metrics, get_company_metric, get_candles, get_api_docs, list_groups, get_market_snapshot. 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.
Claude Code / Desktop
Claude Desktop: add the block below to claude_desktop_config.json. Claude Code uses the same server URL; see Claude Code’s MCP docs for the exact config file path on your OS.
{
"mcpServers": {
"newhedge": {
"url": "https://newhedge.io/api/v2/mcp?api_token=YOUR_TOKEN"
}
}
}Cursor
{
"mcpServers": {
"newhedge": {
"url": "https://newhedge.io/api/v2/mcp?api_token=YOUR_TOKEN"
}
}
}Continue
{
"mcpServers": [
{
"name": "newhedge",
"url": "https://newhedge.io/api/v2/mcp?api_token=YOUR_TOKEN"
}
]
}Price WebSocket
Live BTC/USD ticks over a WebSocket. Enterprise accounts with the price WebSocket feature only.
Endpoint: wss://ws.newhedge.io/cable?api_token=YOUR_TOKEN. 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
No api_token query param. Append ?api_token=....
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.
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). 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.
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 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.