Points

Developer reference for the Permissionless Rewards API service.

📈 Simplified for Better Developer Experience (Update: 31st July, 2025) We've streamlined this API by removing pagination to make leaderboard data more accessible. Get all qualifying users in a single request!

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 addresses, Solana wallet addresses, tier, points balance, active 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: Get all leaderboard data in one simple request! 🌐 Try it now: Star tier • Full leaderboard

Points Leaderboard

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

Fetch a complete snapshot of qualifying 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
isActive	string	No	true	Filter by activity status (active subsriber OR active staker). Valid values: "true" (active only), "false" (inactive only), "all" (all users)

Example Request

Browser Access (Recommended): Open these URLs directly in your browser:

• Active users: https://app.nansen.ai/api/points-leaderboard?isActive=all

• Star tier only: https://app.nansen.ai/api/points-leaderboard?tier=star

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
    }
    // … all qualifying 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_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

API Behavior:

• Complete Dataset: Returns all qualifying users in one response

• Minimum Qualification: Only users with 1000+ points (Tier 1 threshold) are included

• No Server Pagination: Single request gets full leaderboard data

• Tier Restrictions: Basecamp tier users are not included in results

Guidelines

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

• 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']

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

• Tier Filtering Omit tier parameter to retrieve entries across all qualifying 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.