X (Twitter) Hot Topics Fetcher

Fetch real-time trending topics from X, filter by user interest domains, and analyze the background, popular opinions, and key controversies of each topic.

Prerequisites

Dependencies

• Python 3.7+
• tweepy library

Both are handled automatically: the scripts/x_hots entrypoint wrapper creates an isolated virtualenv at <skill_dir>/.venv on first run and installs requirements.txt (which pins tweepy) into it. No manual pip install is needed. Override the venv location with SKILL_VENV_DIR=<path>.

Environment Variables

Only the Bearer Token is required. The script uses app-only (OAuth 2.0) auth, which is sufficient for the search_recent_tweets endpoint and has broader search access than OAuth 1.0a user credentials — so the consumer key/secret and access token/secret are not needed.

export X_BEARER_TOKEN="***"

Obtain this credential from the X Developer Portal.

Note: The Free tier API has limitations:

• Can only search tweets from the last 7 days
• Rate limited to 10 requests per 15 minutes for search endpoints

When to Use

When the user wants to know what's trending on X/Twitter, or asks about hot topics, public opinion, or viral discussions.

Workflow

Step 1: Analyze User Interest Domains

Extract interest domains from the user's natural language input. Common domains include:

• International Politics: politics, geopolitics, diplomacy, sanctions, war, NATO, UN
• Economy & Finance: economy, stock market, tariff, trade, inflation, crypto, bitcoin
• Technology: AI, LLM, GPT, tech, chip, semiconductor, Apple, Google, Microsoft
• Sports: football, World Cup, NBA, Olympics, FIFA
• Entertainment: movie, music, celebrity, Netflix, Disney
• Society: climate, health, education, protest, human rights

Analysis Rules:

1. If the user explicitly mentions a domain (e.g., "what's hot in tech?"), use that domain's keywords directly
2. If the user mentions a specific topic (e.g., "what's happening with AI?"), use that topic as the keyword
3. If no specific domain can be identified, use the generic hot topics query (see "Generic Query" below)
4. Select 2-3 core keywords per domain to avoid excessive queries

Step 2: Run the Script to Fetch Hot Tweets

scripts/x_hots '<json_queries>'

Parameters:

• json_queries: JSON array of search keywords
• Each keyword returns up to 10 related hot tweets

Examples:

# Tech + Economy domains
scripts/x_hots '["AI", "LLM", "stock market", "tariff"]'

# International politics
scripts/x_hots '["geopolitics", "diplomacy", "sanctions"]'

# Generic hot topics (when no domain can be identified)
scripts/x_hots '["trending", "breaking", "viral"]'

Output Format:

{
  "success": true,
  "timestamp": "2026-07-09T03:58:00Z",
  "queries": ["AI", "LLM"],
  "results": {
    "AI": {
      "success": true,
      "count": 10,
      "tweets": [
        {
          "id": "1234567890",
          "text": "Tweet content...",
          "created_at": "2026-07-09T03:50:00Z",
          "metrics": {"like_count": 100, "retweet_count": 50},
          "url": "https://twitter.com/twitter/status/1234567890"
        }
      ]
    }
  }
}

Step 3: Analyze and Present Results

For each domain/keyword, analyze the returned tweets and extract:

1. Background: The origin of the hot topic, timeline, key people/organizations involved
2. Popular Opinions: What are the mainstream views? Core arguments from supporters and opponents
3. Key Controversies: What is the focal point of the debate? Where do different stances diverge?

Presentation Format:

## 🔥 [Domain Name] Hot Topics

### Topic 1: [Topic Title]

**📌 Background**
[Brief description of the event origin, timeline, key figures/organizations]

**💬 Popular Opinions**
- Supporters: [core argument]
- Opponents: [core argument]
- Neutral: [objective analysis]

**⚔️ Key Controversies**
[Focal point of the debate, divergence between different stances]

---

### Topic 2: [Topic Title]
...

Generic Query (When No Domain Can Be Identified)

When the user's input cannot be mapped to a specific domain (e.g., "what's hot on X?"), use the following strategy:

1. Run the script with generic hot topic queries:

   scripts/x_hots '["trending", "breaking", "viral", "news"]'
   

2. Identify the Top 10 highest-engagement topics from the returned tweets (based on likes, retweets, replies)

3. Present them ranked by engagement, with a brief background for each topic

Examples

Example 1: User Mentions a Specific Domain

User input: "What's hot in tech?"

Analysis: Domain = Tech, Keywords = ["AI", "LLM", "tech"]

Execute:

scripts/x_hots '["AI", "LLM", "tech"]'

Example 2: User Mentions a Specific Topic

User input: "What's happening with tariff policy?"

Analysis: Topic = Tariff, Keywords = ["tariff", "trade war", "tariff policy"]

Execute:

scripts/x_hots '["tariff", "trade war", "tariff policy"]'

Example 3: No Domain Can Be Identified

User input: "What's hot on X?"

Analysis: No specific domain identified, use generic query

Execute:

scripts/x_hots '["trending", "breaking", "viral", "news"]'

Notes

1. API Limits: Free-tier API can only search tweets from the last 7 days
2. Language Filter: Defaults to English tweets (lang:en); modify the script for other languages
3. Deduplication: Script already filters out retweets (-is:retweet), only returns original tweets
4. Engagement Ranking: Popularity is judged by likes, retweets, and replies combined
5. Timeliness: Results are sorted by relevancy, prioritizing popular/high-engagement tweets

Error Handling

API Authentication Failure

{"success": false, "error": "Missing environment variable: X_BEARER_TOKEN"}

Fix: Ensure the Bearer Token environment variable is set in your shell profile (e.g. ~/.zshrc):

export X_BEARER_TOKEN="***"

Obtain the credential from the X Developer Portal.

No Results Found

{"results": {"AI": {"success": true, "count": 0, "tweets": []}}}

Action: Inform the user that there are no hot topics in this domain currently; suggest trying different keywords

Rate Limit Exceeded

{"success": false, "error": "429 Too Many Requests"}

Action: Wait 15 minutes before retrying, or reduce the number of query keywords