Search Twitter/X tweets with advanced filters, pay-per-request in USDC on Base via x402.
What it does
The twit.sh /tweets/search endpoint lets agents and applications search the Twitter/X full tweet archive using advanced filters. You can filter by keywords, exact phrases, hashtags, author, recipient, mentions, minimum engagement thresholds (replies, likes, reposts), and date ranges. Results are paginated via cursor tokens. The endpoint returns X v2 API-compatible JSON.
This is one endpoint within the broader twit.sh API, which covers user lookups, tweet lookups, timelines, replies, quote tweets, retweets, lists, communities, articles, and authenticated actions (post, like, retweet, bookmark, follow). All endpoints are payment-gated using the x402 protocol: the server responds with HTTP 402 and a machine-readable USDC payment challenge on Base mainnet. The agent settles the payment and retries with a proof header — no API keys, OAuth, or account creation required.
The /tweets/search endpoint costs $0.01 USDC per request. At least one filter parameter is required. Data is sourced from publicly available information and shaped into clean JSON. The API is designed for autonomous AI agents and is compatible with Claude Code, Cursor, OpenClaw, Hermes, Codex, and other x402-enabled agent frameworks. An npm CLI skill (`npx twitsh`) is also available for easy integration.
Capabilities
Use cases
- —Searching Twitter/X for tweets matching specific keywords, hashtags, or phrases
- —Monitoring brand mentions or competitor activity on Twitter/X
- —Filtering tweets by engagement thresholds to find viral or high-impact content
- —Building datasets of tweets within specific date ranges for research or analytics
- —Autonomous AI agents gathering real-time social media intelligence without API keys
Fit
Best for
- —AI agents needing programmatic Twitter/X search without OAuth setup
- —Developers who want pay-per-call pricing instead of monthly API subscriptions
- —Research and analytics workflows requiring advanced tweet filtering
- —Crypto-native applications that can settle payments in USDC on Base
Not for
- —High-volume bulk scraping (pay-per-request adds up at scale)
- —Applications requiring Twitter streaming/real-time push notifications
- —Users who need authenticated write actions on this specific endpoint (search is read-only)
Quick start
# Search tweets via x402 (agent handles payment automatically)
curl -X GET "https://x402.twit.sh/tweets/search?words=bitcoin&minLikes=100&since=2025-01-01"Example
Request
{
"url": "https://x402.twit.sh/tweets/search",
"method": "GET",
"params": {
"from": "elonmusk",
"since": "2025-01-01",
"until": "2025-06-01",
"words": "bitcoin",
"minLikes": "100"
}
}Endpoint
Quality
Full OpenAPI 3.1 schema with detailed parameter descriptions for all endpoints, live 402 challenge confirmed, clear pricing ($0.01 USDC), and a well-documented landing page. Deducted points because no response schema or example response body is provided for this endpoint, and /docs returns 404.
Warnings
- —No response schema defined for the /tweets/search 200 response — actual response structure must be inferred from the 'X v2 API-compatible JSON' claim.
- —The /docs, /api, /pricing, and /README paths all return 404, so there is no supplementary documentation beyond the landing page and OpenAPI spec.
- —Write actions (like, follow, retweet, tweet) require raw Twitter session cookies (auth_token, ct0) passed as query parameters, which raises security concerns.
Citations
- —The /tweets/search endpoint costs $0.01 USDC per request with fixed pricing.https://x402.twit.sh
- —Payment is settled in USDC on Base mainnet via the x402 protocol with no account required.https://x402.twit.sh
- —Data is sourced from the open web and returned in X v2 API-compatible JSON format.https://x402.twit.sh
- —Compatible with Claude Code, Claude Desktop, Cursor, OpenClaw, Hermes, Codex, and other AI agents.https://x402.twit.sh
- —An npm CLI skill is available via npx twitsh.https://x402.twit.sh
- —Search supports filters: words, phrase, anyWords, noneWords, hashtags, from, to, mentioning, minReplies, minLikes, minReposts, since, until, and pagination via next_token.https://x402.twit.sh