# GDELT News Intelligence API

AI-friendly JSON API for real-time global news intelligence. Built on GDELT
(Global Database of Events, Language and Tone — a free, well-known public
source), optimized for AI agents.

## What this wrapper adds on top of raw GDELT

- **Clean JSON responses**: GDELT returns inconsistent XML and quirky JSON
  (e.g. `seendate=20240115T120000Z`). We normalize to ISO 8601 dates and
  predictable field names (`published_at`, `source_country`, `sentiment_score`).
- **5 use-case endpoints** instead of GDELT's 7+ raw modes: you don't have to
  learn `artlist` vs `timelinetone` vs `pointdata` — just call the endpoint
  for what you need (recent / sentiment / geographic / translingual / entity-graph).
- **Parallel-aggregated queries**: `/news/entity-graph` runs three GDELT calls
  in parallel and combines them — saves you the orchestration code.
- **No rate limits**: GDELT throttles to ~1 request per 5 seconds per IP.
  Cloudflare Workers absorbs that for you.
- **No API keys, no setup**: x402 handles auth + payment in a single header.
  Sign once with your wallet, you're done.
- **Reliable schema**: GEO 2.0 API was discontinued by GDELT — we replaced
  geographic intelligence with article-source-country aggregation so calls
  don't fail.

## How payment works

Each endpoint requires an x402 payment in USDC on Base mainnet (eip155:8453).
Make a request without payment to receive an HTTP 402 with the payment requirements
in the `PAYMENT-REQUIRED` header. Sign the EIP-3009 USDC authorization, send it back
in the `X-PAYMENT` header, and you receive the JSON response.

Settlement is handled by the Coinbase CDP facilitator
(https://api.cdp.coinbase.com/platform/v2/x402).

Recipient: 0xda8a384c99832de7f176a6c21720227ac024e364
Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC on Base mainnet)

## Endpoints

### GET /news/recent — $0.01
Top 25 recent articles for a topic. Cleaned to AI-friendly JSON.
Params: topic (required), language (default: english), hours (default: 24, max: 72).
Example: https://news-x402.com/news/recent?topic=bitcoin&hours=24

### GET /news/sentiment — $0.02
Sentiment trajectory over time as a timeseries (GDELT tone score, typically -10 to +10).
Params: topic (required), country (optional ISO code), timespan (default: 24h).
Example: https://news-x402.com/news/sentiment?topic=ukraine&timespan=7d

### GET /news/geographic — $0.02
Top source countries reporting on a topic, with coordinates and mention counts.
Params: topic (required), timespan (default: 24h).
Example: https://news-x402.com/news/geographic?topic=earthquake

### GET /news/translingual — $0.03
Topic coverage across 65 machine-translated languages, grouped by source language.
Shows how non-English media covers a topic — the "killer" feature of GDELT.
Params: topic (required), hours (default: 24, max: 72).
Example: https://news-x402.com/news/translingual?topic=AI+regulation

### GET /news/entity-graph — $0.05
Entity knowledge graph: sentiment trend over time, geographic distribution,
top publishing domains. Three GDELT calls in parallel.
Params: entity (required), timespan (default: 7d).
Example: https://news-x402.com/news/entity-graph?entity=Elon+Musk

## Notes

- Data source: GDELT Project (gdeltproject.org), free public news intelligence.
- License: GDELT data is freely redistributable for any use.
- This service is a thin AI-friendly wrapper that cleans GDELT's quirky responses.
- No authentication beyond x402 payment.
- No rate limits beyond Cloudflare's defaults.