返佣记录查询
通过以下接口查询被邀请人列表及返佣提成数据：
- 推荐状态 — 查看所有被推荐用户及绑定状态
- 返佣仪表盘 — 查看佣金汇总和下线人数统计
- 推荐日志 — 分页查询所有推荐操作历史（创建、绑定、解绑、领取）
- 链上返佣信息 — 直接从智能合约查询链上返佣数据
- Traders / Affiliates / Claims — 下方文档的 V2 接口
返佣计算
当被推荐的交易者执行交易时，返佣按以下公式计算：
commission = trade_fee × tier_commission_rate
Maker 和 Taker 的手续费会分别生成独立的返佣记录（如果对应交易者有推荐人）。
收益状态模型
每条 referral_earnings 记录携带两个相互独立的状态列：
status — 领取生命周期
| 状态 | 说明 |
|---|---|
pending | 已计佣，尚未领取 |
claimed | 已在链上赎回——后端观察到合约的 RewardRedeemed 事件后设置（记录 claimed_at） |
chain_sync_status — 链上结算同步
| 状态 | 说明 |
|---|---|
pending | 尚未批量同步到合约 |
synced | 已包含在一笔成功的 batchSettleRewards 交易中（记录 chain_sync_tx） |
failed | 重试 3 次后同步仍失败（记录 chain_sync_error） |
只有当 chain_sync_status = 'synced' 且 status = 'pending' 时，收益才可领取。
Claim 订单（commission_claims）有自己的 status：processing（已创建，等待链上 redeem）→ success（redeem 确认，写入 tx_hash/finished_at）。失败的 claim 携带 failure_reason，可由管理员重试。
最低领取金额
最低领取金额为 10 USDT。低于此金额的领取请求将返回 BELOW_MINIMUM 错误。
批量链上同步
待处理的返佣收益每 5 分钟通过 batchSettleRewards 批量同步至链上 ZtdxRewardRouter 合约。同步后， 收益即可通过 POST /api/v1/referral/claim 领取。
V2 接口
以下所有接口均需 JWT Bearer Token。
交易者列表
列出推荐人直接绑定的交易者（is_affiliate = false），并按交易者聚合交易量与佣金。
GET /api/v1/referral/traders
Authorization: Bearer <token>
Query 参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
biz | string | all | 业务线过滤：all / spot / futures |
time | string | all | 聚合时间窗口：all / 7d / 30d |
q | string | — | 按交易者地址子串过滤（可选） |
page | int | 1 | 页码（最小 1） |
page_size | int | 20 | 每页条数（1–100） |
响应
{
"items": [
{
"address": "0xabc...",
"bound_at": "2026-03-01T10:00:00Z",
"spot_volume": "120.00",
"futures_volume": "380.00",
"spot_commission": "12.00",
"futures_commission": "38.00",
"total_commission": "50.00",
"last_trade_at": "2026-04-15T09:00:00Z",
"status": "active"
}
],
"total": 8,
"page": 1,
"page_size": 20
}
| 字段 | 类型 | 说明 |
|---|---|---|
items[].address | string | 交易者钱包地址 |
items[].bound_at | string | 交易者绑定推荐人的时间（ISO 8601） |
items[].spot_volume / futures_volume | string | 从推荐人收益记录中归集到该交易者的手续费价值聚合，按业务线拆分 |
items[].spot_commission / futures_commission | string | 从该交易者赚取的已同步佣金，按业务线拆分 |
items[].total_commission | string | spot_commission + futures_commission |
items[].last_trade_at | string | null | 最近一笔产生收益的交易 |
items[].status | string | 最近交易在 7 天内为 active，否则为 inactive |
total | int64 | 直属交易者总数（不受过滤条件影响） |
Affiliate 列表
列出推荐人的下线 affiliate（is_affiliate = true），并聚合团队与分成佣金。
GET /api/v1/referral/affiliates
Authorization: Bearer <token>
Query 参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
page | int | 1 | 页码（最小 1） |
page_size | int | 20 | 每页条数（1–100） |
响应
{
"items": [
{
"address": "0xdef...",
"sub_rate": "0.05",
"spread_rate": "0.05",
"direct_traders_count": 3,
"team_volume": "500.00",
"spot_spread_commission": "5.00",
"futures_spread_commission": "20.00",
"total_spread_commission": "25.00",
"status": "active"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
| 字段 | 类型 | 说明 |
|---|---|---|
items[].sub_rate | string | 下发给 affiliate 的费率 |
items[].spread_rate | string | 你对该 affiliate 团队的分成差率：my_rebate_rate − sub_rate（下限为 0） |
items[].direct_traders_count | int64 | 该 affiliate 自己的直属交易者人数 |
items[].team_volume | string | 来自该 affiliate 团队的手续费价值聚合（spread 类收益） |
items[].spot_spread_commission / futures_spread_commission | string | 按业务线拆分的已同步分成佣金 |
items[].total_spread_commission | string | 两项分成佣金之和 |
items[].status | string | 当前恒为 "active" |
将交易者提升为 Affiliate
POST /api/v1/referral/affiliates
Authorization: Bearer <token>
Content-Type: application/json
{ "wallet": "0xdef...", "sub_rate": "0.05" }
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
wallet | string | 是 | 你的某位直属交易者的地址 |
sub_rate | Decimal | 是 | 下发给 affiliate 的费率；须满足 0 ≤ sub_rate ≤ 你的返佣费率 |
响应：{ "ok": true }
| HTTP | 错误码 | 说明 |
|---|---|---|
| 400 | SELF_ASSIGNMENT | 不能提升自己 |
| 400 | SUB_RATE_EXCEEDS_OWN | sub_rate 为负或超过自己的返佣费率 |
| 400 | USER_NOT_FOUND | 目标钱包不是注册用户 |
| 400 | TARGET_NOT_AGENT | 目标须先是有效的一级代理 |
| 400 | TARGET_NOT_DIRECT_TRADER | 目标钱包不是你的直属交易者 |
| 400 | ALREADY_AFFILIATE | 目标已是 affiliate |
更新 Affiliate 分成比例
PUT /api/v1/referral/affiliates/:wallet
Authorization: Bearer <token>
Content-Type: application/json
{ "sub_rate": "0.06" }
响应：{ "ok": true }
| HTTP | 错误码 | 说明 |
|---|---|---|
| 400 | SUB_RATE_EXCEEDS_OWN | sub_rate 为负或超过自己的返佣费率 |
| 404 | AFFILIATE_NOT_FOUND | 与该钱包不存在 affiliate 关系 |
Claim 预览
GET /api/v1/referral/claims/preview
Authorization: Bearer <token>
{
"claimable": "45.00",
"pending": "12.50",
"last_claimed_at": "2026-04-10T08:15:00Z",
"claim_wallet": "0xabc..."
}
| 字段 | 类型 | 说明 |
|---|---|---|
claimable | string | 当前可领取的佣金（chain_sync_status='synced' AND status='pending'） |
pending | string | 等待链上同步的佣金（chain_sync_status='pending'） |
last_claimed_at | string | null | 最近一次成功领取的完成时间 |
claim_wallet | string | 领取到账钱包（即已认证地址） |
我的 Claim 列表
GET /api/v1/referral/claims
Authorization: Bearer <token>
Query 参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
page | int | 1 | 页码（最小 1） |
page_size | int | 20 | 每页条数（1–100） |
响应
{
"items": [
{
"claim_no": "CLM-1a2b3c4d5e6f",
"amount": "45.00",
"status": "success",
"tx_hash": "0x...",
"failure_reason": null,
"applied_at": "2026-04-10T08:00:00Z",
"finished_at": "2026-04-10T08:15:00Z"
}
],
"total": 1,
"page": 1,
"page_size": 20
}
| 字段 | 类型 | 说明 |
|---|---|---|
items[].claim_no | string | Claim 订单号 |
items[].amount | string | 领取金额（USDT，十进制字符串） |
items[].status | string | processing / success |
items[].tx_hash | string | null | 链上 redeem 交易哈希 |
items[].failure_reason | string | null | 失败原因（如有） |
items[].applied_at | string | Claim 订单创建时间 |
items[].finished_at | string | null | 链上 redeem 确认时间 |