Collection Holders

Retrieve holder distribution and ownership analytics for any NFT collection.

Overview

The Collection Holders endpoint returns a ranked list of addresses holding NFTs from a specific collection, sorted by the number of NFTs owned. This is essential for:

• Analyzing holder concentration
• Identifying top collectors
• Building leaderboards
• Understanding collection distribution

Endpoint

GET /nfts/collection/{type}/holders

Base URL: https://api.surflux.dev

Parameters

Path Parameters

Parameter	Type	Required	Description
type	string	Yes	Full collection type path

Example: 0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog

Query Parameters

Parameter	Type	Required	Default	Description
page	number	No	0	Page number for pagination (starts from 0)
perPage	number	No	10	Number of items per page (max 50)
api-key	string	Yes	-	API key for authentication

Request Example

curl "https://api.surflux.dev/nfts/collection/0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog/holders?page=0&perPage=20&api-key=your_api_key_here"

Response

Response Structure

{
  "items": [
    {
      "owner": "0xf9c18a383d4f5c293bef82e4daf1ce82306b7b561cbef50d5c456a90d8547a5d",
      "count": 127
    },
    {
      "owner": "0x443f35e4d8e7f0f9e590e92569cf08b49bc24b63a92dc80b5d5510e753aad2e8",
      "count": 89
    },
    {
      "owner": "0x1148207ed0d1b54bd24172fe0a49092c858e363e702cc32c56bd9bf50afeb952",
      "count": 65
    }
  ],
  "isLastPage": false,
  "currentPage": 0,
  "perPage": 100
}

Response Fields

Field	Type	Description
items	array	Array of holder objects, sorted by count (descending)
isLastPage	boolean	Whether this is the last page of results
currentPage	number	Current page number
perPage	number	Items per page

Holder Object Fields

Field	Type	Description
owner	string	Wallet address of the holder
count	number	Number of NFTs from this collection owned by this address

Use Cases

• Holder Analytics — Analyze holder concentration and distribution patterns
• Leaderboards — Display top collectors for a collection
• Community Insights — Identify major stakeholders in a collection
• Whale Tracking — Monitor large holders for trading signals
• Airdrop Planning — Target holders for rewards or airdrops

Code Examples

JavaScript / TypeScript

const collectionType = "0x41c06da395bc3f0ee621a66082f8f30f376da41a2db7bcce7c087444de200e41::panzerdog::Panzerdog";
const apiKey = "your_api_key_here";

const response = await fetch(
  `https://api.surflux.dev/nfts/collection/${collectionType}/holders?page=0&perPage=20&api-key=${apiKey}`
);

const data = await response.json();

console.log("Top 3 holders:");
data.items.slice(0, 3).forEach((holder, index) => {
  console.log(`${index + 1}. ${holder.owner}: ${holder.count} NFTs`);
});

Advanced: Calculate Holder Concentration

async function getHolderConcentration(collectionType: string, apiKey: string) {
  const response = await fetch(
    `https://api.surflux.dev/nfts/collection/${collectionType}/holders?page=0&api-key=${apiKey}`
  );

  const data = await response.json();

  const totalNFTs = data.items.reduce((sum, h) => sum + h.count, 0);
  const top10NFTs = data.items.slice(0, 10).reduce((sum, h) => sum + h.count, 0);

  const concentration = (top10NFTs / totalNFTs) * 100;

  return {
    totalHolders: data.items.length,
    totalNFTs,
    top10Concentration: concentration.toFixed(2) + "%"
  };
}

Related Endpoints

• Collection Snapshot — Get all NFTs in a collection
• Address NFTs — Get NFTs owned by a specific address