get_token_balance

Instructions

Implementation Reference

• src/blockchain.ts:88-142 (handler)

  Core implementation of the get_token_balance tool: queries ERC20 contract for balance, decimals, symbol, name; formats balance; fetches optional USD value from SailFish subgraph.

  export async function getTokenBalance(
    tokenAddress: string, 
    walletAddress: string
  ): Promise<{ 
    balance: string, 
    decimals: number, 
    symbol: string, 
    name: string, 
    formattedBalance: string,
    usdValue?: string
  }> {
    try {
      const provider = getProvider();
      const tokenContract = new ethers.Contract(tokenAddress, ERC20_ABI, provider);
      
      // Get token details
      const [balance, decimals, symbol, name] = await Promise.all([
        tokenContract.balanceOf(walletAddress),
        tokenContract.decimals(),
        tokenContract.symbol(),
        tokenContract.name()
      ]);
      
      // Convert BigInt to string and number
      const balanceStr = bigIntToString(balance);
      const decimalsNum = Number(decimals);
      
      const formattedBalance = ethers.formatUnits(balance, decimalsNum);
      
      // Try to get USD value from SailFish
      let usdValue: string | undefined;
      try {
        const tokenPrice = await subgraph.getTokenPrice(tokenAddress);
        if (tokenPrice) {
          const valueInUsd = parseFloat(formattedBalance) * parseFloat(tokenPrice);
          usdValue = valueInUsd.toString();
        }
      } catch (error) {
        console.error('Error fetching token price:', error);
        // Continue without USD value
      }
      
      return {
        balance: balanceStr,
        decimals: decimalsNum,
        symbol: String(symbol),
        name: String(name),
        formattedBalance,
        usdValue
      };
    } catch (error) {
      console.error('Error fetching token balance:', error);
      throw error;
    }
  }

• src/index.ts:886-905 (registration)

  MCP tool dispatch/registration: handles CallToolRequest for 'get_token_balance' by validating params and calling blockchain.getTokenBalance, returning JSON result.

  case 'get_token_balance': {
    if (!args.tokenAddress || typeof args.tokenAddress !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Token address is required');
    }
    
    if (!args.walletAddress || typeof args.walletAddress !== 'string') {
      throw new McpError(ErrorCode.InvalidParams, 'Wallet address is required');
    }
    
    const balance = await blockchain.getTokenBalance(args.tokenAddress, args.walletAddress);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(balance, null, 2),
        },
      ],
    };
  }

• src/index.ts:314-330 (schema)

  Input schema definition and tool registration in ListToolsRequest handler for 'get_token_balance'.

    name: 'get_token_balance',
    description: 'Get the token balance of a wallet address with USD value using SailFish as price oracle',
    inputSchema: {
      type: 'object',
      properties: {
        tokenAddress: {
          type: 'string',
          description: 'Token contract address',
        },
        walletAddress: {
          type: 'string',
          description: 'Wallet address to check',
        },
      },
      required: ['tokenAddress', 'walletAddress'],
    },
  },

• src/index.ts:16-17 (registration)

  Import of the blockchain module containing the getTokenBalance handler.

  import * as blockchain from './blockchain.js';
  import * as swap from './swap.js';