Retrieve Collection Holders

📘

Supported on Monad Testnet.

🚧

The Collection Holders API on Monad is currently available to our paid Members. Free tier members can also enjoy a trial period with 30 free calls. If you're interested, please register directly through here. Please note that the API Key can also be used for your RPC endpoint.

Parameter

• contractAddress, string - a 42 character address with '0x' as prefix. The NFT collection contract address to check for holders.
• pageIndex, string - the page number to retrieve. Defaults to 1.
• pageSize, string - the number of holders to return per page. Defaults to 20, maximum is 50.

Response

• code, number - response status code, e.g., 0 for success.
• reason, string - reason message if there's an error.
• message, string - response message, e.g., OK.
• result, object - result object containing NFT holder data.
  • data, array object - an array of NFT holder objects.
    • ownerAddress, string - the wallet address of the NFT holder.
    • amount, string - the number of NFTs owned by the holder.
    • uniqueTokens, number - the number of unique token IDs owned (important for ERC-1155).
    • lastTransaction, string - information about the last transaction.
    • percentage, string - the percentage of the total supply held by this holder.
    • value, string - the value of the NFTs (if available).
    • isContract, boolean - whether the holder address is a contract.
  • nextPageIndex, number - the index of the next page of results.

Note on ERC-721 vs ERC-1155

ERC-721 (Traditional NFTs):
Each token is completely unique and can only have one owner. For ERC-721 collections, you'll typically see:

• amount equals uniqueTokens (e.g., owning 5 NFTs means 5 unique token IDs)
• Each token ID is owned by exactly one address
• Example: CryptoPunks, where each punk has a unique token ID and can only be owned by one wallet

ERC-1155 (Multi-token Standard):
Allows multiple tokens of the same ID (fungible) and unique tokens (non-fungible) to exist in the same contract. For ERC-1155 collections:

• amount can be higher than uniqueTokens (e.g., owning 100 items might only be 10 different token IDs with multiple copies)
• The same token ID can have multiple copies owned by the same or different addresses
• Example: A gaming item collection where a "Common Sword" (ID #1) might exist in 1000 copies, while a "Legendary Shield" (ID #50) might exist in only 5 copies