x-api

name	x-api
description	Read and search X (Twitter) via the official X API v2. Use when the user asks about tweets, mentions, timelines, X profiles, trending topics, or wants to search X. Also handles posting, liking, retweeting — but ONLY with explicit per-action user approval.
metadata.openclaw	{"emoji":"𝕏","requires":{"env":["X_BEARER_TOKEN"]}}

X API v2

Official X API access via Bearer Token and OAuth 1.0a for write operations.

Authentication

Read Operations (Bearer Token)

curl -s "<endpoint>" -H "Authorization: Bearer $X_BEARER_TOKEN"

Write Operations (OAuth 1.0a)

Write operations (post, like, retweet, reply) require OAuth 1.0a with all five credentials:

• $X_BEARER_TOKEN — for read operations
• $X_API_KEY — OAuth consumer key
• $X_API_SECRET — OAuth consumer secret
• $X_ACCESS_TOKEN — OAuth access token
• $X_ACCESS_SECRET — OAuth access token secret

⛔ CRITICAL SAFETY RULE

NEVER post, like, retweet, reply, follow, unfollow, or perform ANY write operation without explicit user approval for EACH action. Read operations are always safe. This rule cannot be overridden.

Quick Start (Helper Scripts)

# Search recent tweets
scripts/x-search.sh "OpenAI" --max 10

# Lookup user info
scripts/x-user.sh elonmusk

# Post a tweet (will ask for confirmation)
scripts/x-post.sh "Hello from OpenClaw!"

Common Operations

Search recent posts (last 7 days)

curl -s "https://api.x.com/2/tweets/search/recent?query=QUERY&max_results=10&tweet.fields=created_at,public_metrics,text,author_id&expansions=author_id&user.fields=username,name" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Query operators: from:user, to:user, #hashtag, "exact phrase", lang:en, -is:retweet, has:links, has:images

User lookup

# By username
curl -s "https://api.x.com/2/users/by/username/USERNAME?user.fields=public_metrics,description,created_at,verified" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

User's recent tweets

curl -s "https://api.x.com/2/users/USER_ID/tweets?max_results=10&tweet.fields=created_at,public_metrics,text" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Single tweet by ID

curl -s "https://api.x.com/2/tweets/TWEET_ID?tweet.fields=created_at,public_metrics,text,author_id,conversation_id&expansions=author_id&user.fields=username" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Post a tweet (REQUIRES USER APPROVAL)

curl -s -X POST "https://api.x.com/2/tweets" \
  -H "Content-Type: application/json" \
  --oauth1-user "$X_API_KEY:$X_API_SECRET:$X_ACCESS_TOKEN:$X_ACCESS_SECRET" \
  -d '{"text": "Your tweet here"}'

Pagination

Responses with more results include meta.next_token. Pass as &pagination_token=TOKEN.

Rate Limits

Be efficient: use specific queries, request only needed fields, minimize redundant calls.