Points

Developer reference for the Permissionless Rewards API service.

📈 Season 02 Updates (Updated: Oct 7, 2025) What's New: The is_eligible field now reflects the new reward redemption requirements.

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 six data points are exposed (rank, EVM wallet address, Solana wallet address, tier, points balance, eligibility status); no personal data is shared.

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

📈 Quick Access for Non-Technical users: See all leaderboard data in Nansen Points Hub! 🌐 See it here: https://app.nansen.ai/points

Points Leaderboard

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

Fetch a complete snapshot of eligible Nansen Points users via the public endpoint. No API key or authentication required.

Query Parameters

Name	Type	Required	Default	Description
tier	string	No	―	Filter by tier name. Valid values: green, ice, north, star
isEligible	boolean	No	true	Filter by reward eligibility status. Valid values: "true" , "false" (ineligible users)

Example Request

Recommended – Browser Access: Open these URLs directly in your browser:

• Eligible users: https://app.nansen.ai/api/points-leaderboard

Response

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

Response Structure

[
    {
      "rank": 1,
      "evm_address": "0x6E93Ebc8302890fF1D1BeFd779D1DB131eF30D4d",
      "solana_address": "EhWT1SJXSCF6YTmUpTgH1xa8xZiGqEPSED3CWfR4cicM",
      "points": 1138320,
      "tier": "star",
      "is_eligible": true
    }
    // … all eligible users …
  ]

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	integer	Total accumulated points.
tier	string	Tier name determined by points thresholds. Valid values: "green", "ice", "north", "star".
is_eligible	boolean	true if the user currently meets reward eligibility criteria.

Usage Notes

API Behavior:

• Complete Dataset: Returns all qualifying users in one response

• Minimum Qualification: Only users with 1000+ points (Green tier threshold) are included

• No Server Pagination: Single request gets full leaderboard data

• Tier Restrictions: Users below the Green tier threshold are excluded

• Data Filtering: Users must have at least one wallet address to appear.

Guidelines

• Browser Access: Most reliable method - open URLs directly in any web browser

• Public & Permissionless No authentication header or API key required

• Single Request: Get complete leaderboard data in one API call

• Response Format: The API returns a raw JSON array. Access the data directly via response.json() (no wrapper object).

• Rank Handling: Users with identical points 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 once a day (11am UTC). Implement local caching to reduce redundant calls.