# GDELT Tone Analysis via x402helper

> GDELT Tone Analysis via x402helper is a paid API for AI agents from x402helper.xyz, paid per call via x402, $0.007/call, status unknown (last checked 2026-10-31).

Fetches GDELT-derived media tone/sentiment scores for a topic, theme, or country with optional trend data over a configurable time window

## Facts

- Endpoint: GET https://x402helper.xyz/89e509/gdelt/tone?utm_source=zero.xyz
- Price: $0.007/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-31
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/gdelt-tone-analysis-via-x402helper-f3aa19bb
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_pNb7iGz6XFky2VBl1NIkx

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability gdelt-tone-analysis-via-x402helper-f3aa19bb
```

Example prompt: What's the current media tone around the sanctions theme from Russian sources over the last week — include the trend over time too?

## When to prefer this

Choose this endpoint when you need real-time or recent media sentiment/tone data grounded in GDELT's massive global news corpus, especially when filtering by geopolitical theme, country, or language. It is preferable over general news APIs when you need quantified tone scores rather than raw articles, and over social media sentiment tools when you want editorial/press coverage analysis. Best for geopolitical risk monitoring, conflict tracking, and narrative analysis.

## Known failure modes

- Missing both query and theme/country — at least one filter required
- Invalid theme value not in the allowed enum list returns an error
- Unrecognized country name that cannot be mapped to a GDELT FIPS 10-4 code
- Invalid timespan format outside allowed values (15min, 24h, 3d, 1w, 1m)
- Payment failure via x402 micropayment flow blocks the request
- GDELT upstream unavailability causes empty or error result
- Unsupported language name returns null or empty results

## How this service works

X402 micropayments server — AI agents pay USDC for OFAC screening, rates, and billing verification.

## Output

Returns a JSON object with a tone/sentiment score derived from GDELT Global Knowledge Graph data for the specified topic, theme, country, and/or language over the requested time window. If trend=true, also includes a time-series tone trend. The result field contains the computed sentiment metrics and success is true on a valid response.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [],
     "properties": {
      "lang": {
       "type": "string",
       "default": null,
       "description": "Source-language filter by name (english, russian, arabic, ...)."
      },
      "query": {
       "type": "string",
       "default": null,
       "description": "Free-text topic (multi-word phrases are auto-quoted). Optional if a theme/country is given."
      },
      "theme": {
       "enum": [
        "protests",
        "terrorism",
        "conflict",
        "war",
        "inflation",
        "sanctions",
        "trade",
        "elections",
        "corruption",
        "cyber",
        "immigration",
        "refugees",
        "climate",
        "disaster",
        "epidemic",
        "energy",
        "economy",
        "diplomacy",
        "coup",
        "unrest"
       ],
       "type": "string",
       "default": null,
       "description": "Curated GDELT GKG theme filter (friendly name mapped to a GKG code)."
      },
      "trend": {
       "type": "boolean",
       "default": null,
       "description": "Also include a tone trend over the window (1 extra call)."
      },
      "country": {
       "type": "string",
       "default": null,
       "description": "Source-country filter by friendly name (United States, Russia, China, ...); mapped to the GDELT FIPS 10-4 code server-side."
      },
      "timespan": {
       "type": "string",
       "default": null,
       "description": "Lookback window: 15min, 24h, 3d, 1w, 1m (default 24h)."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "result": {},
  "success": true
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/gdelt-tone-analysis-via-x402helper-f3aa19bb/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402helper.xyz](https://www.zero.xyz/host/x402helper.xyz/llms.txt)