Skip to main content

​
Get Leaderboard

Retrieve leaderboard rankings with filtering and ordering.
cURL
curl "https://tally.genlayer.com/api/v1/leaderboard/?type=validator&limit=100&order=asc"

​
Query Parameters

​
type
string
default:"validator"
Leaderboard type:
  • validator - Active validators
  • builder - Builders
  • steward - Stewards
  • validator-waitlist - Waitlisted users (not yet validators)
  • validator-waitlist-graduation - Graduated validators
​
user_address
string
Filter by specific user’s Ethereum address
​
limit
integer
Number of entries to return (no pagination by default)
​
order
string
default:"asc"
Sort order: asc (ascending rank) or desc (descending rank)
​
search
string
Search by user name, email, or address

​
Response

[
  {
    "id": 1,
    "user": 42,
    "user_details": {
      "id": 42,
      "name": "Alice Builder",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "profile_image_url": "https://res.cloudinary.com/.../profile.jpg",
      "visible": true
    },
    "type": "builder",
    "total_points": 1500,
    "rank": 1,
    "graduation_date": null,
    "referral_points": {
      "builder_points": 250,
      "validator_points": 150
    },
    "active_validators_count": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-03-01T15:00:00Z"
  },
  {
    "id": 2,
    "user": 10,
    "user_details": {
      "id": 10,
      "name": "Bob Validator",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12",
      "profile_image_url": "https://res.cloudinary.com/.../bob.jpg",
      "visible": true
    },
    "type": "validator",
    "total_points": 2000,
    "rank": 1,
    "graduation_date": null,
    "referral_points": null,
    "active_validators_count": 3,
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-03-01T14:00:00Z"
  }
]

​
Get Top Leaderboard Entries

Get the top 10 entries on the validator leaderboard.
cURL
curl https://tally.genlayer.com/api/v1/leaderboard/top/

​
Response

Returns an array of the top 10 leaderboard entries (validator type).

​
Get Leaderboard Statistics

Get aggregate statistics for leaderboards.
cURL
curl "https://tally.genlayer.com/api/v1/leaderboard/stats/?type=builder"

​
Query Parameters

​
type
string
Filter stats by leaderboard type (optional, returns global stats if omitted)

​
Response

{
  "participant_count": 450,
  "contribution_count": 3250,
  "total_points": 125000,
  "builder_count": 150,
  "validator_count": 200,
  "creator_count": 75
}

​
Get User Statistics

Get detailed statistics for a specific user. 
curl https://tally.genlayer.com/api/v1/leaderboard/user/42/

​
Query Parameters

​
category
string
Filter by category: builder, validator, or steward

​
Response

{
  "totalContributions": 25,
  "totalPoints": 1500,
  "averagePoints": 60.0,
  "contributionTypes": [
    {
      "id": 5,
      "name": "Smart Contract Deploy",
      "category_slug": "builder",
      "category_name": "Builder",
      "count": 10,
      "total_points": 800,
      "percentage": 53.3
    },
    {
      "id": 8,
      "name": "Community Content",
      "category_slug": "builder",
      "category_name": "Builder",
      "count": 15,
      "total_points": 700,
      "percentage": 46.7
    }
  ]
}

​
Get Validator Waitlist Top

Get top N waitlist users for the Race to Testnet Asimov leaderboard.
cURL
curl "https://tally.genlayer.com/api/v1/leaderboard/validator-waitlist/top/?limit=10"

​
Query Parameters

​
limit
integer
default:"10"
Number of entries to return (1-100)

​
Response

Returns an array of leaderboard entries for validator-waitlist type.

​
Get Validator Waitlist Statistics

Get comprehensive statistics for the validator waitlist.
cURL
curl https://tally.genlayer.com/api/v1/leaderboard/validator-waitlist-stats/

​
Response

​
total_participants
integer
Total users on waitlist
​
total_contributions
integer
Total contributions from waitlist users
​
total_graduated_contributions
integer
Contributions from graduated validators
​
total_points
integer
Total points from waitlist users
​
total_graduated_points
integer
Points from graduated validators
​
total_graduated
integer
Number of graduated validators
{
  "total_participants": 150,
  "total_contributions": 1200,
  "total_graduated_contributions": 450,
  "total_points": 45000,
  "total_graduated_points": 18000,
  "total_graduated": 35
}

​
Get Leaderboard Types

Get all available leaderboard types and their configuration.
cURL
curl https://tally.genlayer.com/api/v1/leaderboard/types/

​
Response

[
  {
    "key": "validator",
    "name": "Validator Leaderboard",
    "ranking_order": "points_desc"
  },
  {
    "key": "builder",
    "name": "Builder Leaderboard",
    "ranking_order": "points_desc"
  },
  {
    "key": "validator-waitlist",
    "name": "Validator Waitlist",
    "ranking_order": "points_desc"
  }
]

​
Get Community Leaderboard

Get community statistics and top community members by referral points.
cURL
curl https://tally.genlayer.com/api/v1/leaderboard/community/

​
Response

​
total_community
integer
Number of users with referral points
​
total_builder_points
integer
Sum of all builder referral points
​
total_validator_points
integer
Sum of all validator referral points
​
top_community
array
List of users sorted by total referral points
{
  "total_community": 75,
  "total_builder_points": 5000,
  "total_validator_points": 3500,
  "top_community": [
    {
      "id": 10,
      "name": "Community Leader",
      "address": "0xabcdef...",
      "profile_image_url": "https://...",
      "builder_points": 500,
      "validator_points": 300,
      "total_points": 800
    }
  ]
}
Get users who earned the most points recently (last 30 days).
cURL
curl "https://tally.genlayer.com/api/v1/leaderboard/trending/?limit=10"

​
Query Parameters

​
limit
integer
default:"10"
Number of users to return (1-100)

​
Response

[
  {
    "user_name": "Alice Builder",
    "user_address": "0x1234...",
    "profile_image_url": "https://...",
    "total_points": 450,
    "builder": true,
    "validator": false,
    "steward": false
  }
]
If no recent activity (last 30 days), falls back to all-time top contributors.

​
Get Global Multipliers

Retrieve all global leaderboard multipliers.
cURL
curl https://tally.genlayer.com/api/v1/multipliers/

​
Response

[
  {
    "id": 1,
    "contribution_type": 5,
    "contribution_type_details": {
      "id": 5,
      "name": "Smart Contract Deploy",
      "slug": "smart-contract-deploy"
    },
    "multiplier_value": "1.50",
    "valid_from": "2024-01-01T00:00:00Z",
    "description": "Bonus for smart contract deployments",
    "notes": "Increased to encourage more deployments",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]

​
Get Active Multipliers

Get currently active multipliers (most recent for each contribution type).
cURL
curl https://tally.genlayer.com/api/v1/multipliers/active/

​
Response

Returns an array of multiplier objects (only the active one for each contribution type).

​
Recalculate Leaderboards (Admin Only)

Recalculate all leaderboards from scratch.
Admin authentication required - This endpoint is restricted to administrators.
cURL
curl -X POST https://tally.genlayer.com/api/v1/leaderboard/recalculate/ \
  --cookie "sessionid=admin_session"

​
Response

{
  "message": "Leaderboards recalculated successfully",
  "status": "success"
}

​
Ranking Rules

​
Rank Calculation

  • Ranks are 1-based (1 is the highest rank)
  • Users with equal points receive the same rank
  • The next rank after a tie skips numbers (e.g., 1, 1, 3, not 1, 1, 2)
  • Only visible users (visible=True) appear in leaderboards

​
Point Calculation

frozen_global_points = base_points × multiplier_at_creation
  • Points are “frozen” at creation time with the then-current multiplier
  • Changing multipliers doesn’t affect existing contributions
  • Total points = sum of all frozen_global_points for the leaderboard type

​
Leaderboard Types

  • Includes users with validator profile
  • Sums points from validator category contributions
  • Shows active_validators_count for multi-wallet operators
  • Includes users with builder profile
  • Sums points from builder category contributions
  • Excludes builder-welcome contribution
  • Users with validator-waitlist contribution
  • Pre-graduation leaderboard
  • Shows progression toward validator status
  • Users who graduated from waitlist to validator
  • Historical record of graduation points
  • Includes graduation_date field

​
Best Practices

  1. Cache leaderboard data - Recalculation is expensive
  2. Use limit parameter for performance
  3. Filter by type to reduce response size
  4. Monitor total_points for gamification features
  5. Use trending endpoint for highlighting recent activity

​
Next Steps

Users API

Access user profiles and data

Contributions API

View contribution history

Build docs developers (and LLMs) love

Get started for freeTalk to us