推荐与返佣 (Referral & Rebates)
ZTDX 提供多层级的推荐激励计划，用户可以通过邀请新用户交易来获得返佣收益。
推荐码管理
创建推荐码
接口信息
- Method:
POST - Path:
/api/v1/referral/codes - Authentication: 需要身份验证
- Content-Type:
application/json
请求参数
| 参数 | 类型 | 必须 | 描述 |
|---|---|---|---|
| signature | string | 是 | 签名 |
| timestamp | number | 是 | Unix 时间戳（秒） |
签名消息格式
Create Referral Code on ZTDX
Timestamp: {timestamp}
Address: {address}
请求示例
{
"signature": "0x...",
"timestamp": 1704067200
}
响应示例
{
"success": true,
"code": "ZTDX1234",
"created_at": "2024-01-01T00:00:00Z"
}
响应字段说明
| 字段 | 类型 | 描述 |
|---|---|---|
| success | boolean | 是否成功 |
| code | string | 生成的推荐码（8位大写） |
| created_at | string | 创建时间 |
错误响应
| HTTP 状态码 | 错误码 | 描述 |
|---|---|---|
| 409 | CODE_ALREADY_EXISTS | 用户已有推荐码 |
| 401 | SIGNATURE_INVALID | 签名验证失败 |
绑定推荐码
新用户可以在注册或首次交易前绑定邀请码。
接口信息
- Method:
POST - Path:
/api/v1/referral/bind - Authentication: 需要身份验证
- Content-Type:
application/json
请求参数
| 参数 | 类型 | 必须 | 描述 |
|---|---|---|---|
| code | string | 是 | 推荐码 |
| signature | string | 是 | 签名 |
| timestamp | number | 是 | Unix 时间戳（秒） |
签名消息格式
Bind Referral Code on ZTDX
Code: {code}
Timestamp: {timestamp}
Address: {address}
请求示例
{
"code": "ZTDX1234",
"signature": "0x...",
"timestamp": 1704067200
}
响应示例
{
"success": true,
"referrer_address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
"referrer_code": "ZTDX1234"
}
错误响应
| HTTP 状态码 | 错误码 | 描述 |
|---|---|---|
| 404 | CODE_NOT_FOUND | 推荐码不存在 |
| 409 | ALREADY_BOUND | 已绑定推荐人 |
| 400 | SELF_REFERRAL | 不能使用自己的推荐码 |
推荐面板
获取实时的获客统计和收益数据。
接口信息
- Method:
GET - Path:
/api/v1/referral/dashboard - Authentication: 需要身份验证
响应示例
{
"code": "ZTDX1234",
"total_referrals": 50,
"active_referrals": 30,
"total_earnings": "1500.50",
"pending_earnings": "250.00",
"claimed_earnings": "1250.50",
"tier": {
"level": 2,
"name": "Gold",
"commission_rate": "0.15",
"next_tier_requirement": 50
},
"recent_activity": [
{
"referral_address": "0x123...",
"event_type": "trade",
"volume": "10000.00",
"commission": "15.00",
"timestamp": "2024-01-01T00:00:00Z"
}
]
}
响应字段说明
| 字段 | 类型 | 描述 |
|---|---|---|
| code | string | null | 用户的推荐码 |
| total_referrals | number | 成功邀请的总用户数 |
| active_referrals | number | 活跃用户数（30天内有交易） |
| total_earnings | string | 累计总收益 |
| pending_earnings | string | 待领取收益 |
| claimed_earnings | string | 已领取收益 |
| tier | object | 当前等级信息 |
| recent_activity | array | 最近活动记录 |
等级体系
| 等级 | 名称 | 邀请人数要求 | 返佣比例 |
|---|---|---|---|
| 1 | Silver | 0-9 | 10% |
| 2 | Gold | 10-49 | 15% |
| 3 | Platinum | 50-99 | 20% |
| 4 | Diamond | 100+ | 25% |
领取奖励
将已结算的返佣提取至账户余额。
接口信息
- Method:
POST - Path:
/api/v1/referral/claim - Authentication: 需要身份验证
响应示例
{
"success": true,
"amount": "250.00",
"tx_hash": null
}
响应字段说明
| 字段 | 类型 | 描述 |
|---|---|---|
| success | boolean | 是否成功 |
| amount | string | 领取金额 |
| tx_hash | string | null | 交易哈希（链下领取为 null） |
错误响应
| HTTP 状态码 | 错误码 | 描述 |
|---|---|---|
| 400 | NO_PENDING_EARNINGS | 没有待领取的佣金 |
| 400 | BELOW_MINIMUM | 低于最低领取金额（10 USDT） |
链上面板（公开接口）
ZTDX 的透明性通过链上数据面板体现。这些接口无需身份验证。
获取链上统计
接口信息
- Method:
GET - Path:
/api/v1/referral/on-chain/dashboard/:address - Authentication: 不需要
路径参数
| 参数 | 类型 | 必须 | 描述 |
|---|---|---|---|
| address | string | 是 | Ethereum 地址 |
响应示例
{
"code": "ZTDX1234",
"total_referees": 50,
"total_volume_usd": "1000000.00",
"total_earnings_usd": "15000.00",
"claimed_earnings_usd": "12000.00",
"claimable_earnings_usd": "3000.00",
"current_tier": 2,
"current_rate_bps": 1500,
"tier_name": "Gold"
}
响应字段说明
| 字段 | 类型 | 描述 |
|---|---|---|
| code | string | 推荐码 |
| total_referees | number | 总邀请人数 |
| total_volume_usd | string | 总交易量（USD） |
| total_earnings_usd | string | 总收益（USD） |
| claimed_earnings_usd | string | 已领取收益 |
| claimable_earnings_usd | string | 可领取收益 |
| current_tier | number | 当前等级（0-4） |
| current_rate_bps | number | 当前返佣比例（基点，1500 = 15%） |
| tier_name | string | 等级名称 |
查询可领取金额
接口信息
- Method:
GET - Path:
/api/v1/referral/on-chain/claimable/:address - Authentication: 不需要
路径参数
| 参数 | 类型 | 必须 | 描述 |
|---|---|---|---|
| address | string | 是 | Ethereum 地址 |
响应示例
{
"address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
"claimable_usd": "3000.00"
}
操作员状态
接口信息
- Method:
GET - Path:
/api/v1/referral/on-chain/operator-status - Authentication: 不需要
响应示例
{
"operator_address": "0x1234567890abcdef...",
"is_operator": true,
"contract_address": "0xabcdef1234567890..."
}
说明
- 推荐码由系统自动生成，8位大写字母和数字组合
- 每个用户只能创建一个推荐码
- 每个用户只能绑定一次推荐人
- 返佣比例根据邀请人数自动升级
- 最低领取金额为 10 USDT
- 链上数据公开透明，任何人都可以查询