Leaderboard

Each point system has a leaderboard that can be queried directly from the sdk.

Get a leaderboard

Get the leaderboard using the getLeaderboard method. The latest version returns an object with the leaderboard, metadata, and stats. The response defaults to the top 100 users, and you can specify the limit and offset to paginate through the leaderboard. Stats includes the total number of users in the leaderboard.

await stack.getLeaderboard();
// =>{
// leaderboard: [
//   {
//     address: '0x28B4DE9c45AF6cb1A5a46c19909108f2BB74a2BE',
//     points: 25,
//     identities: [Object]
//   },
//   {
//     address: '0x4d0c5acFb9C448Cb5dd869d9E6e5697Aa2a12Ec5',
//     points: 25,
//     identities: [Object]
//   },
//   {
//     address: '0x302aE9D5BDD8f5125b1182cdd966Ff4eEd3E3aCF',
//     points: 15,
//     identities: [Object]
//   },
//   metadata: {
//     label: '',
//     name: '',
//     description: '',
//     bannerUrl: '',
//     primaryColor: '#e64747',
//     createdAt: '2024-05-08T18:33:38.818Z',
//     url: 'https://stack.so/leaderboard/leaderboard-40a3-782251'
//   },
//   stats: { total: 14 },
//}

Parameters

• query: (Optional) LeaderboardQuery object

Returns

• leaderboard
  • address: The Ethereum address of the user.
  • points: The total points of the user.
  • identities: The identities associated with the user, e.g. Farcaster, Lens, ENS.
• metadata
  • label: The label of the leaderboard.
  • name: The name of the leaderboard.
  • description: The description of the leaderboard.
  • bannerUrl: The URL of the banner image for the leaderboard.
  • primaryColor: The primary color of the leaderboard.
  • createdAt: The creation date of the leaderboard.
  • url: The URL of the leaderboard.
• stats
  • total: The total number of users in the point system (useful for pagination).

LeaderboardQuery

As of v0.4.0, LeaderboardQuery is an object that can be constructed in order to handle filter, limit, offset.

Filter by users

const query = stack.leaderboardQuery()
  .where({
    associatedAccount: {
      in: [
        "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
      ]
    }
  })
  .build();

const leaderboard = await stack.getLeaderboard({query});

Iterate through first 1000 rows of a leaderboard

const rows = [];
for (let i = 0; i < 10; i++) {
  const query = stack.leaderboardQuery()
    .limit(100)
    .offset(100 * i)
    .build();
  const result = await stack.getLeaderboard({query});
  rows.push(...result.leaderboard);
}

Get Leaderboard Rank

Get the rank of an account in the leaderboard using the getLeaderboardRank method.

await stack.getLeaderboardRank("0x2eeb301387D6BDa23E02fa0c7463507c68b597B5");

// {
//   address: '0x627306090abaB3A6e1400e9345bC60c78a8BEf57',
//   rank: 1,
//   points: 10
// }