Appearance

Leaderboard ​

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

Get leaderboard ​

Get the leaderboard using the getLeaderboard method. The object returned contains 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.

typescript
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 filters, limit, offset.

Filter by users ​

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

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

Get leaderboard rank ​

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

typescript
await stack.getLeaderboardRank("0x2eeb301387D6BDa23E02fa0c7463507c68b597B5");

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