Authentication

All API endpoints require an API key passed as the X-API-Key request header. Get one below — no card, no account, 1,000 free calls every 30 days.

Already subscribed? Keys generated from the dashboard are linked to your account and pick up your plan's monthly allowance automatically.

# 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

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

Summary

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

Prices

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

Correlation

{
  "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)"
}

MCP — Claude, Cursor & other AI clients

SentimentFX also speaks the Model Context Protocol, so Claude Code, Claude.ai desktop, Cursor, Cline and any other MCP-compatible client can call the sentiment tools natively without you writing HTTP-plumbing code. Same X-API-Key, same billing, same rate limits — you just point the client at a URL.

Endpoint: https://api.sentimentfx.org/mcp

Auth: X-API-Key: sfx_... header, or Authorization: Bearer sfx_... for clients that can only send a bearer token (get a free key).

Tools exposed

Claude Code

Run once in a terminal. --scope user makes the tools available in every project; leave it out to add them to the current project only:

claude mcp add --transport http --scope user sentimentfx https://api.sentimentfx.org/mcp --header "X-API-Key: sfx_your_key_here"

Check it with claude mcp list, or /mcp inside a session. Start a new session and Claude will discover the six tools. Try "What's Bitcoin sentiment looking like this week?".

Cursor / Windsurf

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project) for Cursor, or to Windsurf's mcp_config.json:

{
  "mcpServers": {
    "sentimentfx": {
      "url": "https://api.sentimentfx.org/mcp",
      "headers": { "X-API-Key": "sfx_your_key_here" }
    }
  }
}

Cline

In the MCP Servers panel, open the Configure tab and click Configure MCP Servers. Cline needs "type": "streamableHttp": without it, Cline falls back to the older SSE transport, which this server doesn't offer.

{
  "mcpServers": {
    "sentimentfx": {
      "type": "streamableHttp",
      "url": "https://api.sentimentfx.org/mcp",
      "headers": { "X-API-Key": "sfx_your_key_here" }
    }
  }
}

Claude API (custom apps)

Use the Messages API's MCP connector. It needs the server in mcp_servers and a matching mcp_toolset in tools. The connector can't send custom headers, so your key goes in authorization_token, which arrives as Authorization: Bearer:

from anthropic import Anthropic
client = Anthropic()
resp = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20", "server-side-fallback-2026-07-01"],
    fallbacks="default",
    mcp_servers=[{
        "type": "url",
        "url": "https://api.sentimentfx.org/mcp",
        "name": "sentimentfx",
        "authorization_token": "sfx_your_key_here",
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "sentimentfx"}],
    messages=[{"role": "user", "content": "Rank the top 5 tickers by 7-day sentiment shift."}],
)
print("".join(b.text for b in resp.content if b.type == "text"))

Every MCP tool call counts against the same allowance as the equivalent /v1/* HTTP call — check usage on the dashboard's API Access panel.

Error Codes

Request more calls

Every plan stops at its allowance rather than billing per call. If your application needs more than your plan includes, tell us roughly how many calls and what for, and we'll raise your key's allowance. The extra calls apply every period: each 30-day window on a free key, each month on Pro or Data.

Bulk dataset licence

The API is sold as a monthly call allowance, which suits an application reading current sentiment. If you need the whole corpus at once — to backtest against, to train on, or to join to your own data — that's a licence rather than a subscription, delivered as CSV or JSONL.

Scores come from the same FinBERT pipeline behind the live API, so a backtest on the archive and a signal read from /v1/sentiment are directly comparable. Methodology is documented in full under Sentiment Scoring.