Referral Dashboard

Returns the referrer's comprehensive earnings data, including tier information and recent activity.

GET /referral/dashboard
Authorization: Bearer <token>

Response

{
  "code": "4DDDC2D4",
  "total_referrals": 8,
  "active_referrals": 3,
  "total_referred_volume": "52000.00",
  "total_earnings": "125.50",
  "pending_earnings": "45.00",
  "claimed_earnings": "80.50",
  "tier": {
    "level": 1,
    "name": "Bronze",
    "commission_rate": "0.12",
    "rate_bps": 1200,
    "next_tier_referrals": 20,
    "next_tier_volume": "100000.00"
  },
  "recent_activity": [
    {
      "referral_address": "0xabc...",
      "event_type": "trade",
      "volume": "10000.00",
      "commission": "1.50",
      "timestamp": 1771900000000
    }
  ],
  "bound_referral": null
}

When the user has not yet reached the Starter threshold, tier is null:

{
  "code": "4DDDC2D4",
  "total_referrals": 0,
  "active_referrals": 0,
  "total_referred_volume": "0.00",
  "total_earnings": "0.00",
  "pending_earnings": "0.00",
  "claimed_earnings": "0.00",
  "tier": null,
  "tier_note": "Minimum rebate threshold not reached. Requirements: ≥1 referred user AND referred users' cumulative volume ≥ $1,000",
  "recent_activity": [],
  "bound_referral": null
}

Response Fields

Field	Type	Description
code	string | null	User's referral code
total_referrals	int64	Total number of referred users
active_referrals	int64	Number of active referees (recently traded)
total_referred_volume	Decimal	Cumulative trading volume of all referees (USD)
total_earnings	Decimal	Total lifetime earnings (USDT)
pending_earnings	Decimal	Unclaimed earnings (USDT)
claimed_earnings	Decimal	Already claimed earnings (USDT)
tier	object | null	Tier info; null if Starter threshold not yet reached
tier_note	string	Only present when tier is null; describes the unmet threshold

tier

null when the user has not yet met the Starter threshold.

Field	Type	Description
level	int	Tier level (0–4)
name	string	Tier name (Starter/Bronze/Silver/Gold/Diamond)
commission_rate	string	Commission rate as decimal (e.g., "0.12" = 12%)
rate_bps	int	Commission rate in basis points (1 bps = 0.01%)
next_tier_referrals	int | null	Referrals needed for next tier; null if Diamond
next_tier_volume	string | null	Referred users' cumulative volume needed for next tier (USD); null if Diamond

recent_activity[]

Field	Type	Description
referral_address	string	Referee's wallet address
event_type	string	Event type (e.g., "trade")
volume	Decimal	Trade volume (USD)
commission	Decimal	Commission earned (USDT)
timestamp	int64	Event timestamp (milliseconds)

bound_referral

Field	Type	Description
code	string	Referral code bound to
referrer_address	string	Referrer's wallet address
bound_at	int64	Binding timestamp (milliseconds)

bound_referral is null if the user is not bound to any referrer.

Tier Levels

Level	Name	Commission Rate	BPS	Min Referrals (AND)	Min Referred Volume (AND)
0	Starter	10%	1000	≥ 1	≥ $1,000
1	Bronze	12%	1200	≥ 5	≥ $10,000
2	Silver	17%	1700	≥ 20	≥ $100,000
3	Gold	22%	2200	≥ 50	≥ $500,000
4	Diamond	25%	2500	≥ 100	≥ $2,000,000

Both conditions must be satisfied simultaneously to reach a tier. Users who have not met the Starter threshold have tier: null in the response.

Tiers are recalculated automatically by the backend as referees trade.

Code Examples

Python

import requests

BASE_URL = "https://api.ztdx.io"
JWT_TOKEN = "your_jwt_token"

resp = requests.get(
    f"{BASE_URL}/referral/dashboard",
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
)
data = resp.json()

print(f"Code: {data['code']}")
print(f"Total referrals: {data['total_referrals']}, Active: {data['active_referrals']}")
print(f"Earnings — Total: {data['total_earnings']}, Pending: {data['pending_earnings']}, Claimed: {data['claimed_earnings']}")
if data['tier']:
    print(f"Tier: {data['tier']['name']} (Level {data['tier']['level']}), Commission: {data['tier']['commission_rate']}")
else:
    print(f"No tier yet — {data.get('tier_note', '')}")

for act in data["recent_activity"]:
    print(f"  {act['event_type']}: vol={act['volume']} commission={act['commission']}")