积分 API (Points API)

Version: v1.1 Last Updated: 2026-01-20 Status: Production Ready ✅

概述

积分 API 用于查询用户在不同 Epoch 的积分详情、查看排行榜以及拉取 Epoch 列表。

快速参考

接口	方法	认证	描述
`/api/v1/points`	GET	✅ 需要	获取用户积分详情
`/api/v1/leaderboard`	GET	❌ 公开	获取排行榜
`/api/v1/epochs`	GET	❌ 公开	获取 Epoch 列表

认证

需要 JWT 认证的接口，在请求头中包含 token：

Authorization: Bearer <jwt_token>

接口详情

1. 获取用户积分

GET /api/v1/points

获取用户在当前期或指定期的积分汇总。

请求参数：

参数	类型	必填	默认值	描述
`epoch`	integer	否	当前活跃期	指定 Epoch ID

响应示例：

{
  "success": true,
  "data": {
    "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
    "epoch_number": 1,
    "epoch_status": "active",

    "trading_points": "1250.50",
    "pnl_points": "800.00",
    "holding_points": "350.25",
    "referral_points": "200.00",
    "staking_points": "100.00",
    "total_points": "2700.75",

    "tier": "T2",
    "tier_multiplier": "1.10",

    "trading_volume": "125050.00",
    "trade_count": 45,

    "referral_code": "AXUSER123",
    "referral_count": 3,

    "rank": 15,
    "updated_at": "2026-01-20T10:30:00.000Z"
  },
  "error": null,
  "timestamp": 1768890275
}

响应字段说明：

字段	类型	描述
`user_address`	string	用户钱包地址 (小写)
`epoch_number`	integer	当前 Epoch 编号
`epoch_status`	string	Epoch 状态: `active`, `pending`, `ended`, `settled`
`trading_points`	string	交易积分
`pnl_points`	string	盈亏积分
`holding_points`	string	持仓积分
`referral_points`	string	推荐积分
`staking_points`	string	质押积分
`total_points`	string	总积分 (5种之和)
`tier`	string\|null	当前等级 (T1-T4)，无交易时为 null
`tier_multiplier`	string	当前等级倍数
`trading_volume`	string	本 Epoch 累计交易量
`trade_count`	integer	本 Epoch 交易次数
`referral_code`	string\|null	用户推荐码
`referral_count`	integer	成功推荐人数
`rank`	integer	当前排名
`updated_at`	string	最后更新时间 (ISO 8601)

2. 获取排行榜

GET /api/v1/leaderboard

获取指定 Epoch 的积分排行榜。

请求参数：

参数	类型	必填	默认值	描述
`epoch`	integer	否	当前活跃期	指定 Epoch ID
`type`	string	否	`total`	排行榜类型
`limit`	integer	否	100	返回条数 (1-500)

排行榜类型 (type)：

值	描述
`total`	总积分排行 (默认)
`trading`	交易积分排行
`pnl`	盈亏积分排行
`holding`	持仓积分排行
`referral`	推荐积分排行
`staking`	质押积分排行

响应示例：

{
  "success": true,
  "data": {
    "epoch_number": 1,
    "rank_type": "total",
    "entries": [
      {
        "rank": 1,
        "user_address": "0x93ee356f71177f5d924765c5d6ab31d3eaa63b89",
        "username": null,
        "points": "207.21",
        "tier": "T4"
      },
      {
        "rank": 2,
        "user_address": "0x0a20b798fccea18dec56a4d71180cb622b98efcc",
        "username": "trader_001",
        "points": "187.50",
        "tier": "T1"
      },
      {
        "rank": 3,
        "user_address": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
        "username": null,
        "points": "113.00",
        "tier": "T1"
      }
    ]
  },
  "error": null,
  "timestamp": 1768890300
}

响应字段说明：

字段	类型	描述
`epoch_number`	integer	Epoch 编号
`rank_type`	string	排行榜类型
`entries`	array	排行榜条目列表
`entries[].rank`	integer	排名 (从1开始)
`entries[].user_address`	string	用户钱包地址
`entries[].username`	string\|null	用户显示名 (如已设置)
`entries[].points`	string	该类型积分
`entries[].tier`	string	用户等级

3. 获取 Epoch 列表

GET /api/v1/epochs

获取平台所有已定义的 Epoch 列表及其状态。无需认证。

响应示例：

{
  "success": true,
  "data": [
    {
      "id": 1,
      "label": "Epoch 1: 2026.1.14 - 2026.2.13",
      "startDate": "2026-01-14",
      "endDate": "2026-02-13",
      "status": "active"
    },
    {
      "id": 2,
      "label": "Epoch 2: 2026.2.14 - 2026.3.15",
      "startDate": "2026-02-14",
      "endDate": "2026-03-15",
      "status": "pending"
    },
    {
      "id": 3,
      "label": "Epoch 3: 2026.3.16 - 2026.4.14",
      "startDate": "2026-03-16",
      "endDate": "2026-04-14",
      "status": "pending"
    }
  ],
  "error": null,
  "timestamp": 1768890350
}

响应字段说明：

字段	类型	描述
`id`	integer	Epoch 编号
`label`	string	人类可读的 Epoch 标签
`startDate`	string	开始日期 (YYYY-MM-DD)
`endDate`	string	结束日期 (YYYY-MM-DD)
`status`	string	状态: `pending`, `active`, `ended`, `settled`

Epoch 状态流转：

pending → active → ended → settled

积分计算规则

五种积分类型

类型	计算公式	触发时机
交易积分	`交易量 × 0.0001 × Tier倍数`	交易完成时
盈亏积分	`max(已实现盈利, 0) × 0.001 × Tier倍数`	平仓时
持仓积分	`仓位价值 × 0.00001 × 小时数 × Tier倍数`	每小时计算
推荐积分	`被推荐人交易量 × 0.00005`	被推荐人交易时
质押积分	`质押金额 × 0.0002 × 天数`	每日计算

Tier 等级配置

等级	交易量范围 (USDT)	积分倍数
T1	$0 - $99,999.99	1.0x
T2	$100,000 - $499,999.99	1.1x
T3	$500,000 - $999,999.99	1.3x
T4	$1,000,000+	1.5x

计算示例

用户 A: T2 等级 (交易量 $150,000)
本次交易量: $10,000

交易积分 = $10,000 × 0.0001 × 1.1 = 1.1 积分

错误码

所有错误响应格式：

{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述"
  },
  "timestamp": 1768890400
}

错误码	HTTP 状态码	描述
`UNAUTHORIZED`	401	未提供认证信息或 Token 过期
`EPOCH_NOT_FOUND`	404	指定的 Epoch ID 不存在
`INVALID_PARAMETER`	400	无效的请求参数
`RATE_LIMITED`	429	请求频率过快
`INTERNAL_ERROR`	500	服务器内部错误

前端集成示例

获取用户积分

async function getUserPoints(token, epoch = null) {
  const url = epoch
    ? `/api/v1/points?epoch=${epoch}`
    : '/api/v1/points';

  const response = await fetch(url, {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  const { success, data, error } = await response.json();

  if (!success) {
    throw new Error(error.message);
  }

  return {
    total: parseFloat(data.total_points),
    trading: parseFloat(data.trading_points),
    pnl: parseFloat(data.pnl_points),
    holding: parseFloat(data.holding_points),
    referral: parseFloat(data.referral_points),
    staking: parseFloat(data.staking_points),
    tier: data.tier || 'T1',
    tierMultiplier: parseFloat(data.tier_multiplier),
    rank: data.rank
  };
}

获取排行榜

async function getLeaderboard(type = 'total', limit = 50) {
  const response = await fetch(
    `/api/v1/leaderboard?type=${type}&limit=${limit}`
  );

  const { success, data } = await response.json();

  return data.entries.map(entry => ({
    rank: entry.rank,
    address: entry.user_address,
    displayName: entry.username || shortenAddress(entry.user_address),
    points: parseFloat(entry.points),
    tier: entry.tier
  }));
}

function shortenAddress(addr) {
  return `${addr.slice(0, 6)}...${addr.slice(-4)}`;
}

测试

测试环境

环境	API 地址
测试网	`https://api.8a27.xyz`
生产环境	`https://api.axblade.io`

运行测试脚本

cd backend/tests
python3 test_points_phase1.py

测试覆盖 (16个测试)：

API 可用性和响应结构
Epoch 系统功能
排行榜查询和排名
Tier 等级验证
5种积分类型计算
总积分汇总

更新日志

版本	日期	变更
v1.1	2026-01-20	更新 API 响应格式，添加前端示例，修正字段类型
v1.0	2026-01-13	初始版本

概述​

快速参考​

认证​

接口详情​

1. 获取用户积分​

2. 获取排行榜​

3. 获取 Epoch 列表​

积分计算规则​

五种积分类型​

Tier 等级配置​

计算示例​

错误码​

前端集成示例​

获取用户积分​

获取排行榜​

测试​

测试环境​

运行测试脚本​

更新日志​

概述

快速参考

认证

接口详情

1. 获取用户积分

2. 获取排行榜

3. 获取 Epoch 列表

积分计算规则

五种积分类型

Tier 等级配置

计算示例

错误码

前端集成示例

获取用户积分

获取排行榜

测试

测试环境

运行测试脚本

更新日志