Get Leaderboard

Retrieve the current leaderboard rankings for your campaign, showing users ranked by their total points.

Conceptual Overview

The leaderboard API provides:

Ranked Users: Users ordered by total points (highest to lowest)
Pagination Support: Control how many results to fetch and from which position
Point Totals: Each user's current accumulated points
Identity Information: User identifiers (wallet addresses, emails, etc.)

Use Cases

Display Rankings: Show top performers in your app/game
Competition Tracking: Monitor user progress during campaigns
Analytics: Export leaderboard data for analysis
Rewards Distribution: Identify top users for rewards

API Details

Endpoint: https://gql3.absinthe.network/api/rest/leaderboard
Method: GET
Auth: Authorization header (API key generated per campaign)
Page Size: Fixed at 100 users per request
Response: JSON array of ranked users with points

Authorization

Header

Authorization: Bearer \<YOUR_API_KEY>

Fetching Leaderboard Data

curl

curl -X GET "https://gql3.absinthe.network/api/rest/leaderboard?offset=0" \
  -H "Authorization: Bearer \<YOUR_API_KEY>"

Pagination Examples

First 100 Users

curl -X GET "https://gql3.absinthe.network/api/rest/leaderboard?offset=0" \
  -H "Authorization: Bearer \<YOUR_API_KEY>"

Next 100 Users (ranks 101-200)

curl -X GET "https://gql3.absinthe.network/api/rest/leaderboard?offset=100" \
  -H "Authorization: Bearer \<YOUR_API_KEY>"

Users 201-300

curl -X GET "https://gql3.absinthe.network/api/rest/leaderboard?offset=200" \
  -H "Authorization: Bearer \<YOUR_API_KEY>"

Response Format

Successful Response

Example Response

{
  "data": {
    "mart_leaderboard_secret_v2": [
      {
        "points_rank": 1,
        "rank_with_referral": 1,
        "points_score": 12500,
        "referral_score": 0,
        "evm_address": "0xABC123...",
        "discord_username": null,
        "twitter_username": "cryptowhale",
        "sol_address": null
      },
      {
        "points_rank": 2,
        "rank_with_referral": 2,
        "points_score": 11800,
        "referral_score": 150,
        "evm_address": null,
        "discord_username": "player456",
        "twitter_username": null,
        "sol_address": "8ZUkk8pTyEAjyHbmBBXdrDNiNZ9D9Gcn5HgqxEjD8aHn"
      },
      {
        "points_rank": 3,
        "rank_with_referral": 4,
        "points_score": 10950,
        "referral_score": 300,
        "evm_address": "0xDEF789...",
        "discord_username": "gamer_pro",
        "twitter_username": "defi_master",
        "sol_address": null
      }
    ]
  }
}

Query Parameters

Parameter	Type	Required	Default	Description
`offset`	integer	No	0	Number of users to skip (for pagination)

Response Fields

Field	Type	Description
`points_rank`	integer	User's rank based purely on points (1 = first place)
`rank_with_referral`	integer	User's rank including referral bonuses
`points_score`	integer	User's accumulated points from events
`referral_score`	integer	Additional points from referral activities
`evm_address`	string\|null	User's Ethereum/EVM wallet address
`discord_username`	string\|null	User's Discord username
`twitter_username`	string\|null	User's Twitter/X username
`sol_address`	string\|null	User's Solana wallet address

Error Handling

All requests return 200 OK. Check the top-level errors[] array for failures:

Invalid Parameters

{
  "data": null,
  "errors": [
    {
      "message": "offset must be a non-negative integer",
      "extensions": { "code": "validation-failed" }
    }
  ]
}

Authentication Error

{
  "data": null,
  "errors": [
    {
      "message": "invalid or expired API key",
      "extensions": { "code": "unauthorized" }
    }
  ]
}

Implementation Examples

FAQ

How often is the leaderboard updated?

The leaderboard is updated every 1 hour.

Are ties handled in rankings?

Yes. Users with identical point totals receive the same rank, and subsequent ranks are adjusted accordingly (e.g., if two users tie for 3rd place, the next user is ranked 5th).

What's the difference between points_rank and rank_with_referral?

points_rank shows ranking based purely on points earned from events, while rank_with_referral includes additional referral bonuses in the ranking calculation.

How many users can I fetch per request?

Each request returns exactly 100 users. The page size is fixed and cannot be customized. Use the offset parameter to paginate through larger datasets.

How do I get all users if there are more than 100?

Use pagination by incrementing the offset parameter by 100 for each request:

Page 1: offset=0 (users 1-100)
Page 2: offset=100 (users 101-200)
Page 3: offset=200 (users 201-300)

Continue until you receive fewer than 100 results, which indicates you've reached the end.