--- updatedAt: 2025-06-25T21:54:15.000Z agentTools: projectIndex: https://docs.nftgo.io/llms.txt --- # Get holders by collection Retrieve all holders of a specific collection. # OpenAPI definition ````json { "openapi": "3.0.2", "info": { "title": "API Documentation | NFTGo", "description": "\nNote: You can find our listing criteria here: https://docs.nftgo.io/docs/listing-criteria\n\n# Introduction\n[NFTGo.io](https://nftgo.io/) is a data analytics platform for NFTs. We provide support for NFTs on the Ethereum blockchain. This API includes:\n* Support for metrics like Market Cap and Volume (globally and per-collection)\n* NFT metadata and price information\n* Access to the custom rarity model\n* Address and portfolio tracking\n* Collection transaction history\n* NFT and profit rankings\n* .. And much more!\n\n# Authentication\nTo start exploring the NFTGo API, you need to sign up for an API key [here](https://nftgo.io/data-api/).\nUsing your API key, you can make requests to the NFTGo API by sending the API key as a **header** in your request. Below is an example:\n```Bash\ncurl http://127.0.0.1:5001/ -H X-API-KEY:\n```\n\nAll requests should be prefixed with [http://127.0.0.1:5001/.](http://127.0.0.1:5001/)\n\n# Rate limits\nCurrently, we have a rate limit of 5 request per second (5RPS). If your project needs a specialized plan, you can contact us [here](https://docs.google.com/forms/d/e/1FAIpQLSdToHwUCisiDhNiW_UcVdRgjjLxLNt3fW1cruvZoPpxKxJuGQ/viewform).\n\n\n", "version": "1.1.0", "x-logo": { "url": "https://static.nftgo.io/nftgo-logo-with-text-light.svg" } }, "servers": [ { "url": "https://data-api.nftgo.io" } ], "paths": { "/eth/v1/collection/{collection}/holders": { "get": { "tags": [ "Collection" ], "summary": "Get holders by collection", "description": "Retrieve all holders of a specific collection.", "operationId": "get_collection_holders_eth_v1_collection__collection__holders_get", "parameters": [ { "description": "The collection filter can be a contract address, collection id, slug or opensea slug.If the slug contains special characters, you need to escape them before performing the query.", "required": true, "schema": { "title": "Collection", "type": "string", "description": "The collection filter can be a contract address, collection id, slug or opensea slug.If the slug contains special characters, you need to escape them before performing the query." }, "example": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d", "name": "collection", "in": "path" }, { "description": "Support top holders, whales and blue chip holders.top_100_holders is will be deprecated.", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/HolderTypeEnum" } ], "description": "Support top holders, whales and blue chip holders.top_100_holders is will be deprecated.", "default": "top_holder" }, "name": "holder_type", "in": "query" }, { "description": "The index of data segments. The returned data is divided into many segments. One segment is returned at a time. {offset} parameter indicates the index of data segments.", "required": false, "schema": { "title": "Offset", "minimum": 0, "type": "integer", "description": "The index of data segments. The returned data is divided into many segments. One segment is returned at a time. {offset} parameter indicates the index of data segments.", "default": 0 }, "name": "offset", "in": "query" }, { "description": "The size of a returned data segment", "required": false, "schema": { "title": "Limit", "maximum": 50, "minimum": 1, "type": "integer", "description": "The size of a returned data segment", "default": 10 }, "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/_CollectionHolderList" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "CollectionHolder": { "title": "CollectionHolder", "required": [ "holder_address", "blockchain", "nft_num", "est_holding_value_usd", "est_holding_value_eth", "buy_volume_usd", "buy_volume_eth", "sell_volume_usd", "sell_volume_eth", "pnl_usd", "pnl_eth" ], "type": "object", "properties": { "holder_address": { "title": "Holder Address", "maxLength": 42, "minLength": 42, "pattern": "^0x[a-fA-F0-9]{40}$", "type": "string", "description": "holder's address", "example": "0x0a2542a170aa02b96b588aa3af8b09ab22a9d7ac" }, "blockchain": { "title": "Blockchain", "pattern": "[A-Z]+", "type": "string", "description": "Blockchain the address belongs to", "example": "ETH" }, "holding_value_usd": { "title": "Holding Value Usd", "type": "number", "description": "Deprecated.The holding value (USD) i.e. The sum of the last price of each NFT held by the address", "example": 11312.576910773714 }, "holding_value_eth": { "title": "Holding Value Eth", "type": "number", "description": "Deprecated.The holding value (ETh) i.e. The sum of the last price of each NFT held by the address", "example": 10.28416083 }, "nft_num": { "title": "Nft Num", "minimum": 0, "type": "integer", "description": "The number of NFTs owned by this address", "example": 3 }, "est_holding_value_usd": { "title": "Est Holding Value Usd", "type": "number", "description": "The estimated holding value (USD), a estimated price of a nft is calculated by 'if 7d volume of nft = 0 : estPrice = max(avg price, floor price)'; else : estPrice = last trade price", "example": 1718.7829654688755 }, "est_holding_value_eth": { "title": "Est Holding Value Eth", "type": "number", "description": "The estimated holding value (ETH), a estimated price of a nft is calculated by 'if 7d volume of nft = 0 : estPrice = max(avg price, floor price)'; else : estPrice = last trade price", "example": 1.56181818 }, "buy_volume_usd": { "title": "Buy Volume Usd", "type": "number", "description": "The buy volume (USD) i.e. the total usd the address payed for purchasing", "example": 1244908.5664819027 }, "buy_volume_eth": { "title": "Buy Volume Eth", "type": "number", "description": "The buy volume (ETH) i.e. the total usd the address payed for purchasing", "example": 1131.73506044 }, "sell_volume_usd": { "title": "Sell Volume Usd", "type": "number", "description": "The sell volume (USD) i.e. the total usd the address got by selling", "example": 647826.8522261272 }, "sell_volume_eth": { "title": "Sell Volume Eth", "type": "number", "description": "The sell volume (ETH) i.e. the total usd the address got by selling", "example": 588.93350202 }, "pnl_usd": { "title": "Pnl Usd", "type": "number", "description": "Pnl means profit and loss, positive value for profit and negative value for loss. Profit means the sum of realized profits (USD) made from sales and estimated unrealized profit of NFTs held by the address", "example": -9593.793945304838 }, "pnl_eth": { "title": "Pnl Eth", "type": "number", "description": "Pnl means profit and loss, positive value for profit and negative value for loss. Profit means the sum of realized profits (ETH) made from sales and estimated unrealized profit of NFTs held by the address", "example": -8.72163086 }, "is_whale": { "title": "Is Whale", "type": "boolean", "description": "Whether the address is a whale", "default": false } } }, "HTTPValidationError": { "title": "HTTPValidationError", "type": "object", "properties": { "detail": { "title": "Detail", "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } }, "HolderTypeEnum": { "title": "HolderTypeEnum", "enum": [ "blue_chip_holder", "whale", "top_100_holder", "top_holder" ], "type": "string", "description": "An enumeration." }, "ValidationError": { "title": "ValidationError", "required": [ "loc", "msg", "type" ], "type": "object", "properties": { "loc": { "title": "Location", "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] } }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } } }, "_CollectionHolderList": { "title": "_CollectionHolderList", "required": [ "total", "last_updated", "holders_info" ], "type": "object", "properties": { "total": { "title": "Total", "type": "integer", "description": "Total number of items", "example": 10000 }, "last_updated": { "title": "Last Updated", "type": "integer", "description": "Last updated timestamp in seconds", "example": 1652598929 }, "holders_info": { "title": "Holders Info", "type": "array", "items": { "$ref": "#/components/schemas/CollectionHolder" }, "description": "List of holders in the collection. Note: The returned values all default to the value of the NFT under the given collection" } }, "description": "如果 Model 的数据存在有效期， 则它应该继承 LastUpdatedModel" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true }, "security": [ { "ApiKeyAuth": [] } ] } ````