几分钟了解如何
查询榜单与招募数据

开始前准备

JX3TNT 开放平台复用主站手机号账号。你不需要再记一套账号，但需要单独提交开发者接入申请。

身份验证

调用接口时，把 Token 放在请求头中。下面的 <你的 Token> 替换成开发者中心创建时显示的内容。

Token 创建成功时只完整显示一次。建议保存在机器人服务端的环境变量或安全配置中，不要直接写进公开代码。

最简单的调用示例

curl -H "Authorization: Bearer <你的 Token>" \
  "https://api.jx3tnt.com/v1/recruitments/snapshot.png" \
  --output recruitments.png

建议机器人先读取这个接口，不要把赛季或 Boss ID 长期写死。需要查看历史赛季时，可以增加 seasonId。

curl -H "Authorization: Bearer <你的 Token>" \
  "https://api.jx3tnt.com/v1/meta"

需要填写的参数

查询“乾坤一掷”的角色“咸鱼”

curl -G "https://api.jx3tnt.com/v1/characters/rankings" \
  -H "Authorization: Bearer <你的 Token>" \
  --data-urlencode "serverName=乾坤一掷" \
  --data-urlencode "characterName=咸鱼"

返回示例（字段结构示意）

{
  "ok": true,
  "query": {
    "serverName": "乾坤一掷",
    "characterName": "咸鱼"
  },
  "snapshotVersion": "2026-07-22-01",
  "generatedAt": "2026-07-22T03:00:00.000Z",
  "snapshotUpdatedAt": "2026-07-22T03:00:00.000Z",
  "snapshotUpdatedAtText": "2026-07-22 11:00:00（北京时间）",
  "data": [
    {
      "leaderboardKind": "grandmaster_peak",
      "rank": 12,
      "value": 113.0126,
      "score": 113.0126,
      "character": {
        "serverName": "乾坤一掷",
        "characterName": "咸鱼",
        "schoolName": "七秀",
        "kungfuId": "10081",
        "kungfuName": "冰心诀"
      },
      "reportUrl": "/reports/..."
    }
  ]
}

查看这个角色在“笑妆娘”的分值和 DPS

curl -G "https://api.jx3tnt.com/v1/characters/rankings" \
  -H "Authorization: Bearer <你的 Token>" \
  --data-urlencode "serverName=乾坤一掷" \
  --data-urlencode "characterName=咸鱼" \
  --data-urlencode "bossId=笑妆娘"

返回空值时怎么显示

当 data 是空数组时，请在原本显示榜单名次或分值的位置显示 message。如果你的产品支持点击链接，请把 action.text 显示为文字，并链接到 action.url。

{
  "ok": true,
  "data": [],
  "message": "该角色数据未进入榜单，如需上榜，请前往www.Jx3TNT.com上传战报。",
  "action": {
    "text": "www.Jx3TNT.com 上传战报。",
    "url": "https://www.jx3tnt.com/"
  }
}

机器人无数据提示（Markdown）

该角色数据未进入榜单，如需上榜，请前往 [www.Jx3TNT.com 上传战报。](https://www.jx3tnt.com/)

使用场景建议

详细榜单与深度数据：建议设计成独立命令或单独查询页，按榜单、Boss、门派或心法调用对应接口。角色接口负责角色摘要；名侠榜完整列表仍通过 /v1/leaderboards/mingxia_regular_dps 单独查询，避免让一次角色查询返回过大的结果。

可查询的榜单

可选筛选参数

查询名侠榜前 100

curl -G "https://api.jx3tnt.com/v1/leaderboards/mingxia_regular_dps" \
  -H "Authorization: Bearer <你的 Token>" \
  --data-urlencode "dungeonId=<副本 ID>" \
  --data-urlencode "bossId=<Boss ID>" \
  --data-urlencode "limit=100"

查询一派宗师

curl -G "https://api.jx3tnt.com/v1/leaderboards/grandmaster_peak" \
  -H "Authorization: Bearer <你的 Token>" \
  --data-urlencode "view=oneSectMaster"

查询宗师榜·英雄的“山海心诀”排名

curl -G "https://api.jx3tnt.com/v1/leaderboards/grandmaster_hero" \
  -H "Authorization: Bearer <你的 Token>" \
  --data-urlencode "keyword=山海心诀" \
  --data-urlencode "limit=100"

查询“笑妆娘”的蓬莱名侠榜

curl -G "https://api.jx3tnt.com/v1/leaderboards/mingxia_regular_dps" \
  -H "Authorization: Bearer <你的 Token>" \
  --data-urlencode "bossId=笑妆娘" \
  --data-urlencode "keyword=蓬莱" \
  --data-urlencode "limit=100"

查询当前赛季死神榜

curl -H "Authorization: Bearer <你的 Token>" \
  "https://api.jx3tnt.com/v1/leaderboards/site_death"

返回结果中的角色名与主站死神榜采用同一稳定脱敏方式；averageDeaths 是角色本赛季场均死亡数，participationCount 是本赛季击败 BOSS 次数。同一场战斗重复上传不会重复计算。

输出心法使用 DPS、防御心法使用 DPS、治疗心法使用 HPS。图片随正式榜单快照预先生成，查询时不会重新统计或现场绘图；图片底部会直接标注快照更新时间。

curl -G "https://api.jx3tnt.com/v1/charts/bosses/<Boss ID>/peaks.png" \
  -H "Authorization: Bearer <你的 Token>" \
  --data-urlencode "dungeonId=<副本 ID>" \
  --output boss-peaks.png

图片上半部分按预发车时间列出今日预报名活动，包括站内团牌、招募信息、副本、报名情况和预发车时间；下半部分从已经公开、审核通过且由用户真实上传的长期招募海报中选取一张宽屏展示。没有合格海报时会显示明确的空态，不会生成替代海报。

图片随正式招募快照预先生成，同一快照内内容固定，调用时不会重复读取数据库或临时抽取海报；图片底部会直接标注快照更新时间。这个接口不需要额外参数，也不包含联系方式、报名成员或团队内部排期。

curl -H "Authorization: Bearer <你的 Token>" \
  "https://api.jx3tnt.com/v1/recruitments/snapshot.png" \
  --output recruitments.png

即将开放

指定团队查询

查询团队评价、赛季历史工资，以及单次最高收益的掉落列表与工资。

团队赛季收益榜前 100

查询团队赛季累计收益前 100 名，并返回榜单快照更新时间。

本站接口对剑三机器人开发者完全免费。日／月额度只用于保障安全与公平使用；有真实提升额度需求时，可以在开发者中心申请更高额度 Token。

{
  "ok": true,
  "billingMode": "free",
  "data": {
    "dailyQuota": 1000,
    "dailyUsed": 36,
    "monthlyQuota": 10000,
    "monthlyUsed": 628
  }
}

理解返回结果

榜单按固定时间更新。更新完成后，接口直接读取已经生成好的榜单数据，不会在每次查询时重新计算，也不会把临时结果作为正式榜单返回。建议在展示每一份榜单时同时显示 snapshotUpdatedAtText，让用户知道数据更新到了什么时间。

常见错误

错误返回示例

{
  "ok": false,
  "error": {
    "code": "OPEN_API_TOKEN_INVALID",
    "message": "API Token 无效。"
  }
}

数据来源与帮助

权威榜单需要更多真实玩家数据才更有价值。如果你的产品方便展示来源，建议在查询结果旁保留下面的说明，引导玩家上传战报并认领角色。这能让榜单样本更完整，也能让开发者持续获得更可靠的数据。

联系我们

JX3天梯榜API交流群：1042441268。仅为交流群，非审核通道。

如果需要程序自动读取全部字段说明，可以查看 机器可读接口文档。