GoldRush MCP Server

Instructions

Implementation Reference

• src/services/BalanceService.ts:432-488 (handler)

  The native_token_balance tool handler registration and implementation in BalanceService.ts. It uses the Covalent SDK's BalanceService to fetch the balance.

  server.tool(
      "native_token_balance",
      "Lightweight endpoint to just get the native token balance for an EVM address. " +
          "Required: chainName (blockchain network), walletAddress (wallet address). " +
          "Optional: quoteCurrency for value conversion, blockHeight for historical balance. " +
          "Returns native token balance with current market value and token metadata.",
      {
          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 native token balance 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 native token value in (e.g., 'USD', 'EUR'). If not specified, uses default quote currency."
              ),
          blockHeight: z
              .union([z.string(), z.number()])
              .optional()
              .describe(
                  "Specific block height to get historical native token balance from."
              ),
      },
      async (params) => {
          try {
              const response =
                  await goldRushClient.BalanceService.getNativeTokenBalance(
                      params.chainName as Chain,
                      params.walletAddress,
                      {
                          quoteCurrency: params.quoteCurrency as Quote,
                          blockHeight: params.blockHeight,
                      }
                  );
              return {
                  content: [
                      {
                          type: "text",
                          text: stringifyWithBigInt(response.data),
                      },
                  ],
              };
          } catch (error) {
              return {
                  content: [{ type: "text", text: `Error: ${error}` }],
                  isError: true,
              };
          }
      }
  );