API Reference

BASE URL: HTTPS://API.SENTIMENTFX.ORG

API Key Get your key from the dashboard → API Access. Required by Pro and Data plans.

Authentication

All API endpoints require an API key passed as the X-API-Key request header. Keys are tied to your SentimentFX account and are available on Pro and Data plans.

Generate your API key from the dashboard → API Access section. Sign in at app.sentimentfx.org, then scroll to the API Access panel at the bottom of the page.

Plan	Included Calls/mo	Overage
Pro	1,000	£0.01 / call via Stripe
Data	5,000	£0.01 / call via Stripe

Example Request

# Curl
curl https://api.sentimentfx.org/v1/sentiment/BTC \
  -H "X-API-Key: sfx_your_api_key_here"

# Python
import requests
res = requests.get(
    "https://api.sentimentfx.org/v1/sentiment/BTC",
    headers={"X-API-Key": "sfx_your_api_key_here"}
)

# JavaScript
const res = await fetch(
    "https://api.sentimentfx.org/v1/sentiment/BTC",
    { headers: { "X-API-Key": "sfx_your_api_key_here" } }
)

Sentiment

GET /v1/sentiment/{ticker}

Returns sentiment-scored headlines for the specified ticker. Default 25 headlines = 1 call. Every additional 25 = 1 more call.

Parameter	Type	Default	Description
ticker	string	—	42 supported across crypto, FX, stocks, ETFs, commodities
limit	integer	25	Number of headlines to return

Response

{
  "ticker": "BTC",
  "limit": 25,
  "calls_used": 1,
  "data": [
    {
      "date": "2026-04-27T12:00:00",
      "title": "Bitcoin hits new yearly high amid ETF inflows",
      "source": "CoinDesk",
      "sentiment_score": 0.6821,
      "sentiment_label": "positive"
    }
  ]
}

▶ Try it

Ticker Limit

Summary

GET /v1/summary/{ticker}

Returns daily averaged sentiment scores. Default 30 days = 30 calls.

Parameter	Type	Default	Description
ticker	string	—	42 supported across crypto, FX, stocks, ETFs, commodities
days	integer	30	Number of days of history

Response

{
  "ticker": "BTC",
  "days": 30,
  "calls_used": 30,
  "data": [
    {
      "date": "2026-04-27",
      "avg_sentiment": 0.2341,
      "article_count": 12,
      "label": "positive"
    }
  ]
}

▶ Try it

Ticker Days

Prices

GET /v1/prices/{ticker}

Returns daily closing prices in the asset's native currency: GBP for crypto, exchange rates for FX pairs, USD for stocks, ETFs and commodity futures. Default 30 days = 30 calls.

Parameter	Type	Default	Description
ticker	string	—	42 supported across crypto, FX, stocks, ETFs, commodities
days	integer	30	Number of days of history

Response

{
  "ticker": "BTC",
  "days": 30,
  "calls_used": 30,
  "data": [
    {
      "date": "2026-04-27T00:00:00",
      "close_price_gbp": 72841.50,
      "volume": 18294830293.0
    }
  ]
}

▶ Try it

Ticker Days

Correlation

GET /v1/correlation/{ticker}

Returns the Pearson correlation between sentiment shifts and next-day price returns, with a 95% confidence interval and signal strength rating. Always 1 call.

Parameter	Type	Default	Description
ticker	string	—	42 supported across crypto, FX, stocks, ETFs, commodities

Response

{
  "ticker": "BTC",
  "calls_used": 1,
  "window_days": 180,
  "sample_size": 87,
  "primary_signal": {
    "type": "sentiment_shift_vs_next_day_return",
    "correlation": 0.241,
    "p_value": 0.0241,
    "ci_95": [0.033, 0.431],
    "strength": "weak",
    "direction": "positive (momentum)"
  },
  "interpretation": "Sentiment shifts show a weak positive (momentum) signal (r=0.241, p=0.0241, n=87)"
}

Methodology: Correlates daily sentiment shifts (deviation from 7-day rolling average) against next-day price returns over a 180-day window. Strength is classified on |r| magnitude: strong (|r|≥0.25), weak (|r|≥0.10), or inconclusive (|r|<0.10). CI uses Fisher z-transform.

▶ Try it

Ticker

Error Codes

Code	Meaning
401	Missing or invalid API key
403	Plan does not include API access
404	No data found for ticker
429	Rate limit exceeded
500	Server error

Methodology

HOW SENTIMENTFX SCORES, ANALYSES, AND SIGNALS

Sentiment Scoring

Every headline is scored using FinBERT, a BERT-based transformer model fine-tuned on financial news. The model outputs three probabilities: positive, negative, and neutral.

We compute the score as:

score = positive_probability − negative_probability

This gives a value in the range −1.0 to +1.0, where +1 is maximally positive, −1 is maximally negative, and 0 is neutral. We deliberately exclude the neutral label from the score — only the relative weight of positive vs negative drives it.

The daily sentiment figure shown on the dashboard is the mean score across all headlines published for that ticker on that day.

Score Range	Label
> +0.3	Strongly Bullish
+0.1 to +0.3	Bullish
−0.1 to +0.1	Neutral
−0.3 to −0.1	Bearish
< −0.3	Strongly Bearish

Sentiment Shift

Raw sentiment level is a lagging, noisy signal — markets tend to price in known information quickly. What is more useful is the change in sentiment relative to recent baseline.

We define the daily sentiment shift as:

shift = today's sentiment − 7-day rolling average

A positive shift means today's news is meaningfully more positive than the recent norm. A negative shift means the tone has deteriorated relative to baseline. This is the primary input to the correlation and signal models.

The 7-Day Trend shown on the dashboard compares the average sentiment of the last 7 days to the 7 days before that — a broader directional indicator separate from the daily shift.

Correlation Analysis

We compute a Pearson correlation between daily sentiment shifts and the next-day price return (close-to-close in GBP) over a rolling 180-day window. A minimum of 30 overlapping data points is required to return a result.

r = corr(sentiment_shift[d], price_return[d+1])

The result includes:

Field	Description
correlation (r)	Pearson r. Range −1 to +1. Closer to ±1 = stronger relationship.
p_value	Probability the result is due to chance. <0.05 = statistically significant.
ci_95	95% confidence interval via Fisher z-transform. Narrower = more reliable.
sample_size (n)	Number of overlapping trading days used in the calculation.

We also compute a momentum baseline (autocorrelation of price returns) to test whether the sentiment signal adds value beyond simple price momentum. primary_beats_momentum: true means it does.

Signal Strength

Signal strength reflects the statistical reliability of the historical sentiment-price correlation model for a given ticker — not the size of today's specific shift.

Label	Criteria	Meaning
Strong	\|r\| ≥ 0.25	Consistent relationship across the analysis window
Weak	\|r\| ≥ 0.10	Detectable relationship but modest in magnitude
Inconclusive	\|r\| < 0.10	No meaningful directional relationship found

Strength is based on correlation magnitude (|r|), consistent with how practitioners use rolling correlations in quantitative finance. The p-value is included in the response for reference. Tickers with fewer headlines (SOL, XRP, DOGE) tend to have noisier correlations and are more likely to be inconclusive.

Correlation is not causation. Signal strength tells you how consistent the historical relationship has been — it does not guarantee future price moves.

Shift Percentile

The shift percentile ranks today's sentiment shift against all historical daily shifts for that ticker over the last 180 days.

Percentile	Label	Meaning
≥ 90th	Extreme	Larger than 90% of all recorded shifts — rare
75th – 89th	Significant	Top quartile of historical shifts
50th – 74th	Moderate	Above-median shift
< 50th	Minor	Below-median — normal day-to-day noise

A high shift percentile means today's sentiment move is unusually large relative to history — which, combined with a reliable signal model, increases confidence in the direction. A minor shift in isolation has limited predictive value even if the historical correlation is strong.

Momentum vs Contrarian

The direction label describes how sentiment shifts have historically related to price moves for a given ticker.

Label	r sign	Meaning
Momentum	Positive (+)	Positive sentiment shifts tend to be followed by price rises. Negative shifts tend to be followed by drops.
Contrarian	Negative (−)	Positive sentiment shifts tend to be followed by price drops — the market may already have priced in the optimism. Negative shifts may precede rebounds.

Neither direction is inherently better — both can be traded if the correlation is strong enough. The direction is determined purely by the sign of the Pearson r value over the analysis window.