token_holders
Retrieve current or historical token holders for ERC20/ERC721 tokens across multiple blockchains, with pagination and balance details.
Instructions
Used to get a paginated list of current or historical token holders for a specified ERC20 or ERC721 token.Required: chainName (blockchain network), tokenAddress (token contract address). Optional: blockHeight or date for historical data, pageSize and pageNumber for pagination. Returns list of addresses holding the token with balance amounts and ownership percentages.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chainName | Yes | The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet'). | |
| tokenAddress | Yes | The token contract address to get holders for. Supports ENS, RNS, Lens Handle, and Unstoppable Domain resolution. | |
| blockHeight | No | Specific block height to get historical token holders from. Cannot be used with date parameter. | |
| date | No | Specific date to get historical token holders from (YYYY-MM-DD format). Cannot be used with blockHeight parameter. | |
| pageSize | No | Number of token holders to return per page. Maximum is 100. | |
| pageNumber | No | Page number for pagination, starting from 0. |
Implementation Reference
- src/services/BalanceService.ts:401-429 (handler)The handler implementation for the 'token_holders' MCP tool. It calls the GoldRush client's getTokenHoldersV2ForTokenAddressByPage method with the provided parameters and returns the formatted response.
async (params) => { try { const response = await goldRushClient.BalanceService.getTokenHoldersV2ForTokenAddressByPage( params.chainName as Chain, params.tokenAddress, { blockHeight: params.blockHeight, date: params.date, pageSize: params.pageSize, pageNumber: params.pageNumber, } ); return { content: [ { type: "text", text: stringifyWithBigInt(response.data), }, ], }; } catch (error) { return { content: [{ type: "text", text: `Error: ${error}` }], isError: true, }; } } - The Zod schema definition for the 'token_holders' tool, defining the input parameters and their validation.
{ chainName: z .enum(Object.values(ChainName) as [string, ...string[]]) .describe( "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')." ), tokenAddress: z .string() .describe( "The token contract address to get holders for. Supports ENS, RNS, Lens Handle, and Unstoppable Domain resolution." ), blockHeight: z .union([z.string(), z.number()]) .optional() .describe( "Specific block height to get historical token holders from. Cannot be used with date parameter." ), date: z .string() .optional() .describe( "Specific date to get historical token holders from (YYYY-MM-DD format). Cannot be used with blockHeight parameter." ), pageSize: z .number() .optional() .describe( "Number of token holders to return per page. Maximum is 100." ), pageNumber: z .number() .optional() .describe("Page number for pagination, starting from 0."), }, - src/services/BalanceService.ts:361-366 (registration)Registration of the 'token_holders' tool within the MCP server instance inside the addBalanceServiceTools function.
server.tool( "token_holders", "Used to get a paginated list of current or historical token holders for a specified ERC20 or ERC721 token." + "Required: chainName (blockchain network), tokenAddress (token contract address). " + "Optional: blockHeight or date for historical data, pageSize and pageNumber for pagination. " + "Returns list of addresses holding the token with balance amounts and ownership percentages.",