GoldRush MCP Server

Instructions

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,
          };
      }
  }

• src/services/BalanceService.ts:367-400 (schema)

  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.",