wallet-inspector-mcp

Instructions

Query the balance of a specified wallet address across supported EVM and Solana blockchains.

Parameters:
    wallet_address (str): The wallet address to query (e.g., '0x123...' for EVM chains like Ethereum, 
                         Polygon, BSC, or 'DYw8jCT...' for Solana). Must be a valid address for the target chain.

Returns:
    str: Formatted table with balance information (chain, token amount, USD value) for supported chains or an error message.

Implementation Reference

• main.py:112-178 (handler)

  The core handler function for the 'get_wallet_balance' tool. It validates the wallet address, determines if it's EVM or Solana, calls helper functions to query Dune SIM API, processes the balance data, and returns a formatted ASCII table with chain, token amount, and USD value.

  @mcp.tool()
  async def get_wallet_balance(wallet_address: str) -> str:
      """
      Query the balance of a specified wallet address across supported EVM and Solana blockchains.
      
      Parameters:
          wallet_address (str): The wallet address to query (e.g., '0x123...' for EVM chains like Ethereum, 
                               Polygon, BSC, or 'DYw8jCT...' for Solana). Must be a valid address for the target chain.
      
      Returns:
          str: Formatted table with balance information (chain, token amount, USD value) for supported chains or an error message.
      """
      if not wallet_address:
          return "Error: Wallet address is required."
      
      balance_data = []
      supported_evm_chains = ["ethereum", "polygon", "bsc"]
      
      if is_evm_address(wallet_address):
          result = await query_evm_balance(wallet_address)
          if "error" in result:
              return f"Error querying EVM balance: {result['error']}"
          
          balances = result.get("balances", [])
          if not balances:
              return f"No balance data found for wallet {wallet_address}."
          
          for balance in balances:
              chain = balance.get("chain", "").lower()
              if chain not in supported_evm_chains:
                  continue
              amount = int(balance.get("amount", "0"))
              decimals = balance.get("decimals", 18)
              symbol = balance.get("symbol", "Unknown")
              value_usd = float(balance.get("value_usd", 0))
              # Convert amount to human-readable token quantity
              token_amount = amount / (10 ** decimals)
              balance_data.append([chain, f"{token_amount:.6f} {symbol}", f"${value_usd:.2f}"])
      
      elif is_solana_address(wallet_address):
          result = await query_svm_balance(wallet_address)
          if "error" in result:
              return f"Error querying Solana balance: {result['error']}"
          
          balances = result.get("balances", [])
          if not balances:
              return f"No balance data found for wallet {wallet_address}."
          
          for balance in balances:
              chain = balance.get("chain", "").lower()
              if chain != "solana":
                  continue
              token_amount = float(balance.get("balance", "0"))
              symbol = balance.get("symbol", "Unknown")
              value_usd = float(balance.get("value_usd", 0))
              balance_data.append([chain, f"{token_amount:.6f} {symbol}", f"${value_usd:.2f}"])
      
      else:
          return "Error: Invalid wallet address format. Use EVM (0x...) or Solana (Base58) address."
      
      if not balance_data:
          return f"No supported chain balances found for wallet {wallet_address}."
      
      # Generate ASCII table
      headers = ["Chain", "Token Amount", "USD Value"]
      table = tabulate(balance_data, headers=headers, tablefmt="grid")
      return f"Wallet {wallet_address} balances:\n\n{table}"

• main.py:25-39 (helper)

  Helper function to fetch EVM chain balances from Dune SIM API, used by get_wallet_balance for EVM addresses.

  async def query_evm_balance(wallet_address: str) -> Dict[str, Any]:
      """Query Dune SIM Balance API for wallet balance on EVM chains."""
      headers = {"X-Sim-Api-Key": DUNE_SIM_API_KEY}
      url = f"{DUNE_SIM_API_URL}/v1/evm/balances/{wallet_address}"
      
      async with httpx.AsyncClient() as client:
          try:
              response = await client.get(url, headers=headers)
              response.raise_for_status()
              return response.json()
          except httpx.HTTPStatusError as e:
              return {"error": f"HTTP error: {str(e)}"}
          except httpx.RequestError as e:
              return {"error": f"Request error: {str(e)}"}

• main.py:41-55 (helper)

  Helper function to fetch Solana (SVM) balances from Dune SIM API, used by get_wallet_balance for Solana addresses.

  async def query_svm_balance(wallet_address: str) -> Dict[str, Any]:
      """Query Dune SIM Balance API for wallet balance on Solana chain."""
      headers = {"X-Sim-Api-Key": DUNE_SIM_API_KEY}
      url = f"{DUNE_SIM_API_URL}/beta/svm/balances/{wallet_address}"
      
      async with httpx.AsyncClient() as client:
          try:
              response = await client.get(url, headers=headers)
              response.raise_for_status()
              return response.json()
          except httpx.HTTPStatusError as e:
              return {"error": f"HTTP error: {str(e)}"}
          except httpx.RequestError as e:
              return {"error": f"Request error: {str(e)}"}

• main.py:104-106 (helper)

  Helper function to validate if a wallet address is EVM-compatible (0x followed by 40 hex chars), used to route queries in get_wallet_balance.

  def is_evm_address(address: str) -> bool:
      """Check if the address is an EVM-compatible address."""
      return bool(re.match(r"^0x[a-fA-F0-9]{40}$", address))

• main.py:108-110 (helper)

  Helper function to validate if a wallet address is Solana-compatible (Base58, 32-44 chars), used to route queries in get_wallet_balance.

  def is_solana_address(address: str) -> bool:
      """Check if the address is a Solana-compatible address (Base58, 32-44 characters)."""
      return bool(re.match(r"^[1-9A-HJ-NP-Za-km-z]{32,44}$", address))

• main.py:112-112 (registration)

  The @mcp.tool() decorator registers the get_wallet_balance function as an MCP tool with the FastMCP server.

  @mcp.tool()