get_token_balance

Instructions

Implementation Reference

• src/handlers/token-handlers.ts:82-104 (handler)

  MCP tool handler for 'get_token_balance': parses input arguments (blockchain, tokenAddress, walletAddress, network) and delegates to AdvancedBlockchainService.getTokenBalance, formats response as MCP content.

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

• src/services/advanced-blockchain-service.ts:99-144 (helper)

  Core implementation: Retrieves ERC-20 token balance via eth_call to balanceOf(address) on EVM-compatible chains, processes hex result to decimal balance.

  async getTokenBalance(
    blockchain: string,
    tokenAddress: string,
    walletAddress: string,
    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})`,
      };
    }
  
    // Encode balanceOf(address) call
    const paddedAddress = walletAddress.replace('0x', '').padStart(64, '0');
    const data = AdvancedBlockchainService.ERC20_BALANCE_OF + paddedAddress;
  
    const result = await this.blockchainService.callRPCMethod(
      service.id,
      'eth_call',
      [
        {
          to: tokenAddress,
          data: data,
        },
        'latest',
      ]
    );
  
    if (result.success && result.data) {
      // Convert hex to decimal
      const balance = BigInt(result.data).toString();
      return {
        success: true,
        data: {
          balance,
          balanceHex: result.data,
        },
        metadata: result.metadata,
      };
    }
  
    return result;
  }

• src/handlers/token-handlers.ts:15-41 (registration)

  Tool registration definition including name, description, and input schema for get_token_balance, returned by registerTokenHandlers for MCP server registration.

  {
    name: 'get_token_balance',
    description: 'Get ERC-20 token balance for an address',
    inputSchema: {
      type: 'object',
      properties: {
        blockchain: {
          type: 'string',
          description: 'Blockchain name',
        },
        tokenAddress: {
          type: 'string',
          description: 'Token contract address',
        },
        walletAddress: {
          type: 'string',
          description: 'Wallet address to check balance',
        },
        network: {
          type: 'string',
          enum: ['mainnet', 'testnet'],
          description: 'Network type (defaults to mainnet)',
        },
      },
      required: ['blockchain', 'tokenAddress', 'walletAddress'],
    },
  },

• src/handlers/token-handlers.ts:18-40 (schema)

  Input schema validation for get_token_balance tool: requires blockchain, tokenAddress, walletAddress; optional network.

  inputSchema: {
    type: 'object',
    properties: {
      blockchain: {
        type: 'string',
        description: 'Blockchain name',
      },
      tokenAddress: {
        type: 'string',
        description: 'Token contract address',
      },
      walletAddress: {
        type: 'string',
        description: 'Wallet address to check balance',
      },
      network: {
        type: 'string',
        enum: ['mainnet', 'testnet'],
        description: 'Network type (defaults to mainnet)',
      },
    },
    required: ['blockchain', 'tokenAddress', 'walletAddress'],
  },