返佣系统概述
ZTDX 返佣系统允许用户通过邀请交易者加入平台来赚取佣金。推荐人创建唯一的邀请码，分享给交易者，并从被推荐人产生的交易手续费中赚取一定比例的返佣。
Base URL: https://api.ztdx.io/api/v1
工作原理
推荐人（Referrer）
├── 创建推荐码（POST /referral/codes）
└── 将推荐码分享给交易者
交易者（Referee）
├── 绑定推荐码（POST /referral/bind）
└── 每次交易产生手续费 → 推荐人获得返佣
返佣流程
交易者执行交易
→ 后端计算返佣（trade_fee × tier_rate）
→ 写入 referral_earnings（chain_sync_status = 'pending'）
→ 每 5 分钟批量同步至链上合约（batchSettleRewards）
→ chain_sync_status = 'synced'
推荐人链上领取：
POST /referral/claim
→ 对所有已同步、未领取的收益创建 claim 订单
→ 返回 EIP-712 签名
推荐人在合约上调用 redeemReward(amount, deadline, signature)
→ 后端监听到 RewardRedeemed → 收益标记为 'claimed'，claim 订单标记为 'success'
等级体系
返佣比例由推荐人等级决定，等级基于其被推荐人的累计交易量：
| 等级 | 名称 | 返佣比例 | BPS | 邀请人数（AND） | 被 推荐人累计交易量（AND） |
|---|---|---|---|---|---|
| 0 | Starter | 10% | 1000 | —（默认保底） | —（默认保底） |
| 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 |
所有用户至少为 Starter（10%），无任何门槛——Starter 是从第一天起就生效的保底等级。升到更高等级需要同时满足邀请人数与被推荐人交易量两个条件。 费率在每次请求/计佣时根据推荐人当前的邀请人数与被推荐人交易量实时重算。
智能合约
链上结算由单个 RewardRouter 风格的合约 ZtdxRewardRouter 处理（通过 REFERRAL_REBATE_ADDRESS 配置）：
| 方法 | 功能 |
|---|---|
rewardAccountInfo(address) | 用户返佣账户：已赎回金额、nonce、推荐码、affiliate、等级 |
affiliateRewardInfo(address) | 交易者推荐配置：推荐码、affiliate、total/discount/reward BPS |
redeemedRewards(address) | 累计已赎回返佣金额 |
redeemReward(amount, deadline, signature) | 用户侧领取，携带后端 EIP-712 签名 |
batchSettleRewards(users, amounts, batchId) | 后端批量同步累计佣金（每 5 分钟） |
配套的 AffiliateRegistry 存储合约（REFERRAL_STORAGE_ADDRESS）保存推荐码映射与等级设置。
ZtdxRewardRouter 地址可通过 GET /referral/on-chain/operator-status（contract_address 字段）获取。
认证方式
所有受保护接口需要 JWT Bearer Token：
Authorization: Bearer <token>
Token 通过 EIP-712 登录流程获取，详见认证文档。
API 接口列表
公开接口（无需认证）
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /referral/leaderboard | 返佣排行榜（前 N 名） |
| GET | /referral/on-chain/user-rebate/:address | 查询用户链上返佣信息 |
| GET | /referral/on-chain/referral-info/:address | 查询交易者链上推荐配置 |
| GET | /referral/on-chain/claimed/:address | 查询链上已领取金额 |
| GET | /referral/on-chain/operator-status | 查询后端 Signer 运营状态 |
受保护接口（需 JWT）
| 方法 | 接口 | 说明 |
|---|---|---|
| POST | /referral/codes | 创建推荐码 |
| POST | /referral/bind | 绑定推荐码 |
| POST | /referral/unbind | 解绑推荐码 |
| GET | /referral/status | 查询推荐状态（推荐人和被推荐人双向） |
| GET | /referral/dashboard | 获取推荐中心仪表盘（V2） |
| GET | /referral/logs | 查询操作日志 |
| POST | /referral/claim | 创建佣金 claim + 获取链上 redeem 签名 |
| POST | /referral/on-chain/claim-signature | 生成链上 Claim 签名（自定义金额） |
| GET | /referral/traders | 列出直接绑定的交易者及其交易量/佣金聚合 |
| GET | /referral/affiliates | 列出下级 affiliate 及其分成佣金聚合 |
| POST | /referral/affiliates | 将直属交易者提升为 affiliate 并设置分成比例 |
| PUT | /referral/affiliates/:wallet | 更新 affiliate 的分成比例 |
| GET | /referral/claims/preview | 预览可领取 / 待同步佣金 |
| GET | /referral/claims | 列出我的佣金 claim 订单 |
traders、affiliates、claims 等接口的详细请求/响应文档见返佣记录。
EIP-712 签名类型
| 操作 | TypeHash |
|---|---|
| 创建推荐码 | CreateReferralCode(address wallet,uint256 timestamp) |
| 绑定推荐码 | BindReferralCode(address wallet,string code,uint256 timestamp) |
| 解绑推荐码 | CreateReferralCode(address wallet,uint256 timestamp) —— 解绑复用创建推荐码的结构体；不存在单独的 UnbindReferralCode 类型 |
EIP-712 Domain 可从 GET /auth/nonce/:address → typed_data.domain 获取。