返佣仪表盘

返回推荐人的综合收益数据，包含等级信息和最近活动记录。

GET /referral/dashboard
Authorization: Bearer <token>

响应

{
  "code": "4DDDC2D4",
  "total_referrals": 8,
  "active_referrals": 3,
  "total_referred_volume": "52000.00",
  "total_earnings": "125.50",
  "pending_earnings": "45.00",
  "claimed_earnings": "80.50",
  "tier": {
    "level": 1,
    "name": "Bronze",
    "commission_rate": "0.12",
    "rate_bps": 1200,
    "next_tier_referrals": 20,
    "next_tier_volume": "100000.00"
  },
  "recent_activity": [
    {
      "referral_address": "0xabc...",
      "event_type": "trade",
      "volume": "10000.00",
      "commission": "1.50",
      "timestamp": 1771900000000
    }
  ],
  "bound_referral": null
}

未达 Starter 门槛时，tier 为 null：

{
  "code": "4DDDC2D4",
  "total_referrals": 0,
  "active_referrals": 0,
  "total_referred_volume": "0.00",
  "total_earnings": "0.00",
  "pending_earnings": "0.00",
  "claimed_earnings": "0.00",
  "tier": null,
  "tier_note": "未达到最低返佣门槛，需满足：≥1 位被推荐人 且 被推荐人累计交易量 ≥ $1,000",
  "recent_activity": [],
  "bound_referral": null
}

响应字段

字段	类型	说明
code	string | null	用户的推荐码
total_referrals	int64	累计推荐人数
active_referrals	int64	活跃被推荐人数（近期有交易）
total_referred_volume	Decimal	所有被推荐人的累计交易量（USD）
total_earnings	Decimal	累计总收益（USDT）
pending_earnings	Decimal	待领取收益（USDT）
claimed_earnings	Decimal	已领取收益（USDT）
tier	object | null	等级信息；未达 Starter 门槛时为 null
tier_note	string	仅当 tier 为 null 时出现，说明未满足的门槛条件

tier

未达 Starter 门槛时整个对象为 null。

字段	类型	说明
level	int	等级编号（0–4）
name	string	等级名称（Starter/Bronze/Silver/Gold/Diamond）
commission_rate	string	返佣比例（小数格式，如 "0.12" = 12%）
rate_bps	int	返佣比例（基点，1 bps = 0.01%）
next_tier_referrals	int | null	升级所需邀请人数；Diamond 时为 null
next_tier_volume	string | null	升级所需被推荐人累计交易量（USD）；Diamond 时为 null

recent_activity[]

字段	类型	说明
referral_address	string	被推荐人钱包地址
event_type	string	事件类型（如 "trade"）
volume	Decimal	交易量（USD）
commission	Decimal	获得的返佣（USDT）
timestamp	int64	事件时间（毫秒时间戳）

bound_referral

字段	类型	说明
code	string	绑定的推荐码
referrer_address	string	推荐人钱包地址
bound_at	int64	绑定时间（毫秒时间戳）

如果用户未绑定推荐人，bound_referral 为 null。

等级说明

等级	名称	返佣比例	BPS	邀请人数（AND）	被推荐人累计交易量（AND）
0	Starter	10%	1000	≥ 1	≥ $1,000
1	Bronze	12%	1200	≥ 5	≥ $10,000
2	Silver	17%	1700	≥ 20	≥ $100,000
3	Gold	22%	2200	≥ 50	≥ $500,000
4	Diamond	25%	2500	≥ 100	≥ $2,000,000

升级条件为 AND 关系，两个条件必须同时满足。未达 Starter 门槛的用户响应中 tier 为 null。

等级由后端根据被推荐人的实时交易情况自动重算更新。

代码示例

Python

import requests

BASE_URL = "https://api.ztdx.io"
JWT_TOKEN = "your_jwt_token"

resp = requests.get(
    f"{BASE_URL}/referral/dashboard",
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
)
data = resp.json()

print(f"Code: {data['code']}")
print(f"Total referrals: {data['total_referrals']}, Active: {data['active_referrals']}")
print(f"Earnings — Total: {data['total_earnings']}, Pending: {data['pending_earnings']}, Claimed: {data['claimed_earnings']}")
if data['tier']:
    print(f"Tier: {data['tier']['name']} (Level {data['tier']['level']}), Commission: {data['tier']['commission_rate']}")
else:
    print(f"暂无等级 — {data.get('tier_note', '')}")

for act in data["recent_activity"]:
    print(f"  {act['event_type']}: vol={act['volume']} commission={act['commission']}")