Integration with the Leaderboard service

The Leaderboard Service is responsible for providing information about challenges, both active and past, as well as managing data related to user scores in these challenges.This service is designed to facilitate the retrieval of challenge-related data, including details about ongoing and historical challenges, and it also handles the transmission of user-specific scores within these challenges.

What Information Can We Display?

The most important data that we can display includes the user's Wallet Address, their Game Score, and their current position on the leaderboard. Additionally, we have created an endpoint /scores/personal/{userId}/{challengeId} that is useful when a user logs in to display information about their position and the positions of users both ahead and behind them.

Integrate the leaderboard service into your app

To integrate the leaderboard service into your app, you can use our API.

default

GET /challenges

This endpoint allows you to retrieve information about currently active challenges. You can view challenges and filter them based on various parameters.

Authentication

  • Authentication is not required to access this endpoint.

Environments:

Query parameters

Name

Description

skip

(number, optional): The number of records to skip in the response.

limit

(number, optional): The maximum number of records to return in the response.

challengeId

(string, optional): Filter challenges by challenge ID.

name

(string, optional): Filter challenges by name.

gameId

(string, optional): Filter challenges by game ID.

map

(string, optional): Filter challenges by the specific map or level.

elympicsGameIds

(array of strings, optional): Filter challenges by multiple Elympics game IDs.

gameIds

(array of strings, optional): Filter challenges by multiple game IDs.

maps

(array of strings, optional): Filter challenges by multiple map names.

elympicsGameIds

(array of strings, optional): Filter challenges by multiple Elympics game IDs.

Example cURL
curl -X 'GET' \
  'https://test-api.metaproprotocol.com/ms/leaderboard/challenges' \
  -H 'accept: */*'
Example response body (200 OK)
{
  "_id": "64cb761b267ef946a3986ee3",
  "challengeId": "e851683a-55ce-4b9a-9169-09ba5b89a111",
  "elympicsUserId": "95254826-ca97-4416-ae95-59c9ac2aa98c",
  "elympicsGameId": "f6239ae6-1111-4b4c-a741-771b85bf8871",
  "endedAt": "2023-08-04T12:50:08.046Z",
  "gameId": "eddb2e98-468a-4d70-977b-553d67d8f18c",
  "matchId": "327b4d12-a0b3-4473-b831-e5719a9d9627",
  "points": 2192.2273,
  "position": 1
}
Example of the response body (404 Not found)
{
    "message": "Cannot GET /scores5",
    "error": "Not Found",
    "statusCode": 404
}

GET /challenges/challenge/{challengeId}

This endpoint allows you to retrieve information about a specific challenge, including details such as its start time, associated game, map, and more. To access this information, you need to provide the challengeId as a required parameter

Authentication

  • Authentication is not required to access this endpoint.

Environments:

Query parameters

Name

Description

challengeId

(string, required): The unique identifier for the challenge you want to retrieve information about.

Example cURL
curl -X 'GET' \
  'https://test-api.metaproprotocol.com/ms/leaderboard/challenges/challenge/e851683a-55ce-4b9a-9169-09ba5b89a111' \
  -H 'accept: */*'
Example response body (200 OK)
{
  "_id": "64caa4bb58965c9bfe0a28ea",
  "gameId": "1009b077-98b5-4625-8fe3-74399826b190",
  "startDate": "2023-08-02T14:16:49.766Z",
  "endDate": "2023-08-07T18:31:49.766Z",
  "map": "classic",
  "elympicsGameId": "f6239ae6-1111-4b4c-a741-771b85bf8871",
  "challengeId": "e851683a-55ce-4b9a-9169-09ba5b89a111"
}
Example of the response body (404 Not found)
{
    "message": "Challenge not found",
    "error": "Not Found",
    "statusCode": 404
}

POST /scores/score

This endpoint allows you to send information about a user's current game score. To make a successful request, you need to provide the leaderboardAPIkey , which is encrypted to prevent fraudulent submissions to our leaderboard.

Authentication

  • Authentication with API KEY is required to access this endpoint.

Environments:

Query parameters

Name

Description

leaderboardAPIkey

(string, required): The encrypted API key for leaderboard access.

Example request sent (201 OK)
{
  "gameId": "string",
  "map": "classic",
  "elympicsUserId": "string",
  "walletAddress": "0x3203c9e46ca618c8c1ce5dc67e7e9d75f5da2377",
  "matchId": "123123",
  "startedAt": "2023-09-25T09:17:00.416Z",
  "endedAt": "2023-09-25T09:17:00.416Z",
  "roundData": {
    "score": 100,
    "diamonds": 5,
    "jumps": 12
  }
}
Example of the response body (401 - Unauthorized)
{
  "message": "Unauthorized",
  "statusCode": 401
}

GET /scores

This endpoint allows you to retrieve information about the current scores of a player. Authentication is not required to access this API. You can view and filter the leaderboard of a specific challenge using various parameters.

Authentication

  • Authentication is not required to access this endpoint.

Environments:

Query parameters

Name

Description

skip

(number, optional): The number of records to skip in the response.

limit

(number, optional): The maximum number of records to return in the response.

challengeId

(string, optional): Filter scores by challenge ID.

map

(string, optional): Filter scores by the specific map or level.

elympicsUserId

(string, optional): Filter scores by the player's user ID.

matchId

(string, optional): Filter scores by match ID.

position

(number, optional): Filter scores by player's position.

startedAt

(string, optional): Filter scores by the start date and time.

endedAt

(string, optional): Filter scores by the end date and time.

elypicsUserIds

(array of strings, optional): Filter scores by multiple player user IDs.

gameIds

(array of strings, optional): Filter scores by multiple game IDs.

Example cURL
curl -X 'GET' \
  'https://test-api.metaproprotocol.com/ms/leaderboard/scores' \
  -H 'accept: */*'
Example response body (200 OK)
{
  "_id": "64cb761b267ef946a3986ee3",
  "challengeId": "e851683a-55ce-4b9a-9169-09ba5b89a111",
  "elympicsUserId": "95254826-ca97-4416-ae95-59c9ac2aa98c",
  "elympicsGameId": "f6239ae6-1111-4b4c-a741-771b85bf8871",
  "endedAt": "2023-08-04T12:50:08.046Z",
  "gameId": "eddb2e98-468a-4d70-977b-553d67d8f18c",
  "matchId": "327b4d12-a0b3-4473-b831-e5719a9d9627",
  "points": 2192.2273,
  "position": 1
}
Example of the response body (404 Not found)
{
    "message": "Cannot GET /scores5",
    "error": "Not Found",
    "statusCode": 404
}

GET /scores/personal/{userId}/{challengeId}

This endpoint allows you to retrieve information about a specific user's scores, including scores of users positioned ahead and behind them in the leaderboard. To access this information, you need to provide the userId and challengeId as required parameters, as well as optional parameters for the number of positions ahead and behind.

Authentication

  • Authentication is not required to access this endpoint.

Environments:

Query parameters

Name

Description

scoresBefore

(number, optional): The number of positions backward in the leaderboard to include in the response.

scoresAfter

(number, optional): The number of positions forward in the leaderboard to include in the response.

userId

(string, required): The user ID for which you want to retrieve personal scores.

challengeId

(string, required): The ID of the challenge associated with the scores.

Example cURL
curl -X 'GET' \
  'https://test-api.metaproprotocol.com/ms/leaderboard/scores/personal/e240c9a8-5b06-4686-a847-433982607f99/e851683a-55ce-4b9a-9169-09ba5b89a111?positionsBack=1&positionsForward=1' \
  -H 'accept: application/json'
Example response body (200 OK)
[
  {
    "_id": "64cb761b267ef946a3986ee3",
    "challengeId": "e851683a-55ce-4b9a-9169-09ba5b89a111",
    "elympicsUserId": "95254826-ca97-4416-ae95-59c9ac2aa98c",
    "elympicsGameId": "f6239ae6-1111-4b4c-a741-771b85bf8871",
    "endedAt": "2023-08-04T12:50:08.046Z",
    "gameId": "eddb2e98-468a-4d70-977b-553d67d8f18c",
    "matchId": "327b4d12-a0b3-4473-b831-e5719a9d9627",
    "points": 2192.2273,
    "position": 1
  },
  {
    "_id": "64caa4ca267ef946a38f7548",
    "challengeId": "e851683a-55ce-4b9a-9169-09ba5b89a111",
    "elympicsUserId": "e240c9a8-5b06-4686-a847-433982607f99",
    "elympicsGameId": "f6239ae6-1111-4b4c-a741-771b85bf8871",
    "endedAt": "2023-08-03T10:25:17.473Z",
    "gameId": "eddb2e98-468a-4d70-977b-553d67d8f18c",
    "matchId": "58959652-eef1-4e5b-a5a0-4f8f504f724f",
    "points": 2002.6027,
    "position": 2
  },
  {
    "_id": "64cceff1267ef946a3a772de",
    "challengeId": "e851683a-55ce-4b9a-9169-09ba5b89a111",
    "elympicsUserId": "1f87d44b-e98e-4094-bf12-7f57a8fee1a2",
    "elympicsGameId": "f6239ae6-1111-4b4c-a741-771b85bf8871",
    "endedAt": "2023-08-04T03:55:03.158Z",
    "gameId": "eddb2e98-468a-4d70-977b-553d67d8f18c",
    "matchId": "204cf0ae-e59b-44eb-95c6-c46b006616ab",
    "points": 1989.1409,
    "position": 3
  }
]
Example of the response body (404 Not found)
{
  "message": "User not found",
  "error": "Not Found",
  "statusCode": 404
}
PreviousWhat information can we obtain?NextIntegration for in-Wallet Apps

Last updated