GoldRush MCP Server

Instructions

Implementation Reference

• src/services/BalanceService.ts:272-359 (handler)

  The tool 'erc20_token_transfers' is defined and registered here within the 'addBalanceServiceTools' function. The handler uses the 'goldRushClient.BalanceService.getErc20TransfersForWalletAddressByPage' method to execute the logic.

  server.tool(
      "erc20_token_transfers",
      "Commonly used to render the transfer-in and transfer-out of a token along with historical prices from an address. " +
          "Required: chainName (blockchain network), walletAddress (wallet address). " +
          "Optional: quoteCurrency for value conversion, contractAddress to filter by specific token, " +
          "startingBlock/endingBlock to set range, pageSize (default 10) and pageNumber (default 0). " +
          "Returns token transfer events with timestamps, values, and transaction details.",
      {
          chainName: z
              .enum(Object.values(ChainName) as [string, ...string[]])
              .describe(
                  "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')."
              ),
          walletAddress: z
              .string()
              .describe(
                  "The wallet address to get ERC20 transfers for. Passing in an ENS, RNS, Lens Handle, or an Unstoppable Domain resolves automatically."
              ),
          quoteCurrency: z
              .enum(Object.values(validQuoteValues) as [string, ...string[]])
              .optional()
              .describe(
                  "Currency to quote transfer values in (e.g., 'USD', 'EUR'). If not specified, uses default quote currency."
              ),
          contractAddress: z
              .string()
              .nullable()
              .describe(
                  "Specific ERC20 token contract address to filter transfers. If null, returns transfers for all ERC20 tokens."
              ),
          startingBlock: z
              .number()
              .optional()
              .describe(
                  "Starting block number to begin search from. Use with endingBlock to define a range."
              ),
          endingBlock: z
              .number()
              .optional()
              .describe(
                  "Ending block number to search until. Use with startingBlock to define a range."
              ),
          pageSize: z
              .number()
              .optional()
              .default(10)
              .describe(
                  "Number of transfers to return per page. Default is 10, maximum is 100."
              ),
          pageNumber: z
              .number()
              .optional()
              .default(0)
              .describe(
                  "Page number for pagination, starting from 0. Default is 0."
              ),
      },
      async (params) => {
          try {
              const response =
                  await goldRushClient.BalanceService.getErc20TransfersForWalletAddressByPage(
                      params.chainName as Chain,
                      params.walletAddress,
                      {
                          quoteCurrency: params.quoteCurrency as Quote,
                          contractAddress: params.contractAddress,
                          startingBlock: params.startingBlock,
                          endingBlock: params.endingBlock,
                          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,
              };
          }
      }
  );