compare_balances

Instructions

Implementation Reference

• src/services/advanced-blockchain-service.ts:271-331 (handler)

  Core implementation of compare_balances tool: queries native token balances across multiple EVM chains using eth_getBalance RPC calls, converts to ETH, aggregates total and counts non-zero balances.

  async compareBalances(
    address: string,
    blockchains?: string[],
    network: 'mainnet' | 'testnet' = 'mainnet'
  ): Promise<EndpointResponse> {
    try {
      // Get all EVM chains if not specified
      const chainsToCheck = blockchains || this.getEVMChains();
  
      const results = await Promise.all(
        chainsToCheck.map(async (blockchain) => {
          const service = this.blockchainService.getServiceByBlockchain(blockchain, network);
          if (!service) {
            return { blockchain, error: 'Service not found', balance: null };
          }
  
          const result = await this.blockchainService.callRPCMethod(
            service.id,
            'eth_getBalance',
            [address, 'latest']
          );
  
          if (result.success && result.data) {
            const weiBalance = BigInt(result.data);
            const ethBalance = Number(weiBalance) / 1e18;
            return {
              blockchain,
              balance: ethBalance,
              balanceWei: weiBalance.toString(),
              balanceHex: result.data,
            };
          }
  
          return { blockchain, error: result.error, balance: null };
        })
      );
  
      const totalBalance = results
        .filter(r => r.balance !== null)
        .reduce((sum, r) => sum + (r.balance || 0), 0);
  
      return {
        success: true,
        data: {
          address,
          balances: results,
          totalBalance,
          chainsWithBalance: results.filter(r => r.balance && r.balance > 0).length,
        },
        metadata: {
          timestamp: new Date().toISOString(),
          endpoint: 'multi-chain',
        },
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Failed to compare balances',
      };
    }
  }

• src/handlers/multichain-handlers.ts:101-117 (handler)

  MCP tool handler wrapper: extracts parameters, calls the advanced blockchain service's compareBalances, formats response as MCP content with error flag.

  case 'compare_balances': {
    const address = args?.address as string;
    const blockchains = args?.blockchains as string[] | undefined;
    const network = (args?.network as 'mainnet' | 'testnet') || 'mainnet';
  
    const result = await advancedBlockchain.compareBalances(address, blockchains, network);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
      isError: !result.success,
    };
  }

• src/handlers/multichain-handlers.ts:18-37 (schema)

  JSON schema defining input parameters for the compare_balances tool: address (required), optional blockchains array and network enum.

  inputSchema: {
    type: 'object',
    properties: {
      address: {
        type: 'string',
        description: 'Address to check',
      },
      blockchains: {
        type: 'array',
        items: { type: 'string' },
        description: 'List of blockchain names (optional, defaults to all EVM chains)',
      },
      network: {
        type: 'string',
        enum: ['mainnet', 'testnet'],
        description: 'Network type (defaults to mainnet)',
      },
    },
    required: ['address'],
  },

• src/handlers/multichain-handlers.ts:15-38 (registration)

  Tool registration object including name, description, and input schema, returned by registerMultichainHandlers for inclusion in MCP server's tool list.

  {
    name: 'compare_balances',
    description: 'Compare native token balance for an address across multiple EVM chains',
    inputSchema: {
      type: 'object',
      properties: {
        address: {
          type: 'string',
          description: 'Address to check',
        },
        blockchains: {
          type: 'array',
          items: { type: 'string' },
          description: 'List of blockchain names (optional, defaults to all EVM chains)',
        },
        network: {
          type: 'string',
          enum: ['mainnet', 'testnet'],
          description: 'Network type (defaults to mainnet)',
        },
      },
      required: ['address'],
    },
  },