SentimentFX

SentimentFX

A news-sentiment dataset for 42 markets across crypto, FX, stocks, ETFs and commodities. SentimentFX scrapes financial headlines, scores each one with FinBERT (a finance-tuned transformer model), and stores the scores next to daily and intraday prices. You can read the data on a dashboard, through a metered REST API, or as tools over MCP for Claude and other AI clients.

The product is the scored archive and live feed. It is not a price forecast: the dashboard shows correlation and backtest results so you can judge the signal yourself, and it makes no claim that sentiment predicts returns.

Live: sentimentfx.org · app.sentimentfx.org · developers.sentimentfx.org · status.sentimentfx.org

What it does

• Pulls headlines from RSS feeds every 15 minutes (CoinDesk, CoinTelegraph, Yahoo Finance, r/CryptoCurrency and others), plus RSS-less news sites through saved ScraperAI configs
• Scores each new headline once with FinBERT: positive_prob - negative_prob, giving -1 to +1, shown as 0–100 in the UI
• Refreshes prices for all 42 tickers every hour through yfinance (daily OHLC and intraday candles)
• Correlates daily sentiment shifts with next-day returns over 180 days, with a 95% confidence interval and a strength label
• Publishes a free cross-asset Sentiment Index (0–100, Fear → Greed) built from scored news text, not trader positioning
• Sells access through Stripe: a Pro dashboard plan, a Data plan for the API, and the full archive on request

Coverage

Price currency depends on category. Crypto is quoted in GBP (BTC-GBP on Yahoo). FX pairs are raw exchange rates. Stocks, ETFs and commodity futures are in native USD, and no GBP conversion is applied.

Products

Dashboard (app.sentimentfx.org)

• Sentiment vs price chart, candlestick chart with a sentiment pane, and a 0–100 sentiment gauge
• Correlation signal, divergence card, interactive backtest simulator and headline-impact panel
• Headline feed with a per-article score. Editorial news is the default, and social sources are badged.
• Leaderboard, track record and morning-brief pages
• CSV export, email sentiment alerts and the morning brief email (Pro)

Alerts only fire for tickers whose backtest passes a quality gate: positive out-of-sample net return, and at least 70% of walk-forward folds positive. The gate is refreshed daily.

Plans

The bulk archive (every scored headline and price row, as CSV or JSONL) is sold separately. Ask through the dataset form on the developer portal.

Developer API (api.sentimentfx.org/v1/)

Authenticate with an X-API-Key header. Full docs are at developers.sentimentfx.org.

Social posts (Reddit, StockTwits, X) are collected but kept separate. Every sentiment number is news only by default, and sources=social returns the social posts on their own. Calls are counted after the query, on rows actually returned. Nothing is billed per call: a key that uses up its allowance gets a 402 insufficient_quota until it refills, and a higher allowance can be requested. A 404 costs nothing, and out-of-range parameters are rejected with a 422 before any work is done. Every response carries X-Quota-* and X-RateLimit-* headers. Errors use one envelope: {"error": {"type": "...", "message": "..."}}.

# Get a free key (1,000 calls every 30 days, no card)
curl -X POST https://api.sentimentfx.org/api/keys/generate \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

# Use it
curl https://api.sentimentfx.org/v1/summary/BTC?days=7 \
  -H "X-API-Key: sfx_your_key_here"

The Sentiment Index is public and needs no key: GET https://api.sentimentfx.org/sentiment-index. Like every other sentiment number, it's built from news only.

MCP server (api.sentimentfx.org/mcp)

The same data is exposed as six Model Context Protocol tools: list_tickers and get_usage (both free), plus get_sentiment, get_summary, get_prices and get_correlation, which bill exactly like their /v1 equivalents. It uses streamable HTTP with the same X-API-Key header, or Authorization: Bearer <key> for clients that can't set custom headers (the Claude API's MCP connector is one). The registry manifest is server.json, and publishing steps are in docs/publishing-mcp-registry.md.

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

Architecture

RSS feeds (15 min) ─┐
ScraperAI replay ───┼→ scraper.py / ai_sources.py → dedup by URL → FinBERT → headlines
HN Algolia (admin) ─┘

yfinance (hourly) → prices.py / candles.py → prices, candles

headlines + prices → /dashboard, /candles, /correlation, /backtest …  → React dashboard
                   → /v1/*  and  /mcp                                → API and MCP clients
                   → /sentiment-index                                → public index page

Scheduled jobs (APScheduler, inside the API process):

FinBERT only runs on headlines it hasn't seen. The model (~400 MB) downloads and loads on the first scoring call, not at import.

Dormant sources. GNews, StockTwits and X/Twitter fetchers are still in the code but switched off. Set GNEWS_ENABLED, STOCKTWITS_ENABLED or X_ENABLED to true to turn one back on. StockTwits was turned off because Cloudflare blocks the server's IP and retail chat scores poorly with a news-tuned model.

Repo layout

Getting started

Backend

cd backend
python -m venv venv
source venv/Scripts/activate        # Windows (Git Bash); venv/bin/activate on macOS/Linux
pip install -r requirements.txt
python -m uvicorn app.main:app --reload   # http://localhost:8000

There is no .env.example. Create backend/.env with the variables below.

Frontend

cd frontend
npm install
npm run dev      # http://localhost:5173

Set VITE_SUPABASE_ANON_KEY in frontend/.env to enable login (VITE_GA_ID is optional). The API base URL is hard-coded to https://api.sentimentfx.org in src/lib/constants.js, so a local frontend talks to production unless you change it.

Tests

cd backend
pip install -r requirements-dev.txt
python -m pytest tests/ -v

Use python -m pytest, not bare pytest: tests/ has no __init__.py, so bare pytest can't import app. The tests are smoke-level only. They check that the app boots and the core routes answer, and they need a reachable DATABASE_URL. CI runs them against a throwaway Postgres on every push to main and every PR. There is no frontend test suite.

Sentiment scoring

score = positive_probability - negative_probability

The range is -1 (most negative) to +1 (most positive), and the UI shows it as 0–100. Neutral headlines land near 0 instead of being forced to exactly 0, which was the problem with the old label × confidence method. FinBERT scores the title only, even when the full article body is stored.

Deployment

• Backend: Railway via Procfile + nixpacks.toml at api.sentimentfx.org. Starts with uvicorn app.main:app --host 0.0.0.0 --port $PORT. Runs on CPU only.
• Dashboard, landing, developer portal: separate Vercel projects (frontend/, landing/, developers/), each auto-deploying from main.