Get Leaderboard

Retrieve the public leaderboard for a campaign, using privacy-safe user display rules.

API Details

Endpoint: GET /leaderboard
Auth: None (public)
Caching: Responses are cached for ~1 minute

Query parameters

Parameter	Type	Required	Default	Description
`campaign_id`	string	Yes	-	Campaign/season id (format: `xxxx-xxxx`)
`limit`	number	No	100	Max entries to return (1–1000)

Privacy-safe display rules

The leaderboard never returns or displays:

Email addresses
Wallet addresses
Secret identifiers

Instead it returns:

display_name: resolved by priority (first match wins)
- User-set name (users.name) only if it contains no bad-word substring (case-insensitive)
- Twitter username (if linked)
- Deterministic anonymous name (seeded by a secret user identifier)
avatar_url:
- Twitter avatar via https://unavatar.io/x/<twitter_username>
- Otherwise Dicebear via https://api.dicebear.com/9.x/lorelei/svg?seed=<seed>

Example request

curl -X GET "<PLATFORM_API_BASE_URL>/leaderboard?campaign_id=nhdv-0tkk&limit=100"

Example response

{
  "campaign_id": "nhdv-0tkk",
  "cached_at": "2025-01-01T00:00:00.000Z",
  "currency_names": { "xp": "XP", "gems": "Gems", "gold": "Gold" },
  "entries": [
    {
      "rank": 1,
      "user_id": "be9af004-2310-4acf-a2c5-77be909ef560",
      "display_name": "Cool Tiger",
      "avatar_url": "https://api.dicebear.com/9.x/lorelei/svg?seed=secret-1",
      "identities": { "x_username": "elonmusk" },
      "scores": {
        "xp": { "score": 125, "referral_score": 0, "total": 125 },
        "gems": { "score": 0, "referral_score": 0, "total": 0 },
        "gold": { "score": 0, "referral_score": 0, "total": 0 }
      }
    }
  ]
}