GoldRush MCP Server

Instructions

Implementation Reference

• src/services/BalanceService.ts:31-113 (handler)

  The "token_balances" tool is registered in addBalanceServiceTools function in src/services/BalanceService.ts, where it defines its schema and handler logic using the GoldRush client.

  server.tool(
      "token_balances",
      "Commonly used to fetch the native and fungible (ERC20) tokens held by an address. " +
          "Required: chainName (blockchain network), address (wallet address). " +
          "Optional: quoteCurrency for value conversion, nft (include NFTs, default false), " +
          "noNftFetch, noSpam, and noNftAssetMetadata (all default true) to control data returned. " +
          "Returns detailed token balance information including spot prices and metadata.",
      {
          chainName: z
              .enum(Object.values(ChainName) as [string, ...string[]])
              .describe(
                  "The blockchain network to query (e.g., 'eth-mainnet', 'matic-mainnet', 'bsc-mainnet')."
              ),
          address: z
              .string()
              .describe(
                  "The wallet address to get token balances for. Must be a valid blockchain address."
              ),
          quoteCurrency: z
              .enum(Object.values(validQuoteValues) as [string, ...string[]])
              .optional()
              .describe(
                  "Currency to quote token values in (e.g., 'USD', 'EUR'). If not specified, uses default quote currency."
              ),
          nft: z
              .boolean()
              .optional()
              .default(false)
              .describe(
                  "Include NFT token balances in the response. Default is false."
              ),
          noNftFetch: z
              .boolean()
              .optional()
              .default(true)
              .describe(
                  "Skip fetching NFT metadata. Default is true for better performance."
              ),
          noSpam: z
              .boolean()
              .optional()
              .default(true)
              .describe(
                  "Filter out spam/scam tokens from results. Default is true."
              ),
          noNftAssetMetadata: z
              .boolean()
              .optional()
              .default(true)
              .describe(
                  "Skip fetching NFT asset metadata. Default is true for better performance."
              ),
      },
      async (params) => {
          try {
              const response =
                  await goldRushClient.BalanceService.getTokenBalancesForWalletAddress(
                      params.chainName as Chain,
                      params.address,
                      {
                          quoteCurrency: params.quoteCurrency as Quote,
                          nft: params.nft,
                          noNftFetch: params.noNftFetch,
                          noSpam: params.noSpam,
                          noNftAssetMetadata: params.noNftAssetMetadata,
                      }
                  );
              return {
                  content: [
                      {
                          type: "text",
                          text: stringifyWithBigInt(response.data),
                      },
                  ],
              };
          } catch (error) {
              return {
                  content: [{ type: "text", text: `Error: ${error}` }],
                  isError: true,
              };
          }
      }
  );