Alchemy MCP Server

Implementation Reference

• index.ts:145-169 (registration)

  Registers the MCP tool 'fetchTokensOwnedByMultichainAddresses' with Zod input schema and an async handler that calls alchemyApi.getTokensByMultichainAddress and formats the response.

  server.tool('fetchTokensOwnedByMultichainAddresses', {
    addresses: z.array(z.object({
      address: z.string().describe('The wallet address to query. e.g. "0x1234567890123456789012345678901234567890"'),
      networks: z.array(z.string()).describe('The blockchain networks to query. e.g. ["eth-mainnet", "base-mainnet"]')
    })).describe('A list of wallet address and network pairs'),
  }, async (params) => {
    try {
      const result = await alchemyApi.getTokensByMultichainAddress(params);
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    } catch (error) {
      if (error instanceof Error) {
        console.error('Error in getTokensByMultichainAddress:', error);
        return {
          content: [{ type: "text", text: `Error: ${error.message}` }],
          isError: true
        };
      }
      return {
        content: [{ type: "text", text: 'Unknown error occurred' }],
        isError: true
      };
    }
  });

• api/alchemyApi.ts:65-82 (handler)

  Core implementation of the tool logic: creates Alchemy multi-chain token client, posts request to /by-address endpoint, processes response by converting hex balances to decimals using helper.

  async getTokensByMultichainAddress(params: MultiChainTokenByAddress) {
    try {
      const client = createMultiChainTokenClient();
      
      const response = await client.post('/by-address', {
        addresses: params.addresses.map((pair: AddressPair) => ({
          address: pair.address,
          networks: pair.networks
        }))
      });
  
      const responseData = convertHexBalanceToDecimal(response);
      return responseData;
    } catch (error) {
      console.error('Error fetching token data:', error);
      throw error;
    }
  },

• index.ts:146-149 (schema)

  Zod schema defining the input parameters for the tool: array of address-network pairs.

  addresses: z.array(z.object({
    address: z.string().describe('The wallet address to query. e.g. "0x1234567890123456789012345678901234567890"'),
    networks: z.array(z.string()).describe('The blockchain networks to query. e.g. ["eth-mainnet", "base-mainnet"]')
  })).describe('A list of wallet address and network pairs'),

• types/types.d.ts:23-25 (schema)

  TypeScript interface defining the input type MultiChainTokenByAddress used in alchemyApi.

  export interface MultiChainTokenByAddress {
    addresses: AddressPair[];
  }

• utils/convertHexBalanceToDecimal.ts:1-35 (helper)

  Helper utility that converts hexadecimal token balances from Alchemy API response to readable decimal values, handling token decimals.

  export default function convertHexBalanceToDecimal(response: any) {
      // Handle nested data structure - API returns { data: { data: { tokens: [...] } } }
      const responseData = response.data && response.data.data ? response.data.data : response.data;
          
      // Process tokens if they exist
      // LLMs are very bad at arithmetic, so we need to convert the hex balances to decimal
      if (responseData.tokens && Array.isArray(responseData.tokens)) {
        // Convert hex balances to decimal
        responseData.tokens = responseData.tokens.map((token: any) => {
          try {
            const processedToken = { ...token };
            const hexTokenBalance = token.tokenBalance;
            const tokenDecimals = parseInt(token.tokenMetadata.decimals || '18', 10);
            
            const bigIntBalance = BigInt(hexTokenBalance);
            const decimalBalance = Number(bigIntBalance) / Math.pow(10, tokenDecimals);
            
            // Store both formats
            processedToken.originalHexBalance = hexTokenBalance;
            processedToken.tokenBalance = decimalBalance;
            
            return processedToken;
          } catch (error) {
            // On error, return token with balance as 0 but keep original hex
            return {
              ...token,
              originalHexBalance: token.tokenBalance,
              tokenBalance: 0
            };
          }
        });
      }
    
      return responseData;
    }

• api/alchemyClients.ts:18-25 (helper)

  Helper function that creates configured axios client for Alchemy's multi-chain tokens API endpoint.

  export const createMultiChainTokenClient = () => axios.create({
    baseURL: `https://api.g.alchemy.com/data/v1/${API_KEY}/assets/tokens`,
    headers: {
        'accept': 'application/json',
        'content-type': 'application/json',
        'x-alchemy-client-breadcrumb': BREADCRUMB_HEADER
    },
  });