Referral Commission Leaderboard

Returns the top-N referrers (users who own a referral code). Entries are ranked by number of referred users (descending), then by total claimed commission (descending). No authentication required.

GET /v1/referral/leaderboard?n=<1-50>

Query Parameters

Parameter	Type	Required	Default	Description
n	integer	No	10	Number of top entries to return; values outside 1–50 are clamped to that range

Response

[
  {
    "rank": 1,
    "referrer_address": "0x1234...abcd",
    "total_commission": "1234.567890",
    "computed_at": 1745280000000
  },
  {
    "rank": 2,
    "referrer_address": "0xabcd...5678",
    "total_commission": "987.654321",
    "computed_at": 1745280000000
  }
]

Response Fields

Field	Type	Description
rank	integer	Rank position (1 = most referred users)
referrer_address	string	Referrer's wallet address; 0x0000000000000000000000000000000000000000 if the referrer has no recorded address
total_commission	string	Total commission claimed via POST /v1/referral/claim (USDT, decimal string rounded to 6 dp). Unclaimed pending earnings are not included
computed_at	int64	Time of the request (milliseconds) — the leaderboard is computed live on each call

Error Codes

Errors are returned as a plain-text body, not JSON.

HTTP	Message	Description
400	(query rejection text)	n is not an integer (out-of-range values are clamped, not rejected)
500	(database error text)	Database query failed

Code Examples

Python

import requests

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

resp = requests.get(
    f"{BASE_URL}/v1/referral/leaderboard",
    params={"n": 10},
)
leaderboard = resp.json()

for entry in leaderboard:
    print(f"#{entry['rank']} {entry['referrer_address']}: {entry['total_commission']} USDT")

JavaScript

const resp = await fetch("https://api.rocky.exchange/v1/referral/leaderboard?n=10");
const leaderboard = await resp.json();

for (const entry of leaderboard) {
  console.log(`#${entry.rank} ${entry.referrer_address}: ${entry.total_commission} USDT`);
}