领取返佣

佣金在链上领取。POST /api/v1/referral/claim 创建一个 claim 订单（对当前所有可领取收益做快照），返回后端 Signer 的 EIP-712 签名，用户随后携带该签名调用 ZtdxRewardRouter 合约的 redeemReward(...) 完成领取。不存在链下即时到账模式。

Claimable = Σ referral_earnings.commission
            WHERE chain_sync_status = 'synced' AND status = 'pending'

只有已批量同步到合约（chain_sync_status = 'synced'）且尚未领取（status = 'pending'）的收益才可领取。仍在等待链上同步的收益计入仪表盘的 pending_commission，但暂不可领取。

创建 Claim

POST /api/v1/referral/claim
Authorization: Bearer <token>
Content-Type: application/json

请求体

空对象 {}。Claim 始终覆盖用户全部可领取余额。

响应

{
  "success": true,
  "claim_no": "CLM-1a2b3c4d5e6f",
  "status": "processing",
  "amount": "45000000",
  "nonce": 0,
  "deadline": 1772097006,
  "signature": "0x9efb5f986acf3dafdd...",
  "contract_address": "0x...",
  "message": "请使用返回的签名调用合约 redeemReward() 方法完成链上领取"
}

字段	类型	说明
`success`	`bool`	Claim 订单是否创建成功
`claim_no`	`string`	Claim 订单号（`CLM-` 前缀）；可通过 `GET /api/v1/referral/claims` 跟踪
`status`	`string`	恒为 `"processing"`——链上 redeem 确认后变为 `"success"`
`amount`	`string`	领取金额，链上 6 位精度的整数字符串（`amount × 10^6`，如 `"45000000"` = 45 USDT）
`nonce`	`uint64`	用户当前链上 reward nonce（每次 redeem 后递增）
`deadline`	`uint64`	签名过期时间（Unix 时间戳，秒；签发后 1 小时）
`signature`	`string`	后端生成的 EIP-712 签名
`contract_address`	`string`	`ZtdxRewardRouter` 合约地址
`message`	`string`	人类可读的操作提示

合约调用

将返回的参数提交到合约：

// redeemReward(uint256 amount, uint256 deadline, bytes signature)
ZtdxRewardRouter(contractAddress).redeemReward(amount, deadline, signature)

签名覆盖的 EIP-712 结构体：

RedeemReward(address account,uint256 value,uint256 nonce,uint256 deadline)

EIP-712 域：name = "ZTDX Reward Router"（可通过 EIP712_REFERRAL_DOMAIN_NAME 配置），version = "1"，chainId = 部署链，verifyingContract = contract_address 返回的 ZtdxRewardRouter 地址。

合约发出 RewardRedeemed 事件后，后端事件监听器（每 30 秒轮询）将覆盖的收益标记为 status = 'claimed'，并将 claim 订单终态更新为 status = 'success' 并记录交易哈希。

错误码

HTTP	错误码	说明
409	`CLAIM_ALREADY_PROCESSING`	上一个 claim 订单仍为 `processing`——请等待链上确认
400	`NO_CLAIMABLE`	无已同步且未领取的佣金
400	`BELOW_MINIMUM`	可领取金额低于最低限额 10 USDT
500	`CLAIM_PERSIST_ERROR`	Claim 订单创建失败
500	`SIGNATURE_ERROR`	Claim 签名生成失败

链上 Claim 签名（自定义金额）

为任意金额生成 EIP-712 签名，不创建 claim 订单。常规流程请优先使用 POST /api/v1/referral/claim——本接口不校验可领取余额。

POST /api/v1/referral/on-chain/claim-signature
Authorization: Bearer <token>
Content-Type: application/json

请求体

{
  "amount": "50.00"
}

字段	类型	必填	说明
`amount`	`string`	是	申请 Claim 的 USDT 金额（必须 > 0）

响应

{
  "amount": "50000000",
  "nonce": 0,
  "deadline": 1772097006,
  "signature": "0x9efb5f986acf3dafdd...",
  "contract_address": "0x..."
}

字段	类型	说明
`amount`	`string`	金额（链上 USDT 精度，6 位，即 `amount × 10^6`）
`nonce`	`uint64`	当前用户 nonce（每次链上领取后递增）
`deadline`	`uint64`	签名有效期（Unix 时间戳，秒）
`signature`	`string`	后端生成的 EIP-712 签名
`contract_address`	`string`	`ZtdxRewardRouter` 合约地址

错误码

HTTP	错误码	说明
400	`INVALID_AMOUNT`	金额格式无效或 ≤ 0
500	`SIGNATURE_ERROR`	Claim 签名生成失败

代码示例

Python — 创建 Claim + Redeem

import requests

BASE_URL = "https://api.prex.world/api/v1"
JWT_TOKEN = "your_jwt_token"

resp = requests.post(
    f"{BASE_URL}/referral/claim",
    headers={"Authorization": f"Bearer {JWT_TOKEN}", "Content-Type": "application/json"},
    json={},
)
data = resp.json()
print(f"Claim {data['claim_no']} [{data['status']}]")
print(f"Amount (6-decimal): {data['amount']}, Nonce: {data['nonce']}, Deadline: {data['deadline']}")
print(f"Signature: {data['signature']}")
print(f"Contract: {data['contract_address']}")
# 下一步：在链上调用 ZtdxRewardRouter.redeemReward(amount, deadline, signature)。
# 后端观察到 RewardRedeemed 事件后，claim 订单转为 'success'。

创建 Claim​

请求体​

响应​

合约调用​

错误码​

链上 Claim 签名（自定义金额）​