Xcatcher Mcp Manifest

---

name: x402-x-tweet-fetcher description: Top up Xcatcher points via x402 on Solana (USDC), obtain an API key, create X crawl tasks, poll status, and download XLSX results. homepage: https://xcatcher.top/docs/ user-invocable: true metadata: {"openclaw":{"emoji":"🐦","homepage":"https://xcatcher.top/docs/","requires":{"bins":["curl","jq","base64"],"env":["XCATCHERAPIKEY"]},"primaryEnv":"XCATCHERAPIKEY"}} ---

Xcatcher (x402 + Tasks)

Use this skill to:

• buy points via x402 on Solana (USDC),
• obtain an API key,
• create crawl tasks,
• poll task status,
• download XLSX results.

Base URL: https://xcatcher.top REST base: https://xcatcher.top/api/v1 Optional health: https://xcatcher.top/mcp/health

Requirements

• curl, jq, base64
• Set XCATCHER_API_KEY for authenticated calls (you will obtain it in step 4 if you don't have one).

Points pricing (task cost)

• mode=normal: 1 point / user
• mode=deep: 10 points / user
• estimatedcost = userscount × (mode == normal ? 1 : 10)
• support chain: base / sol

> Do not hardcode any USDC→points rate. Always trust the quote response.

---

0) Optional health check

BASE="https://xcatcher.top" curl -sS "$BASE/mcp/health" echo

---

1) Get an x402 quote (points → Solana USDC payment instructions)

Notes:

• Quotes expire quickly (often ~60s). Pay immediately after receiving the quote.

BASE="https://xcatcher.top" POINTS=1

curl -sS "$BASE/api/v1/x402/quote?points=$POINTS" | tee quote.json echo

QUOTEID=$(jq -r '.quoteid' quote.json) USDCMINT=$(jq -r '.accepts.solana.asset' quote.json) PAYTO=$(jq -r '.accepts.solana.payTo' quote.json) AMOUNT_ATOMIC=$(jq -r '.accepts.solana.maxAmountRequired' quote.json)

echo "QUOTEID=$QUOTEID" echo "USDCMINT=$USDCMINT" echo "PAYTO=$PAYTO" echo "AMOUNTATOMIC=$AMOUNTATOMIC" echo "USDCAMOUNT=$(python3 - <<'PY' import json q=json.load(open("quote.json")) amt=int(q["accepts"]["solana"]["maxAmountRequired"]) print(amt/1000_000) PY )" echo

QUOTE_ID must save ---

2) Pay USDC on Solana mainnet

Send USDC (SPL) to PAYTO for at least AMOUNTATOMIC (USDC has 6 decimals). Record the Solana transaction signature, then set it below.

SOLSIG="YOURSOLANATXSIGNATURE"

---

3) Build PAYMENT-SIGNATURE header (base64 of UTF-8 JSON)

Rules:

• Base64 encode once (no double encoding).
• Do not wrap the header value in extra quotes.

PAYMENTSIGNATUREB64=$(jq -nc --arg sig "$SOL_SIG" \ '{"x402Version":1,"scheme":"exact","network":"solana:mainnet","payload":{"signature":$sig}}' \ | base64 | tr -d '\n')

echo "PAYMENTSIGNATUREB64=$PAYMENTSIGNATUREB64" echo

---

4) Buy points (quoteid + PAYMENT-SIGNATURE → apikey)

BASE="https://xcatcher.top"

curl -sS -X POST "$BASE/api/v1/x402/buypoints" \ -H "Content-Type: application/json" \ -H "PAYMENT-SIGNATURE: $PAYMENTSIGNATUREB64" \ -d "$(jq -nc --arg q "$QUOTEID" '{quote_id:$q}')" \ | tee buy.json echo

APIKEY=$(jq -r '.apikey' buy.json) echo "APIKEY=$APIKEY" export XCATCHERAPIKEY="$APIKEY" echo "XCATCHERAPI_KEY exported." echo

---

5) Verify balance (must-do)

BASE="https://xcatcher.top" curl -sS "$BASE/api/v1/me" \ -H "Authorization: Bearer $XCATCHERAPIKEY" \ | jq . echo

If you get 402 here or later:

• Most common causes: quote expired or payment proof invalid.
• Fix: redo steps 1 → 4 with a NEW quote and NEW payment.

---

6) Create crawl task

Rules:

• users are X usernames without '@'
• always provide idempotency_key
• if retrying the same logical request, reuse the same idempotency_key

BASE="https://xcatcher.top" MODE="normal" IDEM="test-idem-001" USERS_JSON='["user1","user2"]'

echo "ESTIMATEDCOSTPOINTS=$(python3 - <<'PY' import json, os users=json.loads(os.environ.get("USERS_JSON","[]")) mode=os.environ.get("MODE","normal") per=1 if mode=="normal" else 10 print(len(users)*per) PY )" echo

curl -sS -X POST "$BASE/api/v1/tasks" \ -H "Authorization: Bearer $XCATCHERAPIKEY" \ -H "Content-Type: application/json" \ -d "$(jq -nc --arg mode "$MODE" --arg idem "$IDEM" --argjson users "$USERSJSON" \ '{mode:$mode, users:$users, idempotencykey:$idem}')" \ | tee task.json | jq . echo

TASKID=$(jq -r '.taskid' task.json) echo "TASKID=$TASKID" echo

---

7) Poll task status until ready

Stop when downloadurl or resultpath is present.

BASE="https://xcatcher.top" while true; do J=$(curl -sS "$BASE/api/v1/tasks/$TASKID" -H "Authorization: Bearer $XCATCHERAPIKEY") echo "$J" | jq '{taskid,status,statuscode,updatedtime,errormessage,resultpath,downloadurl}' HAS=$(echo "$J" | jq -r '(.downloadurl // .result_path // "") | length') if [ "$HAS" -gt 0 ]; then echo "DONE" break fi sleep 5 done echo

---

8) Download result (XLSX)

Download requires the same Bearer token; results are not public.

BASE="https://xcatcher.top" curl -sS -L -o "task${TASKID}.xlsx" \ -H "Authorization: Bearer $XCATCHERAPIKEY" \ "$BASE/api/v1/tasks/$TASK_ID/download"

echo "Saved: task${TASKID}.xlsx" echo

---

Failure handling

• 401: Bearer token missing/invalid → obtain API key via buypoints or set XCATCHERAPI_KEY correctly.
• 402: quote/proof invalid or expired → redo quote + pay + buy_points (steps 1–4).
• 429: rate limited → backoff; respect Retry-After if present.
• Task stuck / upstream issues → report clearly; poll with increasing interval if needed.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lvpiggyqq
• Source: lvpiggyqq/xcatcher-mcp-manifest
• License: MIT
• Homepage: https://xcatcher.top/

Install and usage instructions live in the source repository linked above.