Coinfair 技术文档

Appearance

排行榜接口文档 ​

本文档包含积分排行榜和 NFT 领取排行榜两个接口。

1. 积分排行榜接口 ​

接口信息 ​

  • 接口路径: /api/earn/leaderboard
  • 请求方法: GET
  • 接口描述: 获取积分排行榜列表，支持分页查询

请求参数 ​

Query 参数 ​

参数名类型必填说明
pageIndexnumber否页码，从 1 开始，默认为 1
pageSizenumber否每页数量，默认值根据接口实现而定
walletAddressstring否钱包地址，用于查询指定用户的排名

请求示例 ​

bash
GET /api/earn/leaderboard?pageIndex=1&pageSize=20

响应数据结构 ​

json
{
  "code": 200,
  "message": "OK",
  "result": {
    "data": [
      {
        "rank": 1,
        "score": 480,
        "user": "CpwzP+CKKmTAb68Dd6hbLtuFVhB3seymQ4P52N9VaNei",
        "walletAddress": "0x35487e65c8aef497fa8f29cbe9cb097c88753eb8172c0f640285921169730d38"
      }
    ],
    "nextPageIndex": 2,
    "total": 1000
  }
}

响应字段说明 ​

result 对象字段 ​

字段名类型必填说明
dataarray是排行榜列表数据
nextPageIndexnumber否下一页页码，无下一页为空
totalnumber是总记录数

data 数组项字段 ​

字段名类型必填说明
ranknumber是排名，从 1 开始
scorenumber是积分
userstring是用户地址（Base64 编码或省略格式）
walletAddressstring是钱包地址（完整格式）

2. NFT 领取排行榜接口 ​

接口信息 ​

  • 接口路径: /api/earn/nft-claim-leaderboard
  • 请求方法: GET
  • 接口描述: 获取 NFT 领取排行榜列表，按领取数量排序，支持分页查询

请求参数 ​

Query 参数 ​

参数名类型必填说明
pageIndexnumber否页码，从 1 开始，默认为 1
pageSizenumber否每页数量，默认值根据接口实现而定

请求示例 ​

bash
GET /api/earn/nft-claim-leaderboard?pageIndex=1&pageSize=20

响应数据结构 ​

json
{
  "code": 200,
  "message": "OK",
  "result": {
    "data": [
      {
        "rank": 1,
        "referrer": "0x1234...5678",
        "walletAddress": "0x35487e65c8aef497fa8f29cbe9cb097c88753eb8172c0f640285921169730d38",
        "count": 5
      }
    ],
    "nextPageIndex": 2,
    "total": 500
  }
}

响应字段说明 ​

result 对象字段 ​

字段名类型必填说明
dataarray是NFT 领取排行榜列表数据
nextPageIndexnumber否下一页页码，无下一页为空
totalnumber是总记录数

data 数组项字段 ​

字段名类型必填说明
ranknumber是排名，从 1 开始，按领取数量降序排列
referrerstring是推荐人地址（省略格式）
walletAddressstring是钱包地址（完整格式）
countnumber是NFT 领取数量

响应示例 ​

积分排行榜响应示例 ​

json
{
  "code": 200,
  "message": "OK",
  "result": {
    "data": [
      {
        "rank": 1,
        "score": 480,
        "user": "CpwzP+CKKmTAb68Dd6hbLtuFVhB3seymQ4P52N9VaNei",
        "walletAddress": "0x35487e65c8aef497fa8f29cbe9cb097c88753eb8172c0f640285921169730d38"
      },
      {
        "rank": 2,
        "score": 330,
        "user": "D4b2dyVAeuDluGrLBqTQ1dhkzvdcb2FGGkjCn5jJaVuF",
        "walletAddress": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
      }
    ],
    "nextPageIndex": 2,
    "total": 1000
  }
}

NFT 领取排行榜响应示例 ​

json
{
  "code": 200,
  "message": "OK",
  "result": {
    "data": [
      {
        "rank": 1,
        "referrer": "0x1234...5678",
        "walletAddress": "0x35487e65c8aef497fa8f29cbe9cb097c88753eb8172c0f640285921169730d38",
        "count": 5
      },
      {
        "rank": 2,
        "referrer": "0xabcd...efgh",
        "walletAddress": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "count": 3
      }
    ],
    "nextPageIndex": 2,
    "total": 500
  }
}

注意事项 ​

  1. 所有接口的分页参数 pageIndex 从 1 开始计数
  2. pageSize 为可选参数，默认值根据接口实现而定
  3. 当 nextPageIndex 不存在或为空时，表示没有下一页数据
  4. total 字段表示符合条件的总记录数，可用于计算总页数
  5. 排行榜接口的数据按分数或数量降序排列
  6. user 字段可能为 Base64 编码或省略格式，walletAddress 为完整地址
  7. referrer 字段为省略格式（如 "0x1234...5678"），前端可直接使用
  8. 响应格式遵循 API 标准：code 为 200 表示成功，message 为状态消息
  9. 可选字段可能为 null 或不存在，前端需要做兼容处理