{"openapi":"3.1.0","info":{"title":"GDELT Global News Intelligence","version":"1.0.0","description":"![x402 Atlas](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0OCIgaGVpZ2h0PSI0OCIgdmlld0JveD0iMCAwIDQ4IDQ4IiBmaWxsPSJub25lIj48ZyBzdHJva2U9IiMxRTQwQUYiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCI+PHBhdGggZD0iTTI0IDdWMjhNMjQgMjhMOCA0Mk0yNCAyOEw0MCA0MiIgc3Ryb2tlLXdpZHRoPSIyLjEiLz48cGF0aCBkPSJNMjQgN0w4IDQyTTI0IDdMNDAgNDJNMTUgMjhIMzMiIHN0cm9rZS13aWR0aD0iMi43Ii8+PC9nPjxnIGZpbGw9IiMxRTQwQUYiPjxjaXJjbGUgY3g9IjgiIGN5PSI0MiIgcj0iMy4yIi8+PGNpcmNsZSBjeD0iNDAiIGN5PSI0MiIgcj0iMy4yIi8+PGNpcmNsZSBjeD0iMTUiIGN5PSIyOCIgcj0iMy4yIi8+PGNpcmNsZSBjeD0iMzMiIGN5PSIyOCIgcj0iMy4yIi8+PGNpcmNsZSBjeD0iMjQiIGN5PSIyOCIgcj0iMi45Ii8+PC9nPjxjaXJjbGUgY3g9IjI0IiBjeT0iNyIgcj0iNC4yIiBmaWxsPSIjMTRCOEE2Ii8+PC9zdmc+)\n\n**GDELT Global News Intelligence** is an independently documented x402 Atlas bridge at https://gdelt.use.x402atlas.com.\nThis document describes only this bridge; it does not aggregate routes, schemas,\nor content from any other bridge.\n\n## How payment works\n\nPaid operations use the [x402 payment protocol](https://x402.org) and settle in\nUSDC. Atlas supports deployments on Base, Polygon, and Arbitrum, plus configured\nSolana networks. This bridge currently advertises Arbitrum One (`eip155:42161`), Base (`eip155:8453`), Polygon (`eip155:137`), Solana mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`).\n\n1. Send the HTTP request without a payment signature.\n2. Read the `402 Payment Required` response. Its `accepts` entries are the\n   authoritative network, asset, amount, and recipient options for that call.\n3. Select an option, sign it with an x402-compatible wallet or SDK, and repeat\n   the request with the `PAYMENT-SIGNATURE` header. The successful response is\n   returned after verification and settlement.\n\nTypeScript clients can automate the challenge, signing, and retry flow with\n[`x402-fetch`](https://www.npmjs.com/package/x402-fetch) or\n[`x402-axios`](https://www.npmjs.com/package/x402-axios). Fund a dedicated\nwallet only with the working USDC balance it needs and keep that key separate\nfrom treasury accounts.\n\n## Pricing\n\nAtlas route prices start at $0.005 per successful call. This bridge's fallback\nprice is $0.005; operations below state their exact configured price in\n`x-x402` and `x-payment-info`. The live `402` challenge remains authoritative.\n\n## Worked payment example\n\nRequest one documented operation without a signature to inspect its live terms:\n\n```bash\ncurl -i 'https://gdelt.use.x402atlas.com/search?maxrecords=75\u0026query=%22supply+chain%22+%28drought+OR+flood%29\u0026sort=HybridRel\u0026timespan=3d'\n# HTTP/1.1 402 Payment Required\n# Read accepts[].network, asset, amount, and payTo from this response.\n```\n\nSign one accepted option and repeat the identical request with the\n`PAYMENT-SIGNATURE` header. Do not invent or cache payment terms; read them from\nthe current challenge.\n\n## Use this API\n\n- Interactive reference: https://gdelt.use.x402atlas.com/docs\n- OpenAPI 3.1 specification: https://gdelt.use.x402atlas.com/openapi.json\n- Agent-readable route corpus: https://gdelt.use.x402atlas.com/llms.txt\n- Endpoint index: https://gdelt.use.x402atlas.com/index.json\n\nUse the operation schemas and examples below to construct requests. Copy the\nserver URL, path, method, parameters, and request body from the operation you\nwant to call. Path and query examples are concrete and can be used directly.\n\n## Atlas response metadata\n\nSuccessful JSON responses include an additive top-level `_atlas` block, kept\nseparate from the bridge's data fields. `_atlas.docs` links this bridge's\n`/llms.txt` corpus. `_atlas.related` suggests adjacent APIs, each with a callable\n`url`, its own `docs` link, and a short `summary`. Suppress this block by sending\n`X-Atlas-Meta: none` or by adding `?_atlas=0` to the request.\n\n## Errors and compatibility\n\nValidation failures use HTTP `400`. Paid operations may return `402` before\ndispatch. Upstream and internal failures use the documented `5xx` responses.\nClients should rely on documented fields and tolerate additive response fields,\nincluding `_atlas` unless they explicitly opt out.\n\n## Protocol reference\n\n- x402 protocol and SDKs: https://x402.org","x-guidance":"Use the operation schemas and examples to construct requests. Paid operations return an HTTP 402 challenge with the authoritative payment terms."},"servers":[{"url":"https://gdelt.use.x402atlas.com"}],"tags":[{"name":"GDELT Global News Intelligence"}],"paths":{"/search":{"get":{"description":"Full-text search across GDELT's global news firehose (DOC 2.0 ArtList mode). `query` is **required** and takes GDELT query syntax — quoted phrases, `OR`, `-exclude`, and operators like `domain:`, `sourcelang:`, `sourcecountry:`, `theme:`, `tone\u003e`/`tone\u003c`, `near`. Optional: `timespan` (relative window like `15min`, `1h`, `7d`, `2w`, `3m`; default `3d`, capped at 3 months), `maxrecords` (default 75, max 250), and `sort` (`DateDesc`, `DateAsc`, `ToneDesc`, `ToneAsc`, or `HybridRel` default). Returns a snake_case `articles` array (`url`, `title`, `seen_at` as RFC3339, `domain`, `language`, `source_country`, optional `social_image`) plus a `queried_at` stamp and a mandatory GDELT `attribution` line; a query that matches nothing is a 200 with an empty `articles`, not a 404. For coverage-volume or tone trends over time use `/timeline` instead.\n\n**Price:** $0.005 per call.","operationId":"gdelt_GET_search","parameters":[{"name":"maxrecords","in":"query","description":"Number of articles to return, capped at 250","schema":{"default":75,"description":"Number of articles to return, capped at 250","maximum":250,"minimum":1,"type":"integer"},"example":75},{"name":"query","in":"query","required":true,"description":"GDELT query syntax — phrases, OR, -exclude, domain:, sourcelang:, sourcecountry:, theme:, tone\u003e/\u003c, near","schema":{"description":"GDELT query syntax — phrases, OR, -exclude, domain:, sourcelang:, sourcecountry:, theme:, tone\u003e/\u003c, near","maxLength":1024,"type":"string"},"example":"\"supply chain\" (drought OR flood)"},{"name":"sort","in":"query","description":"Result ordering","schema":{"default":"HybridRel","description":"Result ordering","enum":["DateDesc","DateAsc","ToneDesc","ToneAsc","HybridRel"],"type":"string"},"example":"HybridRel"},{"name":"timespan","in":"query","description":"Relative window like 15min, 1h, 7d, 2w, 3m; capped at 90 days","schema":{"default":"3d","description":"Relative window like 15min, 1h, 7d, 2w, 3m; capped at 90 days","pattern":"^[0-9]+(min|h|d|w|m)$","type":"string"},"example":"3d"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"properties":{"articles":{"items":{"properties":{"domain":{"type":"string"},"language":{"type":"string"},"seen_at":{"format":"date-time","type":"string"},"social_image":{"description":"Article thumbnail URL, when GDELT has one","type":"string"},"source_country":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"}},"required":["url","title","seen_at","domain","language","source_country"],"type":"object"},"type":"array"},"attribution":{"description":"Mandatory GDELT licence credit line","type":"string"},"count":{"description":"Number of articles returned","type":"integer"},"note":{"description":"Present only on a sample response (empty/omitted query): a hint to pass a real query. The paid request ran; no upstream call was made.","type":"string"},"queried_at":{"format":"date-time","type":"string"},"query":{"description":"Echo of the request query","type":"string"},"timespan":{"description":"Echo of the effective timespan","type":"string"}},"required":["query","queried_at","timespan","count","articles","attribution"],"type":"object"},"example":{"articles":[{"domain":"reuters.com","language":"English","seen_at":"2026-07-01T09:15:00Z","source_country":"United States","title":"Drought disrupts supply chains","url":"https://reuters.com/x"}],"attribution":"Data from The GDELT Project (https://www.gdeltproject.org)","count":1,"queried_at":"2026-07-01T12:00:00Z","query":"\"supply chain\" (drought OR flood)","timespan":"3d"}}}},"400":{"description":"Validation error — the request was rejected before the handler ran.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. The response carries an x402 payment challenge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Unexpected internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"x402Payment":[]}],"summary":"Global news article search by GDELT — normalized fulltext search across worldwide media (query syntax: phrases, OR, sourcecountry, theme, tone) returned as a clean snake_case envelope.","tags":["GDELT Global News Intelligence"],"x-payment-info":{"price":{"amount":"0.005","currency":"USD","mode":"fixed"},"protocols":[{"x402":{}}]},"x-x402":{"discoverable":true,"enabled":true,"paid":true,"price":"$0.005","service_name":"GDELT Global News Intelligence"}}},"/timeline":{"get":{"description":"Attention-and-tone time series for any `query`, merging GDELT DOC 2.0's `TimelineVol` (coverage volume) and `TimelineTone` (average tone) feeds into one `series` of `{date, volume_pct, tone}` — the two-into-one join you can't get from a single upstream call. `query` is **required** (same syntax as `/search`); optional `timespan` sets the window (`7d`, `2w`, `3m`; default `3m`, capped at 3 months) and `timelinesmooth` applies a 1–30 point moving average. The two feeds are fetched concurrently; if one fails its metric is `null` on every point (a volume-only answer still returns 200) — only both failing is an error. Dates are RFC3339 and each 200 carries the mandatory GDELT `attribution`. For the underlying articles rather than the trend, use `/search`.\n\n**Price:** $0.02 per call.","operationId":"gdelt_GET_timeline","parameters":[{"name":"query","in":"query","required":true,"description":"GDELT query syntax (see /gdelt/search)","schema":{"description":"GDELT query syntax (see /gdelt/search)","type":"string"},"example":"bitcoin"},{"name":"timelinesmooth","in":"query","description":"Moving-average window over the series (optional)","schema":{"description":"Moving-average window over the series (optional)","maximum":30,"minimum":1,"type":"integer"},"example":7},{"name":"timespan","in":"query","description":"Relative window like 7d, 2w, 3m; capped at 90 days","schema":{"default":"3m","description":"Relative window like 7d, 2w, 3m; capped at 90 days","pattern":"^[0-9]+(min|h|d|w|m)$","type":"string"},"example":"3m"}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"properties":{"attribution":{"description":"Mandatory GDELT licence credit line","type":"string"},"note":{"description":"Present only on a sample response (empty/omitted query): a hint to pass a real query. The paid request ran; no upstream call was made.","type":"string"},"partial":{"description":"True when one feed (volume or tone) was unavailable and its metric is null on every point — distinguishes a degraded answer from genuinely missing data","type":"boolean"},"queried_at":{"format":"date-time","type":"string"},"query":{"description":"Echo of the request query","type":"string"},"series":{"items":{"properties":{"date":{"format":"date-time","type":"string"},"tone":{"description":"Average article tone on this date; null if the tone feed had no value here","type":["number","null"]},"volume_pct":{"description":"Share of monitored coverage matching the query on this date; null if the volume feed had no value here","type":["number","null"]}},"required":["date","volume_pct","tone"],"type":"object"},"type":"array"},"timespan":{"description":"Echo of the effective timespan","type":"string"},"warnings":{"description":"Human-readable notes on any degraded feed, e.g. \"tone feed unavailable\"; empty when the answer is complete","items":{"type":"string"},"type":"array"}},"required":["query","queried_at","timespan","series","partial","warnings","attribution"],"type":"object"},"example":{"attribution":"Data from The GDELT Project (https://www.gdeltproject.org)","partial":false,"queried_at":"2026-07-01T12:00:00Z","query":"bitcoin","series":[{"date":"2026-04-01T00:00:00Z","tone":-1.8,"volume_pct":0.42}],"timespan":"3m","warnings":[]}}}},"400":{"description":"Validation error — the request was rejected before the handler ran.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required. The response carries an x402 payment challenge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"500":{"description":"Unexpected internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"x402Payment":[]}],"summary":"News attention \u0026 tone timeline by GDELT — coverage-volume and average-tone time series for any query, merged from GDELT's two timeline feeds into one series.","tags":["GDELT Global News Intelligence"],"x-payment-info":{"price":{"amount":"0.02","currency":"USD","mode":"fixed"},"protocols":[{"x402":{}}]},"x-x402":{"discoverable":true,"enabled":true,"paid":true,"price":"$0.02","service_name":"GDELT Global News Intelligence"}}}},"components":{"schemas":{"Error":{"properties":{"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"PaymentRequired":{"description":"x402 payment-required envelope. The exact shape comes from the x402 SDK and includes per-network accepted payment options. See https://x402.org for the canonical schema.","type":"object"}},"securitySchemes":{"x402Payment":{"description":"Pay the route via x402 (https://x402.org). The 402 response carries the payment challenge; resubmit with a PAYMENT-SIGNATURE header.","scheme":"x402","type":"http"}}}}