--- name: x402.twit.sh description: x402.twit.sh provides paid API access to three Twitter/X search and lookup capabilities: keyword/filter-based tweet search, quote-tweet retrieval by tweet ID, and user account search by keyword. It does not cover timelines, follower graphs, or direct messaging. host: x402.twit.sh --- # x402.twit.sh x402.twit.sh is a narrow-scope Twitter/X data host serving agents that need to discover tweets, trace quote-tweet chains, or find user accounts. It covers search and discovery use cases only, accessed via x402 micropayment-gated endpoints. It does not replicate the full Twitter/X API surface — write operations, timeline fetching, and social graph traversal are out of scope. ## When to use this host Use x402.twit.sh when an agent needs to search tweets by keyword/hashtag/engagement filters, paginate through quote-tweets on a specific post, or discover user accounts by keyword. Do not use it for fetching a single tweet by ID (no ID-lookup skill is available), retrieving a user's full timeline without filters, traversing follower/following graphs (use a dedicated social graph API), or any write operations such as posting or liking. If real-time streaming or webhook-based tweet ingestion is needed, this host is not suitable — look for a Twitter streaming API provider instead. ## Capabilities ### Tweet Discovery Finds tweets matching structured filter criteria (keywords, hashtags, users, engagement thresholds, date ranges) and retrieves tweets that quote a specific tweet by ID, enabling both broad search and targeted engagement tracking. - **`search-tweets`** — Searches Twitter/X tweets using keyword, phrase, hashtag, user, engagement, and date filters, returning tweet text, author metadata, entities, and media. - **`fetch-quote-tweets`** — Retrieves a paginated list of tweets that quote a specific tweet, identified by its numeric tweet ID, including author data on each result. ### User Discovery Searches Twitter/X for user accounts by keyword or username fragment, returning ranked profile metadata useful for account identification and subject-matter discovery. - **`search-twitter-users`** — Searches Twitter/X for user accounts matching a keyword or phrase and returns up to 20 paginated, relevance-ranked user profiles per request. ## Workflows ### Identify Authors Then Trace Quote Engagement *Use when an agent needs to find tweets on a topic, identify a notable tweet, and then map how that tweet spread via quote-tweets.* 1. **`search-tweets`** — Search for tweets matching a keyword or hashtag to surface relevant or high-engagement tweets on the topic. 2. **`fetch-quote-tweets`** — Take the ID of a notable tweet from the search results and retrieve all quote-tweets to trace downstream discussion and engagement. ### Discover Users Then Find Their Tweets *Use when an agent needs to find accounts related to a subject and then retrieve recent tweets from one or more of those accounts.* 1. **`search-twitter-users`** — Search for user accounts matching a topic or keyword to identify relevant handles. 2. **`search-tweets`** — Use the discovered usernames in the 'from' filter to retrieve tweets authored by those accounts. ## Skill reference ### `search-tweets` **Tweet Search** — Searches Twitter/X tweets using keyword, phrase, hashtag, user, engagement, and date filters, returning tweet text, author metadata, entities, and media. *Use when:* Use when an agent needs to retrieve tweets matching specific keywords, phrases, hashtags, usernames, engagement thresholds, or date ranges from Twitter/X. *Not for:* Do not use for fetching a single tweet by ID or retrieving a user's full timeline without filters; at least one filter parameter must be provided. **Inputs:** - `words` (string) — All these words must appear in the tweet. - `phrase` (string) — Exact phrase that must appear in the tweet. - `anyWords` (string) — Any of these words must appear in the tweet. - `noneWords` (string) — Exclude tweets containing these words. - `hashtags` (string) — Filter by hashtag (without the # symbol). - `from` (string) — Return tweets authored by this username. - `to` (string) — Return tweets that are replies to this username. - `mentioning` (string) — Return tweets that mention this username. - `minReplies` (string) — Minimum reply count a tweet must have. - `minLikes` (string) — Minimum like count a tweet must have. - `minReposts` (string) — Minimum retweet count a tweet must have. - `since` (string) — Start date for the search range in YYYY-MM-DD format. - `until` (string) — End date for the search range in YYYY-MM-DD format. - `next_token` (string) — Pagination cursor returned from a previous response to fetch the next page of results. **Returns:** Returns a data array of tweet objects each containing tweet text, creation timestamp, author profile, public engagement metrics, entities, and optional media metadata. **Example:** `GET https://x402.twit.sh/tweets/search?hashtags=BTC&minLikes=100&since=2025-01-01&until=2025-12-31` --- ### `fetch-quote-tweets` **Quote Tweet Fetcher** — Retrieves a paginated list of tweets that quote a specific tweet, identified by its numeric tweet ID, including author data on each result. *Use when:* Use when an agent needs to find all tweets that have quoted a specific tweet by its numeric ID, such as tracking engagement, monitoring quote-tweet discussions, or paginating through large sets of quote tweets. *Not for:* Do not use for fetching replies or retweets; those require different endpoints. Not suitable for searching tweets by keyword or user timeline. **Inputs:** - `id` (string, required) — Numeric tweet ID of the tweet whose quote tweets should be retrieved. - `next_token` (string) — Pagination cursor returned from a previous response to retrieve the next page of results. **Returns:** Returns a data array of quote tweet objects (empty if none exist) and a meta object containing a next_token pagination cursor for retrieving subsequent pages. **Example:** `GET https://x402.twit.sh/tweets/quote_tweets?id=1110302988` --- ### `search-twitter-users` **TwitSearch: User Lookup** — Searches Twitter/X for user accounts matching a keyword or phrase and returns up to 20 paginated, relevance-ranked user profiles per request. *Use when:* Use when an agent needs to find Twitter/X user accounts by keyword, username fragment, or topic — for example to discover accounts related to a subject, verify a handle exists, or enumerate users for further lookup. *Not for:* Do not use for searching tweets or posts; this endpoint returns user profiles only. Do not use for real-time follower/following graph traversal — use a dedicated social graph API instead. **Inputs:** - `query` (string, required) — Search keyword or phrase used to match user accounts on Twitter/X. - `next_token` (string) — Pagination cursor returned by a previous response to retrieve the next page of results. **Returns:** Returns a data array of up to 20 user profile objects each containing id, username, name, description, verified status, profile_banner_url, public_metrics (followers, following, tweets, likes, media), optional pinned_tweet_id, and entities; pagination via next_token. **Example:** `GET https://x402.twit.sh/users/search?query=bitcoin` ---