Referral Dashboard

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

GET /v1/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": [],
  "bound_referral": {
    "referrer_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
    "referrer_code": "A1B2C3D4"
  }
}

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

{
  "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 (null if none created)
total_referrals	int64	Total number of referred users (current bindings)
active_referrals	int64	Number of referees with at least one recorded trade (all-time, not time-windowed)
total_referred_volume	string	Cumulative qty × price trade volume of all referees (USD), decimal string rounded to 2 dp
total_earnings	string	Total lifetime accrued commission (USDT), 2 dp
pending_earnings	string	Unclaimed commission (USDT), 2 dp
claimed_earnings	string	Sum of all off-chain claims (USDT), 2 dp
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
recent_activity	array	Always [] currently — not yet populated by the backend
bound_referral	object | null	The user's own binding as a referee; null if not bound

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, 2 dp); null if Diamond

recent_activity[]

Not yet implemented — the backend always returns an empty array. No per-event fields are emitted.

bound_referral

Field	Type	Description
referrer_address	string | null	Referrer's wallet address
referrer_code	string	Referral code bound to

bound_referral is null if the user is not bound to any referrer. It does not include a bound_at timestamp — use GET /v1/referral/status as_referee.bound_at for that.

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; the highest tier for which both clear applies. Users who have not met the Starter threshold have tier: null in the response.

Tiers are recalculated automatically by the backend as referees trade. The dashboard computes the tier live from total_referrals and total_referred_volume.

Error Codes

Error format. Referral endpoints return errors as a plain-text body (text/plain) containing the message shown in the Message column, not a JSON object. A missing or invalid Authorization: Bearer session token returns 401 with missing bearer token / invalid session.

HTTP	Message	Description
401	missing bearer token / invalid session	Missing, expired or revoked session token
500	(database error text)	Server error

Code Examples

Python

import requests

BASE_URL = "https://api.rocky.exchange"
JWT_TOKEN = "your_jwt_token"

resp = requests.get(
    f"{BASE_URL}/v1/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']}")