Zad Top HTTP API

把商店、网站或机器人接到驱动 @ZadTopBot 的同一引擎。一把密钥认证，异步兑换和检查任务，每个卡密都有详细结果。

基础地址

https://api.zadtop.com

获取密钥

打开 @ZadTopBot → 订阅 → HTTP API。
持有有效套餐，并加上 API 附加项 — 每 30 天固定 15 USDT，与套餐无关。
点新 API 密钥。创建新密钥会立刻作废上一把。

认证

每次请求都在 X-API-Key 头里发送密钥。套餐或 API 附加项到期后访问暂停，续订后同一把密钥立刻恢复。

X-API-Key: pk_YOUR_KEY_HERE

任务如何工作

兑换和批量检查是异步的。POST 会校验请求并立刻返回 job_id；再用 GET /v1/jobs/{id} 读取结果 — 或加上 ?wait=25，让请求在任务完成时返回，而不必轮询。

任务变成 done 并不表示每张卡都成功。它表示工作已经做完。每张卡的结果在 results[].success，失败时看 err_code。

curl -sS -X POST https://api.zadtop.com/v1/jobs/instant-redeem \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"2186053213","codes":["4233939008625064"],"game":"freefire"}'

不兑换地检查卡密

每张卡返回一个状态 — valid、used、invalid 等 — 加上 with_value 时还有礼包面值。什么都不会被兑换，好卡依然是好卡。

curl -sS -X POST https://api.zadtop.com/v1/codes/check \
  -H "X-API-Key: pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"codes":["7397062240255931","5539151276341494"],"with_value":true}'

主要路径

POST	`/v1/jobs/instant-redeem`	为玩家 ID 兑换 Free Fire、PUBG、Yalla Ludo 或 Jawaker 卡密。
POST	`/v1/jobs/stock-redeem`	按礼包从已存库存兑换。
POST	`/v1/codes/check`	不兑换地读取最多 20 张卡。
POST	`/v1/jobs/code-check`	同样的检查，最多 200 张卡，作为任务。
GET	`/v1/player/lookup`	玩家 ID 的游戏内名称和地区。
GET	`/v1/jobs/{id}`	一个任务的状态和结果。
GET	`/v1/stock/summary`	你持有的库存，按游戏和礼包。
POST	`/v1/order/screenshot`	商店的订单确认，PNG 格式。
GET	`/v1/me · /v1/quota · /v1/history · /v1/players`	账户、剩余限额、历史订单、已存玩家。
POST	`/v1/subscription/purchase · purchase-api-addon`	用 USDT 余额购买或延长套餐。

游戏

所有游戏使用同一组路径 — 只需修改 game。礼包和示例见参考文档和游戏页面。

`freefire`	兑换 · 卡密检查 · 玩家查询
`pubg`	兑换 · 卡密检查 · 玩家查询
`ludo` / `ludogold`	带 `tier` 兑换 · 玩家查询 · 无卡密检查
`jawaker`	兑换 · 玩家查询 · 无卡密检查

每日限额

每个套餐都有每日限额，在 UTC 午夜重置，由套餐覆盖的游戏共享。兑换每个卡密 1 次请求，卡密检查每张 1 次，玩家查询 0.25 次。商店的拒绝会计入；我们这边的失败会自动退回限额。机器人和 API 共用同一限额。

错误

校验返回 400，代码在 detail.error 里；认证返回 401 或 403；调用过多返回 429。安全重启期间新任务返回 503 SERVICE_DRAINING — 请稍后再试。完整列表在完整参考中。

请求错误

401		API 密钥缺失、输错或已被新密钥替换。请在机器人中重新复制。
403		没有带 API 附加项的有效套餐。请在机器人中续费。
403	`GAME_NOT_IN_PLAN`	你的套餐不包含此游戏。请在机器人中把游戏加入套餐。
400	`INVALID_CODE`	不是此游戏的有效卡密。未发送也未扣费。
400	`INVALID_PLAYER_ID`	不是此游戏的有效玩家 ID。未发送也未扣费。
400	`INSUFFICIENT_BALANCE`	余额不足以支付。请在机器人中充值。
429	`QUOTA_EXHAUSTED`	今天剩余请求不足。将在 UTC 午夜或购买套餐时恢复。
429	`RATE_LIMIT`	调用过多。等待 Retry-After 秒后重试。
503	`SERVICE_DRAINING`	短暂维护。未加入队列；请几秒后重试。

每张卡的结果（err_code）

`CODE_ALREADY_USED`	该卡已被兑换。请勿重试。
`INVALID_CODE`	商店无法识别该卡。请检查输入是否正确。
`REGION_MISMATCH`	该卡所属地区与玩家不同。
`PLAYER_NOT_FOUND`	没有此玩家 ID 的账户。卡未被使用。
`NETWORK`	在得到结果前出现临时问题。已退回；请用同一卡密重试。

地区

几乎所有国家的玩家都受支持。Garena 根本不卖兑换券的地方 — 美国、阿根廷、智利和俄罗斯 — 玩家查询会返回 422 UNSUPPORTED_REGION，任何卡密都还不会有风险。