Get User Leaderboard Entry

Retrieve a specific user's leaderboard position and stats by their wallet address or identifier.

Conceptual Overview

Quick Start

Get User Data

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

The user leaderboard API provides:

User's Current Rank: Both points-only and referral-inclusive rankings
Multi-Currency Scores: Separate scores for Gold, XP, and Gems (events + referrals)
Identity Information: All linked wallet addresses and social accounts
Real-time Data: Current standings updated every hour

Use Cases

User Profile Pages: Show individual user's current ranking
Progress Tracking: Let users check their own performance
Competitive Features: Compare specific users
User Dashboards: Display personalized leaderboard stats

API Details

Endpoint: https://gql3.absinthe.network/api/rest/leaderboard/user/{address}
Method: GET
Auth: Authorization header (API key generated per campaign)
Response: JSON object with user's leaderboard entry

Authorization

Header

Authorization: Bearer \<YOUR_API_KEY>

Fetching User Data

curl

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

Address Format Examples

EVM Address

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

Response Format

Successful Response (User Found)

Complete Response

{
  "data": {
    "mart_leaderboard_secret_v2": [
      {
        "points_rank": 6,
        "rank_with_referral": 6,
        "gold_score": 0,
        "gold_referral_score": 0,
        "xp_score": 184079.69876499794,
        "xp_referral_score": 0,
        "gems_score": 0,
        "gems_referral_score": 0,
        "evm_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "discord_username": null,
        "twitter_username": null,
        "sol_address": "CgyDPEokAFugPQqj4zA5bN49QMeidtVRMA52YPr4t8Dp"
      }
    ]
  }
}

User Not Found

No Results

{
  "data": {
    "mart_leaderboard_secret_v2": []
  }
}

Path Parameters

Parameter	Type	Required	Description
`address`	string	Yes	User's wallet address (EVM or Solana format) in the URL path

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
`gold_score`	number	User's accumulated Gold points from events
`gold_referral_score`	number	Additional Gold points from referral activities
`xp_score`	number	User's accumulated XP points from events
`xp_referral_score`	number	Additional XP points from referral activities
`gems_score`	number	User's accumulated Gems from events
`gems_referral_score`	number	Additional Gems 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:

Missing Address Parameter

{
  "data": null,
  "errors": [
    {
      "message": "address path parameter is required",
      "extensions": { "code": "validation-failed" }
    }
  ]
}

Authentication Error

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

FAQ

How often is user data updated?

What happens if I search for a non-existent address?

Handling Empty Results

The API returns an empty array in mart_leaderboard_secret_v2 when no user is found. This is not an error - check if the array is empty to determine if the user exists.

const userData = response.data.mart_leaderboard_secret_v2;
if (userData.length === 0) {
  console.log('User not found');
} else {
  console.log('User found:', userData[0]);
}

Can I search by Discord or Twitter username?

What's the difference between points_rank and rank_with_referral?

Ranking Types

points_rank: Shows ranking based purely on points earned from events
rank_with_referral: Includes additional referral bonuses in the ranking calculation

{
  "points_rank": 42,           // Rank without referral bonuses
  "rank_with_referral": 38     // Rank with referral bonuses included
}

What are the different score types (Gold, XP, Gems)?

Currency Types

The API returns separate scores for each currency type in your campaign:

Gold: Premium currency, often used for special rewards
XP: Experience points, main progression currency
Gems: Collectible currency, often for special purchases

Each currency has both base scores and referral scores:

{
  "gold_score": 1250.5,          // Gold earned from events
  "gold_referral_score": 0,      // Gold earned from referrals
  "xp_score": 8750.25,           // XP earned from events
  "xp_referral_score": 420.75,   // XP earned from referrals
  "gems_score": 0,               // Gems earned from events
  "gems_referral_score": 0       // Gems earned from referrals
}

Does the API support partial address matching?

Exact Matching Required

No, you must provide the complete wallet address in the URL path. The API uses exact matching (case-insensitive for EVM addresses).

❌ Incorrect:

/leaderboard/user/0xd8dA6BF

✅ Correct:

/leaderboard/user/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

Can one user have both EVM and Solana addresses?

Multi-Chain Support

Yes, users can link multiple wallet types to their account. The API will return all linked addresses, with null values for unlinked types.

{
  "points_rank": 6,
  "rank_with_referral": 6,
  "gold_score": 0,
  "gold_referral_score": 0,
  "xp_score": 184079.69876499794,
  "xp_referral_score": 0,
  "gems_score": 0,
  "gems_referral_score": 0,
  "evm_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "sol_address": "CgyDPEokAFugPQqj4zA5bN49QMeidtVRMA52YPr4t8Dp",
  "discord_username": null,
  "twitter_username": null
}