x-developer 2.3.0

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

@@ -0,0 +1,132 @@
+# Xquik Pricing
+
+Xquik is the most affordable X data API available. All metered operations deduct credits from a single shared pool.
+
+## Subscription
+
+| | |
+|---|---|
+| **Base plan** | $20/month |
+| **Included monitors** | 1 |
+| **Additional monitors** | $5/month each |
+| **Credit value** | 1 credit = $0.00015 |
+
+## Per-Operation Costs
+
+### Read operations — 1 credit ($0.00015)
+
+| Operation | Unit |
+|-----------|------|
+| Get tweet | per call |
+| Search tweets | per tweet returned |
+| User tweets | per tweet returned |
+| User likes | per result |
+| User media | per result |
+| Tweet favoriters | per result |
+| Followers you know | per result |
+| Bookmarks | per result |
+| Bookmark folders | per call |
+| Notifications | per result |
+| Timeline | per result |
+| DM history | per result |
+| Download media | per media item |
+| Get user | per call |
+| Verified followers | per result |
+
+### Read operations — 3 credits ($0.00045)
+
+| Operation | Unit |
+|-----------|------|
+| Trends | per call |
+
+### Read operations — 7 credits ($0.00105)
+
+| Operation | Unit |
+|-----------|------|
+| Follow check | per call |
+| Get article | per call |
+
+### Write operations — 10 credits ($0.0015)
+
+All write actions: create/delete tweet, like, unlike, retweet, follow, unfollow, send DM, update profile/avatar/banner, upload media, community actions.
+
+### Extractions & draws
+
+Draws: 1 credit per participant. Extraction cost depends on the tool type:
+
+| Credits/result | Extraction types |
+|----------------|-----------------|
+| 1 | Tweets, replies, quotes, mentions, posts, likes, media, tweet search, favoriters, retweeters, community members, people search, list members, list followers |
+| 1 | Followers, following, verified followers |
+| 5 | Articles |
+
+### Free operations ($0)
+
+Monitors, webhooks, integrations, account status, radar (7 sources), extraction/draw history, cost estimates, tweet composition (compose, refine, score), style cache management, drafts, support tickets, API key management, X account management.
+
+## Price Comparison vs Official X API
+
+| | Xquik | X API Basic | X API Pro |
+|---|---|---|---|
+| **Monthly cost** | **$20** | $100 | $5,000 |
+| **Cost per tweet read** | **$0.00015** | ~$0.01 | ~$0.005 |
+| **Cost per user lookup** | **$0.00015** | ~$0.01 | ~$0.005 |
+| **Write actions** | **$0.0015** | Limited | Limited |
+| **Bulk extraction** | **$0.00015/result** | Not available | Not available |
+| **Monitoring + webhooks** | **Free** | Not available | Not available |
+| **Giveaway draws** | **$0.00015/entry** | Not available | Not available |
+
+## Pay-Per-Use
+
+Two options without a monthly subscription:
+
+**Credits**: Top up credits via `POST /credits/topup` ($10 minimum). 1 credit = $0.00015. Works with all 122 endpoints.
+
+**MPP**: 32 X-API endpoints accept anonymous on-chain payments. No account needed.
+
+| Endpoint | Price | Unit |
+|----------|-------|------|
+| `GET /x/tweets/{id}` | $0.00015 | per call |
+| `GET /x/tweets/search` | $0.00015 | per tweet |
+| `GET /x/tweets/{id}/quotes` | $0.00015 | per tweet |
+| `GET /x/tweets/{id}/replies` | $0.00015 | per tweet |
+| `GET /x/tweets/{id}/retweeters` | $0.00015 | per user |
+| `GET /x/tweets/{id}/favoriters` | $0.00015 | per user |
+| `GET /x/tweets/{id}/thread` | $0.00015 | per tweet |
+| `GET /x/users/{id}` | $0.00015 | per call |
+| `GET /x/users/{id}/tweets` | $0.00015 | per tweet |
+| `GET /x/users/{id}/likes` | $0.00015 | per tweet |
+| `GET /x/users/{id}/media` | $0.00015 | per tweet |
+| `GET /x/followers/check` | $0.00105 | per call |
+| `GET /x/articles/{tweetId}` | $0.00105 | per call |
+| `POST /x/media/download` | $0.00015 | per media item |
+| `GET /x/trends` | $0.00045 | per call |
+| `GET /trends` | $0.00045 | per call |
+| `GET /x/communities/{id}/info` | $0.00015 | per call |
+| `GET /x/communities/{id}/members` | $0.00015 | per user |
+| `GET /x/communities/{id}/moderators` | $0.00015 | per user |
+| `GET /x/communities/{id}/tweets` | $0.00015 | per tweet |
+| `GET /x/communities/search` | $0.00015 | per community |
+| `GET /x/communities/tweets` | $0.00015 | per tweet |
+| `GET /x/lists/{id}/followers` | $0.00015 | per user |
+| `GET /x/lists/{id}/members` | $0.00015 | per user |
+| `GET /x/lists/{id}/tweets` | $0.00015 | per tweet |
+| `GET /x/users/batch` | $0.00015 | per user |
+| `GET /x/users/search` | $0.00015 | per user |
+| `GET /x/users/{id}/followers` | $0.00015 | per user |
+| `GET /x/users/{id}/followers-you-know` | $0.00015 | per user |
+| `GET /x/users/{id}/following` | $0.00015 | per user |
+| `GET /x/users/{id}/mentions` | $0.00015 | per tweet |
+| `GET /x/users/{id}/verified-followers` | $0.00015 | per user |
+
+SDK: `npm i mppx viem` (TypeScript). Handles the 402 challenge/credential flow automatically.
+
+## Credits
+
+Prepaid credits for metered operations. 1 credit = $0.00015. Top up via `POST /credits/topup` ($10 minimum).
+
+Check balance: `GET /credits` — returns `balance`, `lifetimePurchased`, `lifetimeUsed`.
+
+## Extra Usage
+
+Enable from dashboard to continue metered calls beyond included allowance. Tiered spending limits: $5 -> $7 -> $10 -> $15 -> $25 (increases with each paid overage invoice).

package/skills/x-twitter-scraper/references/python-examples.md

@@ -0,0 +1,152 @@
+# Xquik Python Examples
+
+Python equivalents of the JavaScript examples in SKILL.md.
+
+## Authentication
+
+```python
+import requests
+
+API_KEY = "xq_YOUR_KEY_HERE"
+BASE = "https://xquik.com/api/v1"
+HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
+```
+
+## Retry with Exponential Backoff
+
+```python
+import time, random
+
+def xquik_fetch(path, method="GET", json_body=None, max_retries=3):
+    base_delay = 1.0
+
+    for attempt in range(max_retries + 1):
+        response = requests.request(
+            method,
+            f"{BASE}{path}",
+            headers=HEADERS,
+            json=json_body,
+        )
+
+        if response.ok:
+            return response.json()
+
+        retryable = response.status_code == 429 or response.status_code >= 500
+        if not retryable or attempt == max_retries:
+            error = response.json()
+            raise Exception(f"Xquik API {response.status_code}: {error['error']}")
+
+        retry_after = response.headers.get("Retry-After")
+        delay = int(retry_after) if retry_after else base_delay * (2 ** attempt) + random.uniform(0, 1)
+        time.sleep(delay)
+```
+
+## Extraction Workflow
+
+```python
+# Step 1: Estimate
+estimate = xquik_fetch("/extractions/estimate", method="POST", json_body={
+    "toolType": "reply_extractor",
+    "targetTweetId": "1893704267862470862",
+})
+
+if not estimate["allowed"]:
+    print(f"Would exceed quota: {estimate['projectedPercent']}%")
+    exit()
+
+# Step 2: Create job
+job = xquik_fetch("/extractions", method="POST", json_body={
+    "toolType": "reply_extractor",
+    "targetTweetId": "1893704267862470862",
+})
+
+# Step 3: Poll until complete (large jobs may return "running")
+while job["status"] in ("pending", "running"):
+    time.sleep(2)
+    job = xquik_fetch(f"/extractions/{job['id']}")
+
+# Step 4: Get results
+cursor = None
+results = []
+
+while True:
+    path = f"/extractions/{job['id']}"
+    if cursor:
+        path += f"?after={cursor}"
+    page = xquik_fetch(path)
+    results.extend(page["results"])
+
+    if not page["hasMore"]:
+        break
+    cursor = page["nextCursor"]
+
+print(f"Extracted {len(results)} results")
+```
+
+## Giveaway Draw
+
+```python
+# Create draw with all filters
+draw = xquik_fetch("/draws", method="POST", json_body={
+    "tweetUrl": "https://x.com/burakbayir/status/1893456789012345678",
+    "winnerCount": 3,
+    "backupCount": 2,
+    "uniqueAuthorsOnly": True,
+    "mustRetweet": True,
+    "mustFollowUsername": "burakbayir",
+    "filterMinFollowers": 50,
+    "filterAccountAgeDays": 30,
+    "requiredKeywords": ["giveaway"],
+})
+
+# Get winners
+details = xquik_fetch(f"/draws/{draw['id']}")
+for winner in details["winners"]:
+    role = "BACKUP" if winner["isBackup"] else "WINNER"
+    print(f"{role} #{winner['position']}: @{winner['authorUsername']}")
+```
+
+## Webhook Handler (Flask)
+
+```python
+import hmac, hashlib, json, os
+from flask import Flask, request
+
+app = Flask(__name__)
+# Per-webhook secret from POST /webhooks response, not a Xquik account credential
+WEBHOOK_SECRET = os.environ["XQUIK_WEBHOOK_SECRET"]
+processed_hashes = set()  # Use Redis/DB in production
+
+def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
+    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)
+
+EVENT_HANDLERS = {
+    "tweet.new": lambda u, d: print(f"New tweet from @{u}: {d['text']}"),
+    "tweet.reply": lambda u, d: print(f"Reply from @{u}: {d['text']}"),
+    "tweet.quote": lambda u, d: print(f"Quote from @{u}: {d['text']}"),
+    "tweet.retweet": lambda u, d: print(f"Retweet by @{u}"),
+    "follower.gained": lambda u, d: print(f"@{u} gained follower: @{d['followerUsername']}"),
+    "follower.lost": lambda u, d: print(f"@{u} lost follower: @{d['followerUsername']}"),
+}
+
+@app.route("/webhook", methods=["POST"])
+def webhook():
+    signature = request.headers.get("X-Xquik-Signature", "")
+    payload = request.get_data()
+
+    if not verify_signature(payload, signature, WEBHOOK_SECRET):
+        return "Invalid signature", 401
+
+    payload_hash = hashlib.sha256(payload).hexdigest()
+    if payload_hash in processed_hashes:
+        return "Already processed", 200
+    processed_hashes.add(payload_hash)
+
+    event = json.loads(payload)
+    handler = EVENT_HANDLERS.get(event["eventType"])
+    if handler:
+        handler(event["username"], event["data"])
+
+    return "OK", 200
+```