Xcatcher (x402 + X 任务)

使用此技能可以：

• - 通过 Solana 上的 x402 购买 Xcatcher 积分（USDC）
• 获取 API 密钥
• 创建 X 爬取任务
• 轮询任务状态
• 下载 XLSX 结果

基础 URL：https://xcatcher.top
REST 基础：https://xcatcher.top/api/v1
可选健康检查：https://xcatcher.top/mcp/health

此技能的功能

此技能提供付费 X 数据收集的端到端流程：

1. 1. 请求 x402 积分报价
2. 使用 Solana USDC 支付报价
3. 将已支付的报价兑换为 API 密钥
4. 使用 API 密钥创建爬取任务
5. 轮询任务状态直至结果就绪
6. 下载 XLSX 结果文件

前提条件

本地工具：

• - curl
• jq
• base64

可选：

• - python3 用于简单的 JSON 数学示例

认证：

• - 开始前不需要 XCATCHERAPIKEY
• 成功调用 buypoints 后将获得 XCATCHERAPI_KEY
• 后续认证调用需设置：

定价模型

任务成本：

• - mode=normal：每个用户 1 积分
• mode=deep：每个用户 10 积分

预估成本：

• - estimatedcost = userscount × (mode == normal ? 1 : 10)

支持的支付链：

• - solana
• 如果服务器配置启用，报价负载也可能提及其他支持的网络

切勿硬编码任何 USDC 到积分的转换率。始终信任实时报价响应。

0) 可选健康检查

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

1) 获取 x402 报价

注意：

• - 报价会快速过期
• 创建报价后立即支付
• 保存 quote_id

bash
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)
USDC_MINT=$(jq -r .accepts.solana.asset quote.json)
PAY_TO=$(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 USDC_AMOUNT=$(python3 - < import json
q=json.load(open(quote.json))
amt=int(q[accepts][solana][maxAmountRequired])
print(amt/1000000)
PY
)
echo

重要：

• - 保留 QUOTE_ID
• 在下一步购买中使用
• 如果报价过期，请创建新报价

2) 在 Solana 主网上支付 USDC

向 PAYTO 发送至少 AMOUNTATOMIC 的 USDC（SPL）。

然后记录 Solana 交易签名：

bash
SOLSIG=YOURSOLANATXSIGNATURE

3) 构建 PAYMENT-SIGNATURE 头部

规则：

• - 进行一次 base64 编码
• 不要双重编码
• 不要在头部值外包裹额外引号

bash
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) 购买积分并获取 API 密钥

bash
BASE=https://xcatcher.top

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

APIKEY=$(jq -r .apikey buy.json)
echo APIKEY=$APIKEY

export XCATCHERAPIKEY=$API_KEY
echo 已导出 XCATCHERAPIKEY。
echo

5) 验证余额

bash
BASE=https://xcatcher.top

curl -sS $BASE/api/v1/me \
-H Authorization: Bearer $XCATCHERAPIKEY \
| jq .
echo

如果收到 402：

• - 报价可能已过期
• 支付证明可能无效
• 使用新报价和新支付证明重新执行步骤 1 到 4

6) 创建爬取任务

规则：

• - users 是不带 @ 的 X 用户名
• 始终提供 idempotencykey
• 如果重试相同的逻辑请求，请使用相同的 idempotencykey

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

export MODE USERS_JSON

echo ESTIMATEDCOSTPOINTS=$(python3 - < 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 $USERS_JSON \
{mode:$mode, users:$users, idempotency_key:$idem}) \
| tee task.json | jq .
echo

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

7) 轮询任务状态直至就绪

当出现 downloadurl 或 resultpath 时停止。

bash
BASE=https://xcatcher.top

while true; do
J=$(curl -sS $BASE/api/v1/tasks/$TASK_ID \
-H Authorization: Bearer $XCATCHERAPIKEY)

echo $J | jq {taskid,status,statuscode,updatedtime,errormessage,resultpath,downloadurl}

HAS=$(echo $J | jq -r (.downloadurl // .resultpath // ) | length)
if [ $HAS -gt 0 ]; then
echo 完成
break
fi

sleep 5
done
echo

8) 下载 XLSX 结果

bash
BASE=https://xcatcher.top

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

echo 已保存：task${TASKID}.xlsx
echo

错误处理

• - 401：Bearer 令牌缺失或无效

• - 402：报价无效、支付证明无效或报价已过期

• - 429：请求频率受限

• - 任务延迟或上游不可用

给代理的提示

• - 优先使用实时报价响应，而非任何缓存假设。
• 优先使用明确的 idempotency_key 值进行重试。
• 将任务结果视为私有数据，始终使用相同的 Bearer 令牌下载。
• 不要假设结果文件是公共 URL。