链上查询接口

公开接口，直接查询链上返佣合约数据。无需认证。

---

用户链上返佣信息

从 ReferralRebate 合约读取用户的完整返佣状态。

GET /referral/on-chain/user-rebate/:address

路径参数

参数	类型	说明
address	string	以太坊地址（0x 格式，42 字符）

响应

{
  "address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
  "claimed_usd": "0",
  "nonce": 0,
  "referral_code": "",
  "referrer": "0x0000000000000000000000000000000000000000",
  "tier_level": 0,
  "tier_name": "Starter"
}

字段	类型	说明
address	string	用户地址（lowercase）
claimed_usd	string	链上已领取总金额（USDT，6 位精度字符串）
nonce	uint64	当前 claim nonce（每次 claim 后递增）
referral_code	string	绑定的推荐码（bytes32 解码）
referrer	string	推荐人地址
tier_level	uint8	等级序号（0=Starter … 4=Diamond）
tier_name	string	等级名称

错误码

HTTP	错误码	说明
400	INVALID_ADDRESS	地址格式无效
500	CHAIN_ERROR	链上查询失败

---

Trader 链上推荐信息

从 ReferralRebate 合约读取 Trader 的推荐配置（返佣 BPS）。

GET /referral/on-chain/referral-info/:address

路径参数

参数	类型	说明
address	string	以太坊地址（0x 格式）

响应

{
  "address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
  "code": "",
  "referrer": "0x0000000000000000000000000000000000000000",
  "total_rebate_bps": 0,
  "trader_discount_bps": 0,
  "affiliate_reward_bps": 0
}

字段	类型	说明
code	string	推荐码（bytes32 解码）
referrer	string	推荐人地址
total_rebate_bps	uint16	总返佣基点（1 bps = 0.01%）
trader_discount_bps	uint16	Trader 享受的手续费折扣基点
affiliate_reward_bps	uint16	推荐人获得的奖励基点

错误码

HTTP	错误码	说明
400	INVALID_ADDRESS	地址格式无效
500	CHAIN_ERROR	链上查询失败

---

链上已领取金额

查询用户在链上已领取的总金额。

GET /referral/on-chain/claimed/:address

路径参数

参数	类型	说明
address	string	以太坊地址（0x 格式）

响应

{
  "address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
  "claimed_usd": "0"
}

字段	类型	说明
address	string	用户地址
claimed_usd	string	已领取总金额（USDT）

错误码

HTTP	错误码	说明
400	INVALID_ADDRESS	地址格式无效
500	CHAIN_ERROR	链上查询失败

---

后端 Signer 状态

查询后端 Signer 地址及其在合约中的 operator 状态（用于诊断链上签名服务健康度）。

GET /referral/on-chain/operator-status

响应

{
  "operator_address": "0x...",
  "is_operator": true,
  "contract_address": "0x..."
}

字段	类型	说明
operator_address	string	后端 Signer 的以太坊地址
is_operator	bool	该地址是否为合约 operator（false 时 batchSyncRebates 将失败）
contract_address	string	ReferralRebate 合约地址

代码示例

Python

import requests

BASE_URL = "https://api.ztdx.io"
address = "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489"

# 1. User on-chain rebate info
resp = requests.get(f"{BASE_URL}/referral/on-chain/user-rebate/{address}")
data = resp.json()
print(f"Tier: {data['tier_name']} (Level {data['tier_level']}), Claimed: {data['claimed_usd']}")

# 2. Trader referral info
resp = requests.get(f"{BASE_URL}/referral/on-chain/referral-info/{address}")
data = resp.json()
print(f"Code: {data['code']}, Referrer: {data['referrer']}")
print(f"Rebate BPS: {data['total_rebate_bps']}, Discount: {data['trader_discount_bps']}, Reward: {data['affiliate_reward_bps']}")

# 3. On-chain claimed amount
resp = requests.get(f"{BASE_URL}/referral/on-chain/claimed/{address}")
data = resp.json()
print(f"Total claimed on-chain: {data['claimed_usd']} USDT")

# 4. Operator status
resp = requests.get(f"{BASE_URL}/referral/on-chain/operator-status")
data = resp.json()
print(f"Operator: {data['operator_address']}, Active: {data['is_operator']}")