Get season

Fetch a leaderboard by season, showing user positions based on their experience points earned.

note

Some data may be cached up to 10 minutes for performance reasons. For real-time data please contact the On3 team for further details.

Request

HTTP GET to /leaderboards with Content-Type: application/json.

Example

/leaderboards

Query string parameters

season

Which season to fetch leaderboard data for. If this parameter is not supplied then this endpoint will return the global leaderboard. You can pass a value of 0 to fetch the current active season.

note

The Season ID may be different from the currently active season name, e.g., season ID 0 will always be the currently active season regardless of it's number.

Type	int
Required	No
Limitations	Must be a valid season number
Examples	1

limit

The number of leaderboard positions to fetch.

note

This endpoint is limited to only return ~1MB worth of data or ~6,000 rankings. If a user is not within this limit we'd highly recommend returning "Unranked" for them.

Type	int
Required	No
Limitations
Examples	100

userAddress

You can pass in a user address to easily get their leaderboard position and rank.

note

userPosition is only returned if the user is ranked within the leaderboards limit.

Type	string
Required	No
Limitations
Examples	"0x435Cd3902d1b4f4E842F2C0fd5028EEE71dd099C"

Response

Success (2XX)

{
    "season": { // object may be null if invalid season requested
        "id": "number",
        "start": "string" // in iso8601 format,
        "end": "string" // may be null if not yet ended, in iso8601 format
    },
    "userPosition": { // always null if `userAddress` is not passed or can be null if user not ranked within `limit`
            "address": "string", // wallet address
            "username": "string",
            "position": number, // number indicating the users ranking
            "avatarUrl": "string" // full uri,
            "score": number // xp points
    },
    "leaderboard": [
        {
            "address": "string", // wallet address
            "username": "string",
            "position": number, // number indicating the users ranking
            "avatarUrl": "string" // full uri,
            "score": number // xp points
        },
        // etc
    ]
}

Failure (4XX)

{
}

Codes

Code	Success	Description
2XX	Yes	Your request was successfully processed and data is returned.
4XX	No	Your request failed.
5XX	No	SOmething failed due to a server-side error. If the error continues after several attempts, please report this to the On3 support team.