--- name: www.surplusintelligence.ai description: www.surplusintelligence.ai exposes three skills: Twitter/X user lookup by username, Twitter/X trending topics by WOEID, and a legacy text completion endpoint backed by an OpenAI-compatible API with x402 micropayment on Base. It bridges Twitter data retrieval with on-demand AI text generation in a single host. host: www.surplusintelligence.ai --- # www.surplusintelligence.ai Surplus Intelligence is a small-footprint host serving agents that need to combine Twitter/X data lookups with AI-generated text, paying per request via x402 micropayments on Base. It targets use cases where an agent resolves Twitter identities or retrieves trending topics and then feeds that data into a text completion step. It does not offer a full Twitter API surface or a chat-style multi-turn interface. ## When to use this host Use this host when an agent needs to (1) resolve a Twitter/X username to a user ID, (2) retrieve current trending topics for a geographic location by WOEID, or (3) generate text via a legacy completions API paid per-request with x402 on Base. Do not use this host for fetching tweet timelines, follower counts, full profile metadata, or historical trend data — those require a more complete Twitter API integration not available here. Do not use the text completion skill for multi-turn chat; use a host that exposes a chat completions endpoint instead. If streaming support is required, verify it before relying on the create-text-completion skill. For richer Twitter data or higher-volume AI inference, prefer dedicated Twitter API wrappers or full OpenAI-compatible hosts respectively. ## Capabilities ### Twitter Identity Resolution Resolves a Twitter/X handle to its canonical numeric ID, display name, and username string, enabling downstream operations that require a user ID rather than a handle. - **`fetch-twitter-user-by-username`** — Fetches a Twitter/X user's numeric ID, display name, and username by their handle via the Twitter v2 API. ### Twitter Trend Discovery Retrieves up to 20 current trending topic names for a given geographic location using its WOEID, providing a real-time snapshot of what is trending in that region. - **`fetch-twitter-trends-by-woeid`** — Returns up to 20 current Twitter/X trending topic names for a given WOEID location identifier. ### AI Text Generation Generates text from a raw prompt string using a legacy OpenAI-compatible completions endpoint, billed per request via x402 micropayment on Base. - **`create-text-completion`** — Submits a prompt to an OpenAI-compatible legacy completions endpoint on Surplus Intelligence and returns generated text via x402 micropayment. ## Workflows ### Trend-Aware Content Generation *Use when an agent needs to generate text commentary, summaries, or copy based on what is currently trending on Twitter/X in a specific location.* 1. **`fetch-twitter-trends-by-woeid`** — Retrieve the current list of trending topic names for the target geographic location using its WOEID. 2. **`create-text-completion`** — Feed one or more trend names into a prompt and generate relevant text output such as a summary, article draft, or social copy. ### User-Contextualized Content Generation *Use when an agent needs to generate text that references a specific Twitter/X user and requires their canonical ID or verified username as part of the prompt context.* 1. **`fetch-twitter-user-by-username`** — Resolve the Twitter/X handle to its canonical ID, display name, and verified username. 2. **`create-text-completion`** — Incorporate the resolved user identity data into a prompt and generate relevant text output. ## Skill reference ### `fetch-twitter-user-by-username` **Twitter User Lookup by Username** — Fetches a Twitter/X user's numeric ID, display name, and username by their handle via the Twitter v2 API. *Use when:* Use when an agent needs to resolve a Twitter/X username (handle) to its canonical user ID, display name, or verified username string before performing downstream Twitter API operations. *Not for:* Do not use for fetching tweet timelines, follower counts, or profile metadata beyond id/name/username; those require additional Twitter API endpoints. **Inputs:** - `username` (string, required) — The Twitter/X handle (without the @ symbol) of the user to look up. **Returns:** Returns a data object containing the user's numeric id, display name, and username for the requested Twitter/X handle. **Example:** `GET https://www.surplusintelligence.ai/x402/api/twitter/v2/users/by/username/VitalikButerin` --- ### `fetch-twitter-trends-by-woeid` **Twitter Trends by WOEID** — Returns up to 20 current Twitter/X trending topic names for a given WOEID location identifier. *Use when:* Use when an agent needs to retrieve the current trending topics on Twitter/X for a specific geographic location identified by its WOEID (Where On Earth ID). *Not for:* Do not use for historical trend data or trend metadata beyond topic names (e.g., tweet volume, trend URLs); no such fields are returned in the response. **Inputs:** - `woeid` (integer, required) — Where On Earth ID (WOEID) identifying the geographic location for which to fetch trending topics. Use 1 for worldwide trends. **Returns:** Returns a data array of up to 20 objects, each with a trend_name string representing a currently trending Twitter/X topic for the specified WOEID location. **Example:** `GET https://www.surplusintelligence.ai/x402/api/twitter/v2/trends/by/woeid/1` --- ### `create-text-completion` **Surplus AI Text Completion** — Submits a prompt to an OpenAI-compatible legacy completions endpoint on Surplus Intelligence and returns generated text via x402 micropayment. *Use when:* Use when an agent needs to generate text from a raw prompt string using the legacy completions API format (not chat messages), paying per-request via x402 on Base. *Not for:* Do not use for multi-turn chat interactions; use the Surplus AI chat completions endpoint instead. Not suitable for streaming responses without verifying stream support. **Inputs:** - `model` (string, required) — ID of the model to use for completion. - `prompt` (string, required) — The prompt text to complete. Can be a single string or an array of strings. - `max_tokens` (integer) — Maximum number of tokens to generate in the completion. - `stream` (boolean) — If true, responses are streamed as server-sent events. Defaults to false. **Returns:** Returns a text_completion object with a choices array containing the generated text, finish reason, and a usage object with prompt, completion, and total token counts. **Example:** `{"model":"llama-3.3-70b","prompt":"Tell me about Surplus Intelligence.","max_tokens":256}` ---