x-developer 2.3.0

package/skills/x-twitter-scraper/references/draws.md

@@ -0,0 +1,57 @@
+# Xquik Giveaway Draws
+
+Run transparent, auditable giveaway draws from tweet replies with configurable filters.
+
+## Create Draw
+
+`POST /draws` with a `tweetUrl` (required) and optional filters:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tweetUrl` | string | **Required.** Full tweet URL: `https://x.com/user/status/ID` |
+| `winnerCount` | number | Winners to select (default 1) |
+| `backupCount` | number | Backup winners to select |
+| `uniqueAuthorsOnly` | boolean | Count only one entry per author |
+| `mustRetweet` | boolean | Require participants to have retweeted |
+| `mustFollowUsername` | string | Username participants must follow |
+| `filterMinFollowers` | number | Minimum follower count |
+| `filterAccountAgeDays` | number | Minimum account age in days |
+| `filterLanguage` | string | Language code (e.g., `"en"`) |
+| `requiredKeywords` | string[] | Words that must appear in the reply |
+| `requiredHashtags` | string[] | Hashtags that must appear (e.g., `["#giveaway"]`) |
+| `requiredMentions` | string[] | Usernames that must be mentioned (e.g., `["@xquik"]`) |
+
+## Complete Workflow
+
+```javascript
+// Step 1: Create draw with filters
+const draw = await xquikFetch("/draws", {
+  method: "POST",
+  body: JSON.stringify({
+    tweetUrl: "https://x.com/burakbayir/status/1893456789012345678",
+    winnerCount: 3,
+    backupCount: 2,
+    uniqueAuthorsOnly: true,
+    mustRetweet: true,
+    mustFollowUsername: "burakbayir",
+    filterMinFollowers: 50,
+    filterAccountAgeDays: 30,
+    filterLanguage: "en",
+    requiredHashtags: ["#giveaway"],
+  }),
+});
+
+// Step 2: Get draw details with winners
+const details = await xquikFetch(`/draws/${draw.id}`);
+// details.winners: [
+//   { position: 1, authorUsername: "winner1", tweetId: "...", isBackup: false },
+//   ...
+// ]
+
+// Step 3: Export results
+const exportUrl = `${BASE}/draws/${draw.id}/export?format=csv`;
+```
+
+## Cost
+
+1 credit ($0.00015) per participant entry.

package/skills/x-twitter-scraper/references/extractions.md

@@ -0,0 +1,229 @@
+# Xquik Extraction Tools
+
+23 bulk data extraction tools. Each requires a specific target parameter.
+
+**Endpoint:** `POST /extractions`
+
+**Always estimate first:** `POST /extractions/estimate` with the same body to preview cost and check quota.
+
+## Tool Types
+
+### Tweet-Based (require `targetTweetId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `reply_extractor` | Extract users who replied to a tweet |
+| `repost_extractor` | Extract users who retweeted a tweet |
+| `quote_extractor` | Extract users who quote-tweeted a tweet |
+| `thread_extractor` | Extract all tweets in a thread |
+| `article_extractor` | Extract article content linked in a tweet |
+| `favoriters` | Extract users who favorited a tweet |
+
+**Example:**
+```json
+{
+  "toolType": "reply_extractor",
+  "targetTweetId": "1893704267862470862"
+}
+```
+
+### User-Based (require `targetUsername`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `follower_explorer` | Extract followers of an account |
+| `following_explorer` | Extract accounts followed by a user |
+| `verified_follower_explorer` | Extract verified followers of an account |
+| `mention_extractor` | Extract tweets mentioning an account |
+| `post_extractor` | Extract posts from an account |
+
+**Example:**
+```json
+{
+  "toolType": "follower_explorer",
+  "targetUsername": "elonmusk"
+}
+```
+
+The `@` prefix is automatically stripped if included.
+
+### User-Based by ID (require `targetUserId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `user_likes` | Extract tweets liked by a user |
+| `user_media` | Extract media tweets from a user |
+
+**Example:**
+```json
+{
+  "toolType": "user_likes",
+  "targetUserId": "44196397"
+}
+```
+
+### Community-Based (require `targetCommunityId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `community_extractor` | Extract members of a community |
+| `community_moderator_explorer` | Extract moderators of a community |
+| `community_post_extractor` | Extract posts from a community |
+| `community_search` | Search posts within a community (also requires `searchQuery`) |
+
+**Example:**
+```json
+{
+  "toolType": "community_extractor",
+  "targetCommunityId": "1234567890"
+}
+```
+
+### List-Based (require `targetListId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `list_member_extractor` | Extract members of a list |
+| `list_post_extractor` | Extract posts from a list |
+| `list_follower_explorer` | Extract followers of a list |
+
+**Example:**
+```json
+{
+  "toolType": "list_member_extractor",
+  "targetListId": "1234567890"
+}
+```
+
+### Space-Based (require `targetSpaceId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `space_explorer` | Extract participants of a Space |
+
+**Example:**
+```json
+{
+  "toolType": "space_explorer",
+  "targetSpaceId": "1YqKDqDXAbwKV"
+}
+```
+
+### Search-Based (require `searchQuery`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `people_search` | Search for users by keyword |
+| `tweet_search_extractor` | Search and extract tweets by keyword or hashtag (bulk, up to 1,000) |
+
+**Example (people search):**
+```json
+{
+  "toolType": "people_search",
+  "searchQuery": "machine learning engineer"
+}
+```
+
+**Example (tweet search):**
+```json
+{
+  "toolType": "tweet_search_extractor",
+  "searchQuery": "#AI",
+  "resultsLimit": 100
+}
+```
+
+### Tweet Search Filters
+
+The `tweet_search_extractor` tool type supports 16 additional filter fields that are converted to X search operators and combined with `searchQuery`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fromUser` | string | Author username |
+| `toUser` | string | Directed to user |
+| `mentioning` | string | Mentions user |
+| `language` | string | Language code (e.g., `en`) |
+| `sinceDate` | string | Start date (YYYY-MM-DD) |
+| `untilDate` | string | End date (YYYY-MM-DD) |
+| `mediaType` | string | `images`, `videos`, `gifs`, or `media` |
+| `minFaves` | number | Minimum likes |
+| `minRetweets` | number | Minimum retweets |
+| `minReplies` | number | Minimum replies |
+| `verifiedOnly` | boolean | Verified authors only |
+| `replies` | string | `include`, `exclude`, or `only` |
+| `retweets` | string | `include`, `exclude`, or `only` |
+| `exactPhrase` | string | Exact match text |
+| `excludeWords` | string | Comma-separated words to exclude |
+| `advancedQuery` | string | Raw X search operators appended to query |
+
+**Example with filters:**
+```json
+{
+  "toolType": "tweet_search_extractor",
+  "searchQuery": "AI",
+  "fromUser": "elonmusk",
+  "minFaves": 100,
+  "sinceDate": "2026-01-01",
+  "mediaType": "videos",
+  "resultsLimit": 500
+}
+```
+
+`resultsLimit` (optional): Maximum results to extract. Stops early instead of fetching all. Pass this on both `POST /extractions/estimate` and `POST /extractions` when you only need a specific count.
+
+## Response
+
+```json
+{
+  "id": "77777",
+  "toolType": "reply_extractor",
+  "status": "completed",
+  "totalResults": 150
+}
+```
+
+Statuses: `pending`, `running`, `completed`, `failed`.
+
+## Retrieving Results
+
+```
+GET /extractions/{id}
+```
+
+Returns paginated results (up to 1,000 per page). Each result includes:
+
+- `xUserId`, `xUsername`, `xDisplayName`
+- `xFollowersCount`, `xVerified`, `xProfileImageUrl`
+- `tweetId`, `tweetText`, `tweetCreatedAt` (for tweet-based extractions)
+
+## Exporting Results
+
+```
+GET /extractions/{id}/export?format=csv
+```
+
+Formats: `csv`, `xlsx`, `md`. 50,000 row limit.
+
+Exports include enrichment columns not present in the API response.
+
+## Estimating Cost
+
+```
+POST /extractions/estimate
+```
+
+Same body as create. Response:
+
+```json
+{
+  "allowed": true,
+  "source": "replyCount",
+  "estimatedResults": 150,
+  "usagePercent": 45,
+  "projectedPercent": 48
+}
+```
+
+If `allowed` is `false`, the extraction would exceed your monthly quota.
+
+For common mistakes and tool selection rules, see [mcp-tools.md](mcp-tools.md#common-mistakes).

package/skills/x-twitter-scraper/references/mcp-setup.md

@@ -0,0 +1,207 @@
+# Xquik MCP Server Setup
+
+Connect AI agents and IDEs to Xquik via the Model Context Protocol. The MCP server uses the same API key as the REST API.
+
+| Setting | Value |
+|---------|-------|
+| Protocol | HTTP (StreamableHTTP) |
+| Endpoint | `https://xquik.com/mcp` |
+| Auth header | `x-api-key` |
+
+> **Security:** Use a scoped, revocable API key — not your primary account key. Where your platform supports environment variable interpolation (e.g., `${XQUIK_API_KEY}`), prefer that over hardcoding. Rotate keys periodically from the [dashboard](https://dashboard.xquik.com/account). Never commit API keys to version control.
+
+## Claude.ai (Web)
+
+Claude.ai supports MCP connectors natively via OAuth. Add Xquik as a connector from **Settings > Feature Preview > Integrations > Add More > Xquik**. The OAuth 2.1 flow handles authentication automatically. No API key needed.
+
+## Claude Desktop
+
+Claude Desktop only supports stdio transport. Use `mcp-remote` as a bridge (requires [Node.js](https://nodejs.org)).
+
+> **About `mcp-remote`:** [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) is an open-source stdio-to-HTTP bridge maintained by the MCP ecosystem (MIT license, [source on GitHub](https://github.com/geelen/mcp-remote)). It translates Claude Desktop's stdio transport to StreamableHTTP — it does not execute arbitrary code, access your filesystem, or modify your system. The version is pinned (`@0.1.38`) to prevent supply-chain drift. If you prefer not to use `npx`, install it globally first: `npm install -g mcp-remote@0.1.38`, then replace `"command": "npx"` with `"command": "mcp-remote"` and remove the version from args.
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "xquik": {
+      "command": "npx",
+      "args": [
+        "mcp-remote@0.1.38",
+        "https://xquik.com/mcp",
+        "--header",
+        "x-api-key:${XQUIK_API_KEY}"
+      ]
+    }
+  }
+}
+```
+
+> Replace `${XQUIK_API_KEY}` with your actual API key, or set the environment variable before launching Claude Desktop.
+
+## Claude Code
+
+Add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "xquik": {
+      "type": "http",
+      "url": "https://xquik.com/mcp",
+      "headers": {
+        "x-api-key": "xq_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## ChatGPT
+
+3 ways to connect ChatGPT to Xquik:
+
+### Option 1: Custom GPT (Recommended)
+
+Create a Custom GPT and add Xquik as an Action using the OpenAPI schema at `https://docs.xquik.com/openapi.json`. Set the API key under Authentication > API Key > Header `x-api-key`.
+
+### Option 2: Agents SDK
+
+Use the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/mcp/) for programmatic access:
+
+```python
+from agents.mcp import MCPServerStreamableHttp
+
+async with MCPServerStreamableHttp(
+    url="https://xquik.com/mcp",
+    headers={"x-api-key": "xq_YOUR_KEY_HERE"},
+    params={},
+) as xquik:
+    # use xquik as a tool provider
+    pass
+```
+
+### Option 3: Developer Mode
+
+ChatGPT Developer Mode supports MCP connectors via OAuth. Add Xquik from **Settings > Developer Mode > MCP Tools > Add**. Enter `https://xquik.com/mcp` as the endpoint. OAuth handles authentication automatically.
+
+## Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.xquik]
+url = "https://xquik.com/mcp"
+http_headers = { "x-api-key" = "xq_YOUR_KEY_HERE" }
+```
+
+## Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "xquik": {
+      "url": "https://xquik.com/mcp",
+      "headers": {
+        "x-api-key": "xq_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## VS Code
+
+Add to `.vscode/mcp.json` (project) or use **MCP: Open User Configuration** (global):
+
+```json
+{
+  "servers": {
+    "xquik": {
+      "type": "http",
+      "url": "https://xquik.com/mcp",
+      "headers": {
+        "x-api-key": "xq_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "xquik": {
+      "serverUrl": "https://xquik.com/mcp",
+      "headers": {
+        "x-api-key": "xq_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## OpenCode
+
+Add to `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "xquik": {
+      "type": "remote",
+      "url": "https://xquik.com/mcp",
+      "headers": {
+        "x-api-key": "xq_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+## MCP Server Architecture
+
+The MCP server (v2) at `https://xquik.com/mcp` provides 2 structured API tools:
+
+| Tool | Description | Cost |
+|------|-------------|------|
+| `explore` | Search the API endpoint catalog (read-only, no network calls) | Free |
+| `xquik` | Execute API calls against your account | Varies by endpoint |
+
+The agent sends structured API requests through the MCP server, which handles authentication and execution within the same first-party infrastructure as the REST API. All 122 REST API endpoints across 12 categories are accessible: account, automations, bot, composition, extraction, integrations, media, monitoring, support, twitter, x-accounts, and x-write.
+
+## After Setup
+
+### Workflow Patterns
+
+| Workflow | Steps (via `xquik` tool) |
+|----------|--------------------------|
+| Set up real-time alerts | `POST /monitors` -> `POST /webhooks` -> `POST /webhooks/{id}/test` |
+| Run a giveaway | `GET /account` -> `POST /draws` |
+| Bulk extraction | `POST /extractions/estimate` -> `POST /extractions` -> `GET /extractions/{id}` |
+| Compose optimized tweet | `POST /compose` (step=compose -> refine -> score) |
+| Subscribe or manage billing | `POST /subscribe` |
+
+### Example Prompts
+
+Try these with your AI agent:
+
+- "Monitor @vercel for new tweets and quote tweets"
+- "How many followers does @elonmusk have?"
+- "Search for tweets mentioning xquik"
+- "What does this tweet say? https://x.com/elonmusk/status/1893456789012345678"
+- "Does @elonmusk follow @SpaceX back?"
+- "Pick 3 winners from this tweet: https://x.com/burakbayir/status/1893456789012345678"
+- "How much would it cost to extract all followers of @elonmusk?"
+- "What's trending in the US right now?"
+- "What's trending on Hacker News today?"
+- "Help me write a tweet about launching my product"
+- "Set up a webhook at https://my-server.com/events for new tweets"
+- "What plan am I on and how much have I used?"

package/skills/x-twitter-scraper/references/mcp-tools.md

@@ -0,0 +1,151 @@
+# Xquik MCP Tools Reference
+
+The MCP server at `https://xquik.com/mcp` provides 2 structured API tools. The agent sends API requests through the server, which handles authentication and execution. All requests stay within the same first-party trust boundary as the REST API (`xquik.com/api/v1`).
+
+## Tools
+
+| Tool | Description | Cost |
+|------|-------------|------|
+| `explore` | Search the API endpoint catalog (read-only, no network calls) | Free |
+| `xquik` | Execute API calls against your account | Varies by endpoint |
+
+### `explore` — Search the API Spec
+
+The tool provides an in-memory `spec.endpoints` array. Filter/search it to find endpoints before calling them.
+
+```typescript
+interface EndpointInfo {
+  method: string;
+  path: string;
+  summary: string;
+  category: string; // account, automations, bot, composition, credits, extraction, integrations, media, monitoring, support, twitter, x-accounts, x-write
+  free: boolean;
+  parameters?: Array<{ name: string; in: 'query' | 'path' | 'body'; required: boolean; type: string; description: string }>;
+  responseShape?: string;
+}
+
+declare const spec: { endpoints: EndpointInfo[] };
+```
+
+Examples:
+
+```javascript
+// Find all free endpoints
+async () => spec.endpoints.filter(e => e.free);
+
+// Find endpoints by category
+async () => spec.endpoints.filter(e => e.category === 'x-write');
+
+// Search by keyword
+async () => spec.endpoints.filter(e => e.summary.toLowerCase().includes('tweet'));
+```
+
+### `xquik` — Execute API Calls
+
+The tool provides `xquik.request()` with auth injected automatically. Never pass API keys.
+
+```typescript
+declare const xquik: {
+  request(path: string, options?: {
+    method?: string;  // default: 'GET'
+    body?: unknown;
+    query?: Record<string, string>;
+  }): Promise<unknown>;
+};
+declare const spec: { endpoints: EndpointInfo[] };
+```
+
+## Tool Selection Rules
+
+Use `explore` first to find endpoints, then `xquik` to call them.
+
+| Goal | Endpoint (via `xquik`) |
+|------|------------------------|
+| Single tweet by ID or URL | `GET /api/v1/x/tweets/{id}` |
+| Full X Article by tweet ID | `GET /api/v1/x/articles/{id}` |
+| Search tweets by keyword/hashtag | `GET /api/v1/x/tweets/search?q=...` |
+| User profile, bio, follower counts | `GET /api/v1/x/users/{username}` |
+| Download media from tweets | `POST /api/v1/x/media/download` |
+| Check follow relationship | `GET /api/v1/x/followers/check?source=A&target=B` |
+| Trending topics by region (X) | `GET /api/v1/trends?woeid=1` |
+| Trending news from 7 sources | `GET /api/v1/radar` (via `xquik` tool) |
+| Activity from monitored accounts | `GET /api/v1/events` |
+| Budget, plan, usage percent | `GET /api/v1/account` |
+| Monitor an X account | `POST /api/v1/monitors` |
+| Set up webhook notifications | `POST /api/v1/webhooks` |
+| Run a giveaway draw | `POST /api/v1/draws` |
+| Subscribe or manage billing | `POST /api/v1/subscribe` |
+| Compose/draft a tweet | `POST /api/v1/compose` (3-step: compose, refine, score) |
+| Link your X username | `PUT /api/v1/account/x-identity` |
+| Analyze tweet style | `POST /api/v1/styles` |
+| Get cached style | `GET /api/v1/styles/{username}` |
+| Compare two styles | `GET /api/v1/styles/compare` |
+| Post a tweet | `POST /api/v1/x/tweets` (requires connected account) |
+| Like/unlike a tweet | `POST`/`DELETE /api/v1/x/tweets/{id}/like` |
+| Retweet | `POST /api/v1/x/tweets/{id}/retweet` |
+| Follow/unfollow | `POST`/`DELETE /api/v1/x/users/{id}/follow` |
+| Send a DM | `POST /api/v1/x/dm/{userId}` |
+| Upload media | `POST /api/v1/x/media` |
+| Create automation flow | `POST /api/v1/automations` |
+| List automation flows | `GET /api/v1/automations` |
+| Add step to flow | `POST /api/v1/automations/{slug}/steps` |
+| Activate/deactivate flow | `PATCH /api/v1/automations/{slug}` |
+| Open support ticket | `POST /api/v1/support/tickets` |
+| List support tickets | `GET /api/v1/support/tickets` |
+| Get user's recent tweets | `GET /api/v1/x/users/{id}/tweets` |
+| Get user's liked tweets | `GET /api/v1/x/users/{id}/likes` |
+| Get user's media tweets | `GET /api/v1/x/users/{id}/media` |
+| Get tweet favoriters (who liked) | `GET /api/v1/x/tweets/{id}/favoriters` |
+| Get mutual followers | `GET /api/v1/x/users/{id}/followers-you-know` |
+| Get bookmarks | `GET /api/v1/x/bookmarks` |
+| Get bookmark folders | `GET /api/v1/x/bookmarks/folders` |
+| Get notifications | `GET /api/v1/x/notifications` |
+| Get home timeline | `GET /api/v1/x/timeline` |
+| Get DM history | `GET /api/v1/x/dm/{userId}/history` |
+| Check credit balance | `GET /api/v1/credits` |
+| Top up credits | `POST /api/v1/credits/topup` |
+
+Use `POST /api/v1/extractions` ONLY for bulk data that simpler endpoints cannot provide (all followers, all replies to a tweet, community members, etc.). Always call `POST /api/v1/extractions/estimate` first.
+
+## Workflow Patterns
+
+| Workflow | Steps |
+|----------|-------|
+| **Set up real-time alerts** | `POST /monitors` -> `POST /webhooks` -> `POST /webhooks/{id}/test` |
+| **Run a giveaway** | `GET /account` -> `POST /draws` |
+| **Bulk extraction** | `POST /extractions/estimate` -> `POST /extractions` -> `GET /extractions/{id}` |
+| **Compose optimized tweet** | `POST /compose` (step=compose -> refine -> score) |
+| **Analyze tweet style** | `POST /styles` -> `GET /styles/{username}` -> `POST /compose` with `styleUsername` |
+| **Post a tweet** | `GET /x/accounts` -> `POST /x/tweets` with `account` + `text` |
+| **Get trending news** | `GET /radar` (free, all 7 sources, via `xquik` tool) -> `POST /compose` with trending topic |
+| **Create automation** | `POST /automations` -> `POST /automations/{slug}/steps` -> `PATCH /automations/{slug}` (activate) |
+| **Open support ticket** | `POST /support/tickets` -> `GET /support/tickets/{id}` |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Combining free and paid calls in `Promise.all` | Call free endpoints first, then paid ones separately. A 402 in Promise.all kills all results |
+| Using `compose` when user wants to send a tweet | `POST /compose` is for drafting. Use `POST /x/tweets` to send |
+| Using `POST /x/tweets` when user wants help writing | Use the 3-step compose flow instead |
+| Falling back to web search when API call fails | Use free data already fetched (radar, styles, compose). Never discard it |
+| Not checking subscription before paid calls | Always attempt the call. Handle 402 by calling `POST /subscribe` for checkout URL |
+| Passing API keys in code | Auth is injected automatically. Never include keys |
+| Using `explore` for API calls | `explore` is read-only spec search. Use `xquik` for actual API calls |
+| Looking up follow/DM by username | Follow and DM endpoints need numeric user ID. Look up via `GET /x/users/{username}` first |
+
+## Unsupported Operations
+
+These are NOT available via the MCP server:
+
+- API key management (create, list, delete)
+- File export (CSV, XLSX, Markdown)
+- Account locale update
+- Scheduled tweets
+
+- Direct X search (use extraction `tweet_search_extractor` for bulk search)
+
+## Cost Reference
+
+- **Free**: account info, compose (all steps), styles (cached lookup/save/delete/compare), drafts, radar (via `xquik` tool, all 7 sources), subscribe, API keys, bot endpoints, integrations, X account management, automations (create, list, update, delete, steps), support tickets, credits (balance check, top up)
+- **Subscription required**: tweet search, user lookup, tweet lookup, follow check, media download (first only, cached free), extractions, draws, style analysis (X API refresh), performance analysis, trends, all write actions (tweet, like, retweet, follow, DM, profile, media upload, communities)