wallet-inspector-mcp

Instructions

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()