Nansen Points Leaderboard

Developer reference for the Permissionless Rewards API service.

Permissionless Rewards: Concepts

Before integrating the Nansen Points Leaderboard endpoint, it helps to understand Permissionless Rewards at a high level—see Nansen Academy: On Permissionless Rewards for full details.

• What they are: An open registry that maps Nansen Points balances to onchain wallets (EVM and Solana), without requiring an API key or explicit permission from Nansen.

• Why it matters: Protocols can seamlessly discover eligible wallets and distribute tokens, NFTs, or other perks—fully public and opt-in.

• Privacy model: Only four data points are exposed (wallet addresses, tier, last update, active status); no personal data is shared.

• User control: Holders can add or remove their wallet mapping at any time, revoking future distributions.

Points Leaderboard

GET https://api.nansen.ai/api/points-leaderboard

Fetch a public, paginated optionally tier-filtered snapshot of Nansen Points leaderboard. No API key or authentication required.

Query Parameters

Name	Type	Required	Default	Description
tier	string	No	―	Filter by tier name (e.g. green, ice, north, star ).
records_per_page	integer	No	10	Number of entries to return per page.
page	integer	No	1	Page number (1-indexed).
is_active	boolean	No	true	true if the user currently meets activity criteria (e.g. active subscription or actively staking).

Example Request

curl -s "https://api.nansen.ai/api/points-leaderboard?tier=north&records_per_page=10&page=1"

import requests

resp = requests.get(
    "https://api.nansen.ai/api/points-leaderboard",
    params={"tier": "star", "records_per_page": 20, "page": 2}
)
print(resp.json())

Response

Code	Description
200	Successful response
400	Bad request (invalid parameters)
500	Internal server error

Response Structure

{
  "data": [
    {
      "rank": 1,
      "evm_address": "0x6E93Ebc8302890fF1D1BeFd779D1DB131eF30D4d",
      "solana_address": "EhWT1SJXSCF6YTmUpTgH1xa8xZiGqEPSED3CWfR4cicM",
      "points_balance": 1138320,
      "tier": "star",
      "last_updated": "2025-06-18T05:27:19.915Z",
      "is_active": true
    }
    // … up to `records_per_page` items …
  ]
}

Record Fields (within data array):

Field	Type	Description
rank	integer	Position on the leaderboard.
evm_address	string | null	Ethereum-compatible wallet address, or null if none.
solana_address	string | null	Solana wallet address, or null if none.
points_balance	integer	Total accumulated points.
tier	string	Tier name determined by points thresholds. Valid values: "green", "ice", "north", "star".
last_updated	string	ISO 8601 timestamp when this record was last recalculated.
is_active	boolean	true if the user currently meets activity criteria (e.g. active subscription or actively staking).

Usage Notes

• Public & Permissionless No authentication header or API key required

• Response Format: The API returns data wrapped in a data field. Access the leaderboard entries via response.json()['data']

• Pagination Always include both page and records_per_page to control response size and avoid timeouts.

• Tier Filtering Omit the tier parameter to retrieve entries across all tiers.

• Rank Handling: Users with identical points_balance will share the same rank. The next distinct score will receive the immediately following rank (e.g. if two users tie for rank 5, the following user is rank 6).

• Cache-Friendly Leaderboard data refreshes roughly every 5 minutes. Implement local caching to reduce redundant calls.