BTC vs news API

Bitcoin price and the tone of crypto news coverage, on one timeline, with the correlation between them. Same open access as the rest of this API: no key, no signup, no rate plan.

bash

curl "https://freenewsapi.ai/v1/btc/correlation?interval=day&from=now-90d"

What this is

Two series, aligned hour by hour and served together:

Price — 2,774 BTC/USDT candles: open, high, low, close, volume, trade count.
Tone — 78,026 crypto news articles from the news corpus behind this API, each classified as positive, neutral or negative for crypto prices. Coverage runs 2026-06-09 to 2026-09-07.

Everything is derived from data this project already collects. The price comes from the public Binance klines endpoint; the articles come from the same corpus that /v1/search queries. Nothing here is bought, licensed or scraped from a competitor.

How tone is assigned

Each article is judged on headline and lead paragraph only. The body is not fetched: for a market signal the lead carries almost all of the information, and including bodies would triple the cost for the same answer.

The question the classifier answers is what does this imply for crypto prices, not whether the event is pleasant. Hacks, bans, exchange failures, ETF outflows, lawsuits and enforcement are bearish. Approvals, inflows, records, institutional adoption and favourable regulation are bullish. Explainers, how-to guides, product launches and directionless price predictions are neutral.

100.0% of articles are labelled by a language model. The remainder fall back to a multilingual financial lexicon, and every article says which method produced its label in the labelled_by field. Articles are judged in their own language; the corpus is not English-only.

Relevance is decided on the headline and lead too. A stock-market roundup that mentions bitcoin once in passing is dropped rather than counted as crypto coverage — otherwise the tone series would track general market news instead of crypto.

What the data shows

Over the last 91 days, net tone and the daily return move together at r = +0.110. Shifting one series against the other locates the peak:

Shift	r	Reading	Pairs
-4 d	+0.119	price leads news	86
-3 d	+0.090	price leads news	87
-2 d	+0.072	price leads news	88
-1 d	+0.262	price leads news	89
+0 d	+0.110	same day	90
+1 d	-0.070	news lead price	89
+2 d	+0.018	news lead price	88
+3 d	-0.079	news lead price	87
+4 d	-0.083	news lead price	86

The strongest correlation sits at -1 days (r = +0.262). A peak on the negative side means the press is reacting to the price rather than anticipating it. The positive side, where news would lead price, collapses towards zero within a day.

This is a descriptive indicator, not a trading signal. Both series are autocorrelated, correlation is not causation, and a relationship measured over one quarter need not hold in the next. Compute it yourself over your own window — that is what the endpoint is for.

GET /v1/btc/summary

Current price, recent moves, today's tone and the exact extent of the dataset. Cheap enough to poll.

bash

curl "https://freenewsapi.ai/v1/btc/summary"

Returns price, change_pct for 1h/24h/7d/30d, tone_today and a coverage block giving the first and last timestamp of both series plus the share labelled by model.

GET /v1/btc/series

The flagship call: price and tone on one row per period. This is what you want if you are charting or backtesting.

bash

curl "https://freenewsapi.ai/v1/btc/series?interval=day&from=now-30d"

intervalstringdefault day

hour, day or week. Weeks start on Monday.

fromstringdefault to minus 30 days

Start of the window. Accepts YYYY-MM-DD, YYYY-MM-DDTHH:MM:SSZ, unix seconds, or a relative value such as now-7d, now-48h, now-2w.

tostringdefault now

End of the window, exclusive.

Each row carries the OHLC candle, return_pct against the previous period, the positive/neutral/negative counts, their net, and direction — agrees when the sign of the price move matches the sign of the tone, diverges when they disagree, flat when either is zero.

GET /v1/btc/correlation

Pearson correlation between net tone and the price return, computed at a range of shifts so you can see which side leads.

bash

curl "https://freenewsapi.ai/v1/btc/correlation?interval=day&from=now-90d&max_shift=6"

intervalstringdefault day

hour, day or week.

max_shiftintegerdefault 4

Widest shift to test, 1–24, measured in intervals. A shift of -1 correlates today’s tone against yesterday’s return.

from / tostringdefault last 90 days

Window bounds, same formats as elsewhere.

Returns same_period_r, the full by_shift table with the number of pairs behind each figure, and best — the shift with the largest absolute correlation. Correlation is null when fewer than six pairs survive the window, rather than a number computed from too little data.

GET /v1/btc/price

Just the candles, if you only need price.

bash

curl "https://freenewsapi.ai/v1/btc/price?interval=hour&from=now-48h"

Aggregating to day or week keeps the true open of the first hour and the true close of the last, with the high and low taken across the whole bucket. The hours field says how many hourly candles went into the bucket, so you can spot a partial period at the edge of the window.

GET /v1/btc/sentiment

Just the tone counts, if you already have price data of your own.

bash

curl "https://freenewsapi.ai/v1/btc/sentiment?interval=day&from=now-30d"

GET /v1/btc/news

The individual articles behind the aggregates, each with its label. Use it to audit the classification or to read what actually moved a day.

bash

curl "https://freenewsapi.ai/v1/btc/news?from=now-7d&label=neg&sort=score_asc&size=5"

labelstringdefault all

pos, neu or neg.

hoststringdefault all

Comma-separated hostnames, up to 50.

langstringdefault all

Comma-separated language codes, up to 50.

qstring

Substring match on the headline. Literal, not a query language — % and _ match themselves.

sortstringdefault date

date, date_asc, score or score_asc. Sorting by score surfaces the most bullish or most bearish items.

size / offsetintegerdefault 20 / 0

Up to 100 per page, offset up to 9900.

Each result gives sentiment, the model score on a −2…+2 scale, and labelled_by. When the label came from the lexicon the model score is null — the two scales are different and are deliberately not mixed into one number. The lexicon's own score and the terms it matched are exposed separately as lexicon_score and lexicon_terms.

GET /v1/btc/sources

Which outlets, languages or countries drive the coverage, and which way they lean.

bash

curl "https://freenewsapi.ai/v1/btc/sources?by=host&from=now-30d&top=20"

bystringdefault host

host, lang or country.

topintegerdefault 25

How many buckets, 1–200.

mean_score is the average model score for that bucket, which reads as an editorial lean: consistently above zero means the outlet reports crypto in bullish terms.

Shared parameters

from and to behave identically on every endpoint and accept four formats:

Format	Example	Meaning
Date	`2026-07-01`	Midnight UTC
Date and time	`2026-07-01T14:30:00Z`	Exact instant, UTC
Unix seconds	`1782950400`	Exact instant
Relative	`now-30d`	Hours, days or weeks back from now

All timestamps in responses are UTC, ISO 8601, with a trailing Z. to is always exclusive.

Recipes

Does tone predict tomorrow?

bash

curl "https://freenewsapi.ai/v1/btc/correlation?interval=day&from=now-90d" \
  | jq '.by_shift[] | select(.shift == 1)'

A shift of +1 asks whether today’s tone anticipates tomorrow’s move. On the data so far it does not.

Days when the press disagreed with the market

bash

curl "https://freenewsapi.ai/v1/btc/series?interval=day&from=now-90d" \
  | jq '.series[] | select(.direction == "diverges")'

The most bearish headlines of the week

bash

curl "https://freenewsapi.ai/v1/btc/news?from=now-7d&sort=score_asc&size=10" \
  | jq -r '.results[] | "\(.score) \(.title)"'

Limits and caveats

Price is BTC/USDT on Binance. Other venues differ slightly. The tone series covers crypto coverage broadly, not bitcoin alone, so it includes Ethereum, exchanges, regulation and stablecoins.
Sentiment is a judgement, not a measurement. Spot-check it with /v1/btc/news before relying on it.
Article volume is uneven. Weekends run about a third lighter than weekdays, so a raw net is not comparable across days of the week without normalising by articles.
The corpus has gaps. Where the upstream news archive published empty batches, article counts dip for reasons that have nothing to do with the news. Check articles per bucket before reading a low net as quiet coverage.
Windows that yield more than 5,000 points are refused with a 400 and a message telling you to use a coarser interval.
Rate limit is the same 20 requests per second per IP as the rest of the API, and responses carry Access-Control-Allow-Origin: * so browser code can call this directly.

Errors

Bad input returns 400 with a detail string that says what was wrong and what was expected. 503 means the dataset is momentarily unavailable; retry. There is no 401 or 429 for authentication, because there is no authentication.

bash

curl "https://freenewsapi.ai/v1/btc/price?interval=month"

response

{"detail":"interval must be one of: hour, day, week"}