Xcatcher Developer Docs

Public quickstart for calling Xcatcher via REST API (/api/v1) and Remote MCP (/mcp). Xcatcher is optimized for high-concurrency “fresh content” retrieval across large batches of X users.
Base URL: https://xcatcher.top
REST: /api/v1
Remote MCP: /mcp
Auth: Authorization: Bearer xc_live_...
Health: /mcp/health
Important: result files are not exposed as public direct links. Always download via GET /api/v1/tasks/<task_id>/download with the same Bearer token.
High-throughput example (Normal mode): ~1000 X users → ~5000 tweets within ~2 minutes (typical under normal conditions). (For API limits: submit in batches; see “Modes & Scale” below.)

Modes & Scale (Normal vs Deep)

Xcatcher supports two task modes via both REST and MCP. Choose based on speed/cost vs deeper coverage.

  • normal — optimized for fast, “latest posts” retrieval at scale.
  • deep — intended for deeper collection/enrichment per user, typically longer and higher cost.
Billing (points):
  • normal: 1 point per user in the request.
  • deep: 10 points per user (10×) in the request.
Scale note: a single task request may enforce a max user count. If you need ~1000 users, split into multiple tasks (e.g., 2×500), then aggregate results on your side.

High-Concurrency “Fresh Feed” Workflow

The recommended workflow for agents and automated pipelines is: create → poll → download. Use idempotency_key to keep retries safe and avoid duplicate charges.

  • Batch users (e.g., 200–500 per task) and run tasks concurrently if your quota allows.
  • Poll every 5–10 seconds; if you receive 429, back off and honor Retry-After.
  • Use normal for fast latest-post snapshots; use deep for deeper pulls.
# Example batching strategy (pseudo-shell)
# - Split 1000 users into 2 tasks of 500 users each
# - Submit both tasks, then poll each task_id until done

# Task A users: users_a.json (500 usernames)
# Task B users: users_b.json (500 usernames)

BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"

curl -s -X POST "$BASE/api/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"normal","users": [/* 500 usernames */], "idempotency_key":"batch-a-001"}'

curl -s -X POST "$BASE/api/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"normal","users": [/* 500 usernames */], "idempotency_key":"batch-b-001"}'
Tip: if your client might auto-retry (network errors, timeouts), always provide a stable idempotency_key.

Quickstart (REST API)

Typical flow: (1) obtain an API key, (2) verify it, (3) create a task, (4) poll status, (5) download the xlsx result. The server binds tasks to the user derived from your Bearer token. 

# 0) Base + key placeholder
BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"

# 1) (Optional) Register (no captcha) → returns api_key
curl -s -X POST "$BASE/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

# 2) Login (no captcha) → rotates and issues a new api_key (old key may be revoked)
curl -s -X POST "$BASE/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'

# 3) Verify token / connectivity
curl -s "$BASE/api/v1/me" \
  -H "Authorization: Bearer $API_KEY"

# 4) Create task (side-effect: consumes points)
#    mode: "normal" | "deep"
#    users: array of X usernames (strings) — submit in batches for large sets
#    idempotency_key: optional but recommended for safe retries
curl -s -X POST "$BASE/api/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"normal","users":["elonmusk","naval"],"idempotency_key":"YOUR_IDEMPOTENCY_KEY"}'

# 5) Poll status until done
TASK_ID=10136
curl -s "$BASE/api/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

# 6) Download result (xlsx stream, not JSON)
curl -L -o result.xlsx \
  -H "Authorization: Bearer $API_KEY" \
  "$BASE/api/v1/tasks/$TASK_ID/download"
Notes:
  • idempotency_key is recommended for clients/agents that may retry requests.
  • On success, task creation returns fields like cost_points and balance_after.

Quickstart (Google ADK → Remote MCP)

ADK can connect to Remote MCP (Streamable HTTP) directly. Use your Bearer key in headers. Tool names are filtered to the four core tools. 

import os
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

toolset = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://xcatcher.top/mcp",
        headers={"Authorization": "Bearer xc_live_xxx"},
        # timeout=120,  # optional (param name may vary by ADK version)
    ),
    tool_filter=[
        "create_crawl_task",
        "get_task_status",
        "get_result_download_url",
        "cancel_task",
    ],
)
Remote MCP tools (high level):
  • create_crawl_task: creates a crawl task (side-effect: consumes points). Supports mode and optional idempotency_key.
  • get_task_status: returns task status and whether result is ready.
  • get_result_download_url: returns an absolute download_url for the xlsx file (still requires Bearer).
  • cancel_task: cancels a queued task (where supported by backend policy).

Error Codes (client branching)

  • 401 AUTH_MISSING / AUTH_INVALID: missing Bearer header, or token invalid/expired/blank/contaminated.
  • 409 RESULT_NOT_READY: task is not completed yet; keep polling.
  • 429 RATE_LIMITED: request rate exceeded; respect Retry-After and back off.
  • 599 UPSTREAM_UNREACHABLE: MCP server cannot reach the internal API or timed out (check container network / INTERNAL_API_BASE / upstream health).
# Health check (public)
curl -s "https://xcatcher.top/mcp/health"

Polling Recommendations

  • get_task_status: poll every 5–10 seconds in normal conditions.
  • If you receive 429, increase interval and honor Retry-After.
  • Use idempotency_key for create calls to avoid double-charges during retries.

Pricing / Quota (Points)

  • Task creation consumes points. Cost depends on mode and number of users.
  • Exact cost is returned by the API as cost_points and your remaining balance as balance_after.
  • The server may enforce per-key rate limits and/or concurrency limits; on violation you may see 429.

Top-up / Payment (ETH on Ethereum)

Create a top-up order to add points to your account. The server returns the on-chain receiving address and the exact amount to send. Always poll status until finished.

  • Minimum: amount_usd >= 20
  • Authentication: Bearer required (Authorization)
  • Flow: POST /mcp/payment/create → GET /mcp/payment/status/<payment_id>
BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"

# Create top-up order (ETH on Ethereum)
curl -s -X POST "$BASE/mcp/payment/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":20,"pay_currency":"eth"}'

# Check order status
PAYMENT_ID="5851596631"
curl -s "$BASE/mcp/payment/status/$PAYMENT_ID" \
  -H "Authorization: Bearer $API_KEY"
Notes:
  • Send the exact pay_amount of pay_currency to pay_address.
  • Network fees are paid by the sender wallet; do not subtract fees from pay_amount.
  • Security: payment endpoints use the same Bearer key; missing/invalid auth returns 401.

Top-up / Payment (USDT on Solana)

If you prefer Solana, you can top up using USDT on Solana (SPL). Use the Solana-specific currency code and follow the same create → poll pattern.

Important: The pay_currency string is forwarded to the payment provider. Use the correct currency code for your network (for USDT on Solana, commonly usdtsol). 
BASE="https://xcatcher.top"
API_KEY="xc_live_xxx"

# Create top-up order (USDT on Solana / SPL)
curl -s -X POST "$BASE/mcp/payment/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_usd":20,"pay_currency":"usdtsol"}'

# Check order status
PAYMENT_ID="5851596631"
curl -s "$BASE/mcp/payment/status/$PAYMENT_ID" \
  -H "Authorization: Bearer $API_KEY"
Solana notes:
  • Ensure your wallet is sending USDT on the Solana network (SPL), not ERC-20/TRC-20.
  • Always use the returned pay_address and pay_amount from the API response.
Tip: You can link this page from your login screen and/or dashboard for discoverability: /docs.