On-Chain Query Endpoints

Public endpoints that query the on-chain referral contracts. No authentication required.

---

User On-Chain Rebate Info

Read the user's complete rebate status from the ReferralRebate contract.

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

Path Parameters

Parameter	Type	Description
address	string	Ethereum address (0x format, 42 characters)

Response

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

Field	Type	Description
address	string	User address (lowercase)
claimed_usd	string	Total claimed amount on-chain (USDT, 6-decimal string)
nonce	uint64	Current claim nonce (increments after each claim)
referral_code	string	Bound referral code (bytes32 decoded)
referrer	string	Referrer address
tier_level	uint8	Tier number (0=Starter … 4=Diamond)
tier_name	string	Tier name

Error Codes

HTTP	Code	Description
400	INVALID_ADDRESS	Address format is invalid
500	CHAIN_ERROR	On-chain query failed

---

Trader On-Chain Referral Info

Read the trader's referral configuration (rebate BPS) from the ReferralRebate contract.

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

Path Parameters

Parameter	Type	Description
address	string	Ethereum address (0x format)

Response

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

Field	Type	Description
code	string	Referral code (bytes32 decoded)
referrer	string	Referrer address
total_rebate_bps	uint16	Total rebate basis points (1 bps = 0.01%)
trader_discount_bps	uint16	Fee discount for the trader (bps)
affiliate_reward_bps	uint16	Reward for the referrer (bps)

Error Codes

HTTP	Code	Description
400	INVALID_ADDRESS	Address format is invalid
500	CHAIN_ERROR	On-chain query failed

---

On-Chain Claimed Amount

Query the total amount a user has claimed on-chain.

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

Path Parameters

Parameter	Type	Description
address	string	Ethereum address (0x format)

Response

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

Field	Type	Description
address	string	User address
claimed_usd	string	Total claimed amount (USDT)

Error Codes

HTTP	Code	Description
400	INVALID_ADDRESS	Address format is invalid
500	CHAIN_ERROR	On-chain query failed

---

Operator Status

Check the backend signer address and its operator status in the contract. Useful for diagnosing on-chain signing service health.

GET /referral/on-chain/operator-status

Response

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

Field	Type	Description
operator_address	string	Backend signer's Ethereum address
is_operator	bool	Whether this address is a contract operator (false means batchSyncRebates will fail)
contract_address	string	ReferralRebate contract address

Code Examples

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']}")