领取赛季代币

生成 EIP-712 签名载荷，用户持此签名到链上合约领取赛季代币奖励。

接口具有幂等性，同一 (user, distribution, nonce) 重复调用返回相同签名。

POST /points/claim/:distribution_id
Authorization: Bearer <token>

Path 参数

参数	类型	说明
distribution_id	UUID	分配记录 ID（从 GET /points/distribution/:season_id 返回数组中的 id 字段获取）

请求体

无。

响应

{
  "success": true,
  "data": {
    "user": "0xabcd...1234",
    "distribution_id": "f1e2d3c4-...",
    "amount": "805.00",
    "nonce": 1,
    "deadline": 1741132800,
    "signature": "0x4a5b6c...f0a1b2",
    "domain": {
      "name": "ZTDX Points Distribution",
      "version": "1",
      "chain_id": 1,
      "verifying_contract": "0xContractAddress..."
    }
  },
  "error": null,
  "timestamp": 1745280000
}

data 载荷为平铺结构（无嵌套 eip712_payload）。amount 为人类可读金额（非 wei），链上合约自动转换为 18 位精度。deadline 为 Unix 时间戳（秒）。EIP-712 域名称默认为 "ZTDX Points Distribution"（可通过 POINTS_CLAIM_DOMAIN_NAME 环境变量覆盖）。

响应字段

字段	类型	说明
user	string	用户钱包地址
distribution_id	string	分配记录 UUID
amount	Decimal	可领取代币数量（人类可读）
nonce	int	EIP-712 nonce
deadline	int	领取截止时间（Unix 秒）
signature	string	后端 EIP-712 签名
domain.name	string	EIP-712 域名称
domain.version	string	EIP-712 域版本
domain.chain_id	int	链 ID
domain.verifying_contract	string	链上验证合约地址

EIP-712 Struct（链上验证用）

ClaimPointsRewards(
  address user,
  uint256 distributionId,
  uint256 amount,
  uint256 nonce,
  uint256 deadline
)

• distributionId 为 distribution UUID 的 big-endian uint256 表示
• amount 在链上验证时转换为 18 位精度 wei
• 签名在 claim_deadline 后失效（claim_status 设计上应在此后变为 expired）
• 链上确认后状态更新：claim_status → claimed，claimed_at 与 claim_tx_hash 填写

预留状态： claimed 与 expired 的状态迁移目前为预留设计——尚无代码路径执行它们（TGE 前，分配合约尚未部署）。当前 claim_status 始终保持 pending。

错误码

错误码	说明
FORBIDDEN	分配记录不属于当前用户
NOT_FOUND	分配记录不存在
ALREADY_CLAIMED	已领取过
EXPIRED	超过领取截止时间
SIGNER_UNAVAILABLE	后端签名密钥未配置
SIGN_FAILED	签名失败

代码示例

Python

import requests

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

resp = requests.post(
    f"{BASE_URL}/points/claim/{DISTRIBUTION_ID}",
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
)
data = resp.json()["data"]

print(f"代币数量: {data['amount']}")
print(f"签名: {data['signature']}")
print(f"截止时间: {data['deadline']}（Unix 秒）")
# 将 data 传入链上合约完成领取