get_historical_balance

Instructions

Implementation Reference

• src/handlers/multichain-handlers.ts:119-141 (handler)

  Handler logic for executing the get_historical_balance tool: extracts parameters, calls the service method, and returns formatted response.

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

• src/handlers/multichain-handlers.ts:39-64 (schema)

  Input schema and tool metadata definition for get_historical_balance.

  {
    name: 'get_historical_balance',
    description: 'Get balance at a specific block height',
    inputSchema: {
      type: 'object',
      properties: {
        blockchain: {
          type: 'string',
          description: 'Blockchain name',
        },
        address: {
          type: 'string',
          description: 'Address to check',
        },
        blockNumber: {
          description: 'Block number',
        },
        network: {
          type: 'string',
          enum: ['mainnet', 'testnet'],
          description: 'Network type (defaults to mainnet)',
        },
      },
      required: ['blockchain', 'address', 'blockNumber'],
    },
  },

• src/services/advanced-blockchain-service.ts:517-559 (helper)

  Core helper function implementing the historical balance query via eth_getBalance RPC call at a specific block.

  async getHistoricalBalance(
    blockchain: string,
    address: string,
    blockNumber: string | number,
    network: 'mainnet' | 'testnet' = 'mainnet'
  ): Promise<EndpointResponse> {
    const service = this.blockchainService.getServiceByBlockchain(blockchain, network);
  
    if (!service) {
      return {
        success: false,
        error: `Blockchain service not found: ${blockchain} (${network})`,
      };
    }
  
    const blockParam = typeof blockNumber === 'number'
      ? '0x' + blockNumber.toString(16)
      : blockNumber;
  
    const result = await this.blockchainService.callRPCMethod(
      service.id,
      'eth_getBalance',
      [address, blockParam]
    );
  
    if (result.success && result.data) {
      const weiBalance = BigInt(result.data);
      const ethBalance = Number(weiBalance) / 1e18;
      return {
        success: true,
        data: {
          address,
          blockNumber: blockParam,
          balance: ethBalance,
          balanceWei: weiBalance.toString(),
          balanceHex: result.data,
        },
        metadata: result.metadata,
      };
    }
  
    return result;
  }

• src/handlers/multichain-handlers.ts:10-87 (registration)

  Function that defines and returns the list of multichain tools including get_historical_balance for registration with the MCP server.

  export function registerMultichainHandlers(
    server: Server,
    advancedBlockchain: AdvancedBlockchainService
  ): Tool[] {
    const tools: Tool[] = [
      {
        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'],
        },
      },
      {
        name: 'get_historical_balance',
        description: 'Get balance at a specific block height',
        inputSchema: {
          type: 'object',
          properties: {
            blockchain: {
              type: 'string',
              description: 'Blockchain name',
            },
            address: {
              type: 'string',
              description: 'Address to check',
            },
            blockNumber: {
              description: 'Block number',
            },
            network: {
              type: 'string',
              enum: ['mainnet', 'testnet'],
              description: 'Network type (defaults to mainnet)',
            },
          },
          required: ['blockchain', 'address', 'blockNumber'],
        },
      },
      {
        name: 'get_gas_price',
        description: 'Get current gas price for a blockchain',
        inputSchema: {
          type: 'object',
          properties: {
            blockchain: {
              type: 'string',
              description: 'Blockchain name',
            },
            network: {
              type: 'string',
              enum: ['mainnet', 'testnet'],
              description: 'Network type (defaults to mainnet)',
            },
          },
          required: ['blockchain'],
        },
      },
    ];
  
    return tools;
  }