/setup-x-api.en

description: "Lesson command"
duration: "~15 min"
prerequisites: ["Have an X account", "Browser available"]
level: "beginner"
tags: ["setup", "x", "twitter", "api"]
nonInteractiveMode: incompatible

X (Twitter) API Setup

Step 0: Check Setup Progress

**What the AI auto-runs:** 1. Run `uv run python tools/setup_progress.py show --current setup-x-api` to display progress 2. Auto-detect existing API key:

• Run `uv run python tools/credential_manager.py status`
• If X_BEARER_TOKEN is already set, only run Step 4 (API test) and mark as complete
• If it exists in plaintext in `.env`, suggest migration to the credential store

**Display important warning to the user:**

WARNING: X (Twitter) API requires a paid plan

- Free tier: Recent Search API is NOT available
- Basic plan: $100/month required
- This setup is optional. You can skip it if you won't use the x-research skill

Other training lessons (banner creation, chart generation, data analysis, etc.)
work perfectly fine without the X API.

What You'll Do in This Session

| Item | Details | |------|---------| | Goal | Obtain a Bearer Token from the X Developer Portal, save it to the Credential Store, and enable real-time X search and trend analysis features | | Duration | ~15 minutes | | Prerequisites | Have an X account, browser available | | Skill Level | No CLI commands needed (all auto-run by AI + GUI-only operations) | | Pricing | **Basic plan ($100/month) or higher required**. Free tier does not support Recent Search API | | Use case | Real-time X (Twitter) search and trend analysis. Used by the x-research skill |

**Session flow:** 1. Open X Developer Portal in browser (AI auto-launches browser) 2. Apply for a Developer account, create a project and app 3. Obtain the Bearer Token 4. Securely save with credential_manager.py in a separate terminal 5. Operation test (AI auto-runs)

> **Hint**: If the AI stops responding midway, type "please continue" or "it stopped" to resume.

---

Readiness Check

**AskQuestion configuration:**

{
  "title": "Pre-session confirmation",
  "questions": [{
    "id": "readiness",
    "prompt": "X API setup requires the Basic plan ($100/month). Are you ready?",
    "options": [
      {"id": "ready", "label": "I have a paid plan / plan to subscribe. Let's start"},
      {"id": "chrome", "label": "Automate browser operations with /chrome"},
      {"id": "check_cost", "label": "I want to know more about pricing"},
      {"id": "skip", "label": "Skip (I won't use X API)"},
      {"id": "different_lesson", "label": "Go to a different lesson"}
    ]
  }]
}

(ready -> Proceed to Step 1) (chrome -> After opening the browser in Step 1, follow the "Chrome integration automation" section) (check_cost -> Guide: "X API pricing: Free tier is post-only (no search API). Basic plan ($100/month) enables Recent Search API. Pro plan ($5,000/month) enables Full-Archive Search, but Basic is sufficient for training. If the cost doesn't justify it, we recommend skipping") (skip -> Guide: "X API setup skipped. No impact on other lessons. You can restart with /setup-x-api later" and proceed to completion) (different_lesson -> Show module list)

---

Step 1: Open X Developer Portal in Browser

**What the AI does:** 1. Auto-detect the OS (Mac / Windows / Linux) 2. Run the following command to auto-launch the browser:

# Mac:
open https://developer.x.com/en/portal/dashboard
# Windows:
start https://developer.x.com/en/portal/dashboard
# Linux:
xdg-open https://developer.x.com/en/portal/dashboard

**Once the browser opens, display the following AskQuestion:**

{
  "title": "Step 1: Access X Developer Portal",
  "questions": [{
    "id": "portal_status",
    "prompt": "Did the browser open? Follow these steps to apply for a Developer account:\n\n1. Log in with your X account\n2. Select 'Sign up for Free Account' or 'Subscribe to Basic'\n   (Basic plan is required to use Recent Search API)\n3. Fill in the use case (e.g., 'Academic research and AI agent training')\n4. Agree to the developer agreement\n\nDid the Developer Portal dashboard appear?",
    "options": [
      {"id": "dashboard_ready", "label": "The dashboard appeared!"},
      {"id": "browser_not_open", "label": "The browser didn't open"},
      {"id": "signup_issue", "label": "Having trouble with the Developer account application"},
      {"id": "already_have_account", "label": "I already have a Developer account"}
    ]
  }]
}

(dashboard_ready -> Proceed to Step 2) (browser_not_open -> Guide: "Please open this URL directly in your browser: https://developer.x.com/en/portal/dashboard") (signup_issue -> Guide: "Developer Portal applications may require review. Fill in the use case specifically (e.g., 'Building an AI-powered social media research tool for corporate training'). Review may take a few days. Please re-run this setup after receiving the approval email") (already_have_account -> Proceed to Step 2)

---

Chrome Integration Automation (`/chrome` mode)

**Prerequisites:** The "Claude in Chrome" extension (v1.0.36+) is installed in Chrome, and you launched with `claude --chrome` or ran `/chrome` within the session.

**What the AI auto-runs via Chrome integration:** 1. Open https://developer.x.com/en/portal/dashboard in the browser 2. Use Chrome integration to sequentially perform:

• Select "Subscribe to Basic" (Basic plan is required for Recent Search API. Free Account does not support search API)
• Leave payment information entry to the user (wait for user action)
• Enter "AI agent training and educational purposes" as the use case
• Agree to the Developer Agreement and Submit (wait for user action)
• Navigate to "Projects & Apps" on the Dashboard
• Click "+ Add Project" -> Enter "AIAgent Bootcamp" as Project name, select "Exploring the API" as use case
• Click "+ Add App" -> Enter "AIAgent Bootcamp" as App name, select "Development" as environment
• Open the "Keys and