JX3TNT 开放平台开发文档
机器可读文档进入开发者中心

JX3TNT 开发者文档

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

本文档面向剑三机器人和社区工具开发者。所有接口返回 JSON 数据，你可以按照自己的产品形式组织和展示。

完全免费只读查询资料审核后开通每个 Token 独立统计用量

开始前准备

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

01登录账号使用 JX3TNT 主站手机号账号登录。
02提交申请填写应用名称、用途、QQ 和预计调用量。
03等待审核审核通过后会向主站账号已验证手机号发送通知；未通过原因可在开发者个人中心查看。
04创建 Token审核通过后，在开发者中心自行创建。
API 地址https://api.jx3tnt.com
返回格式application/json
使用提醒：Token 只限申请时登记的主体和应用使用。发现转借、共享、泄露、一号多用或违规多号一用等情况，平台会立即暂停相关服务。

身份验证

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

Authorization: Bearer <你的 Token>

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

最简单的调用示例

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

查询角色榜单

按服务器和角色名，查询这个角色已经进入的各类正式榜单。

GET
/v1/characters/rankings?serverName=乾坤一掷&characterName=韭菜

需要填写的参数

参数是否必填说明
serverName必填角色所在服务器，必须填写完整名称，例如“乾坤一掷”。
characterName必填角色名称，必须精确填写，例如“韭菜”。
kungfuId选填只查看指定心法 ID 的结果。
kungfuName选填只查看指定心法名称的结果。

查询“乾坤一掷”的角色“韭菜”

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

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

{
  "ok": true,
  "query": {
    "serverName": "乾坤一掷",
    "characterName": "韭菜",
    "kungfuId": null,
    "kungfuName": null
  },
  "snapshotVersion": "2026-07-22-01",
  "generatedAt": "2026-07-22T03:00:00.000Z",
  "data": [
    {
      "leaderboardKind": "grandmaster_peak",
      "rank": 12,
      "value": 9876.5,
      "dungeonId": null,
      "bossId": null,
      "character": {
        "serverName": "乾坤一掷",
        "characterName": "韭菜",
        "kungfuId": "10242",
        "kungfuName": "冰心诀"
      },
      "reportUrl": "/reports/..."
    }
  ]
}
怎么看 value：宗师榜返回榜单分值；名侠榜根据类型返回 DPS 或 HPS；团队榜返回对应的团队成绩。请结合 leaderboardKind 判断含义。

查询榜单前 100

查询一个榜单的正式排名，可继续按副本、Boss 或心法筛选。

GET
/v1/leaderboards/{leaderboardKind}

可查询的榜单

grandmaster_peak宗师榜·巅峰
grandmaster_hero宗师榜·英雄
mingxia_regular_dps名侠榜·常规 DPS
mingxia_tank_dps名侠榜·坦克 DPS
mingxia_healer_hps名侠榜·治疗 HPS
team_speed_hero团队竞速·英雄
team_top10_top100十甲／百强团队榜

可选筛选参数

参数说明
dungeonId只查看指定副本。
bossId只查看指定 Boss。查询名侠榜时通常与副本一起使用。
kungfuId只查看指定心法 ID。
kungfuName只查看指定心法名称。
limit返回数量，最少 1 条、最多 100 条，默认 100 条。

查询名侠榜治疗 HPS 前 100

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

查询今日招募

返回今天正在招募的公开内容，并按活动开始时间排列。

GET
/v1/recruitments/today

这个接口不需要额外参数，只会返回站内已经公开的信息，不包含账号、联系方式、报名成员或团队内部排期。

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

查询长期招募

返回站内长期有效的公开招募内容。

GET
/v1/recruitments/long-term

返回字段与今日招募一致。团队自己的活动排期不会自动出现在这里，只有发布者明确公开补位后才可能进入公开招募。

查询 Token 用量

查看当前 Token 的今日和本月调用情况。

GET
/v1/usage

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

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

理解返回结果

字段含义
oktrue 表示调用成功，false 表示需要查看错误信息。
data本次查询到的榜单、招募或用量数据。
snapshotVersion本次榜单数据版本，方便确认两次查询是否使用同一批数据。
generatedAt数据生成时间，采用 ISO 8601 时间格式。

榜单按固定时间更新。更新完成后，接口直接读取已经生成好的榜单数据，不会在每次查询时重新计算，也不会把临时结果作为正式榜单返回。

常见错误

400参数填写有误。检查服务器、角色名、榜单类型和筛选条件。
401Token 缺失、无效、过期或已经停用。
403当前 Token 没有开通这个查询权限。
429调用过于频繁或本日／本月额度已经用完。
503服务或榜单数据暂时不可用，请稍后重试。

错误返回示例

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

数据来源与帮助

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

数据来源：JX3TNT.COM 剑网三天梯榜 更多玩家个人数据请到天梯榜官网上传和认领自己的角色https://www.jx3tnt.com/

联系我们

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

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