# Crypto Sentiment API

Real-time crypto market sentiment for AI agents, priced and paid per call
in USDC on Base via the x402 protocol. No account, API key, or
subscription required for this lane.

## Paid endpoint (x402)
GET https://crypto-sentiment-x402.onrender.com/sentiment/{symbol}
Price: $0.01 USDC per call (see the live HTTP 402 response for the
exact current price -- this text file is not the source of truth)
Network: Base (mainnet), x402 scheme "exact"
Example: GET /sentiment/BTC
Supported symbols: BTC, ETH, SOL, XRP, DOGE, ADA, AVAX, LINK, MATIC, DOT, SHIB, LTC, BNB, USDC, USDT, NEAR, HYPE, QNT, AAVE, TAO, PEPE, PUMP, ENA, STRK
Any other symbol (a stock ticker, say) gets HTTP 404 and is not charged.
Too little recent news for a supported coin to give a reliable reading
(effective sample size below 5 in the last 72 hours): HTTP 422
with no reading, and not charged.

## Hourly archive (x402)
GET https://crypto-sentiment-x402.onrender.com/history/{symbol}?start=<ISO 8601>&end=<ISO 8601>
Price: $0.05 USDC per call. Hourly readings recorded live
and never backfilled; default range the last 7 days, max 30 days per call.
Each row has observed_at, average_compound, sample_size, fear_greed_value,
matcher and drivers (top 3 headlines; null for rows before 2026-10-03).
A symbol that isn't logged, an invalid range or a range with no readings
gets a 4xx and is not charged, and so does a range in which every hour had
zero matching headlines (404 "no_headlines_in_range"). What exists (symbols,
first reading, row counts, missing hours, coverage_7d_pct = share of the
last 7 days' hours with headlines): GET /archive (free).

## Alternative access (not x402)
- GET /v1/sentiment/{symbol} -- X-API-Key header, Stripe subscription quota
  (see /billing/pricing)
- GET /rapidapi/sentiment/{symbol} -- RapidAPI-proxied traffic only
/v1 answers the not-enough-recent-news case with the same HTTP 422 and
doesn't count it against the key's quota. /rapidapi returns the reading
with the "insufficient recent news" label (RapidAPI meters 4xx responses too).

## Discovery
- OpenAPI spec: /openapi.json
- x402 discovery manifest: /.well-known/x402
- Interactive docs: /docs
- Transparency: /transparency
- Signal validation (does the score lead or lag price? 2026-11-03 update: no clear lead or lag at the hourly level): /validation

## Response
JSON with `overall_sentiment`, a per-source `breakdown`, and `drivers`.
The score covers headlines published in the last 72 hours, and each
headline's weight halves for every 24 hours of age.
- overall_sentiment.average_compound: the weighted score, -1 to 1
- overall_sentiment.label: bullish, bearish or neutral. When the effective
  sample size is below 5 ("insufficient recent news") /sentiment and
  /v1/sentiment return HTTP 422 with no reading instead, and don't charge;
  /rapidapi/sentiment returns the reading with that label
- overall_sentiment.unweighted_compound_72h: the plain 72-hour average
- overall_sentiment.effective_sample_size: how many full-weight headlines the
  weighted sample is worth
- overall_sentiment.newest_headline_age_hours and overall_sentiment.window
  (method version, currently "72h-hl24-v2")
- drivers: up to 5 headlines that moved the score most (largest weighted effect
  first), each with title, source, link, published (ISO 8601 UTC), its own
  score, weight and effect. Titles and links only, never article text.
- drivers_summary: one plain line such as "3 of the top 5 headlines are
  negative, 2 are positive."

## Data sources
9 crypto news RSS outlets (CoinDesk, Cointelegraph, Decrypt, Bitcoin Magazine, The Block, CryptoSlate, NewsBTC, CryptoPotato, The Defiant) and the Fear & Greed
Index (alternative.me). Scored with VADER
sentiment analysis plus a crypto slang lexicon, on each headline's title plus
its feed description with HTML, entities, feed footers and the outlet's own
name removed (method 72h-hl24-v2 from 2026-10-21; methodology notes at
/validation). Reddit is intentionally not used -- see /transparency.

## Contact
hi@forgealone.com