POOL_STATS

Instructions

Implementation Reference

• src/tools/pool-stats.ts:4-29 (handler)

  The POOL_STATS tool handler implementation. It initializes WalletService and BammPoolsStatsService, fetches pool stats, formats them, and returns the result or an error message.

  export const poolStatsTool = {
  	name: "POOL_STATS",
  	description: "Get statistics for all BAMM pools",
  	// biome-ignore lint/suspicious/noExplicitAny: <these are not used anyways>
  	execute: async (_params: any, _context: any) => {
  		try {
  			const privateKey = process.env.WALLET_PRIVATE_KEY;
  			if (!privateKey) {
  				return "Error: WALLET_PRIVATE_KEY environment variable is not set. Please set it with your wallet's private key (without 0x prefix).";
  			}
  
  			const walletService = new WalletService(privateKey);
  			const poolStatsService = new BammPoolsStatsService(walletService);
  
  			const pools = await poolStatsService.getPoolsStats();
  			const formattedStats = poolStatsService.formatPoolsStats(pools);
  
  			return formattedStats;
  		} catch (error) {
  			if (error instanceof Error) {
  				return `❌ Failed to retrieve pool statistics: ${error.message}`;
  			}
  			return "❌ An unknown error occurred while retrieving pool statistics";
  		}
  	},
  };

• src/index.ts:23-23 (registration)

  Registration of the poolStatsTool (POOL_STATS) with the FastMCP server.

  server.addTool(poolStatsTool);

• src/services/pool-stats.ts:26-84 (helper)

  Core logic in BammPoolsStatsService.getPoolsStats(): Fetches BAMM addresses from blockchain, maps to Fraxswap pools via API, filters and sorts by TVL.

  async getPoolsStats(): Promise<PoolStats[]> {
  	const publicClient = this.walletService.getPublicClient();
  	const zeroAddress = "0x0000000000000000000000000000000000000000";
  
  	// 1. Get the list of all BAMM addresses from the factory.
  	const bammsOnChain: readonly Address[] = await publicClient.readContract({
  		address: BAMM_ADDRESSES.FACTORY,
  		abi: BAMM_FACTORY_ABI,
  		functionName: "bammsArray",
  		args: [],
  	});
  
  	// 2. Build a mapping: underlying Fraxswap pair address -> BAMM address.
  	const pairToBammMap = new Map<string, string>();
  	for (const bammAddress of bammsOnChain) {
  		if (bammAddress === zeroAddress) continue;
  		// Get the Fraxswap pair address from this BAMM contract.
  		const pairAddress: Address = await publicClient.readContract({
  			address: bammAddress,
  			abi: BAMM_ABI,
  			functionName: "pair",
  			args: [],
  		});
  		if (pairAddress && pairAddress !== zeroAddress) {
  			pairToBammMap.set(pairAddress.toLowerCase(), bammAddress);
  		}
  	}
  
  	// 3. Fetch the full list of pools from the Frax API endpoint.
  	const response = await fetch(this.endpoint);
  	if (!response.ok) {
  		throw new Error(`Failed to fetch pools: ${response.statusText}`);
  	}
  	const data = await response.json();
  
  	// Map the API response to our PoolStats type and add placeholder fields.
  	// biome-ignore lint/suspicious/noExplicitAny: <explanation>
  	const allPools: PoolStats[] = data.pools.map((pool: any) => ({
  		...pool,
  		bammAddress: "",
  		bammApr: 0,
  		fraxswapApr: 0,
  	}));
  
  	// 4. Filter the API pools to only include those with a matching pair address.
  	const filteredPools: PoolStats[] = [];
  	for (const pool of allPools) {
  		const poolPair = pool.poolAddress.toLowerCase();
  		if (pairToBammMap.has(poolPair)) {
  			// Set the BAMM address from our mapping.
  			pool.bammAddress = pairToBammMap.get(poolPair) ?? "";
  			filteredPools.push(pool);
  		}
  	}
  
  	filteredPools.sort((a, b) => b.tvl - a.tvl);
  
  	return filteredPools;
  }

• src/services/pool-stats.ts:86-116 (helper)

  BammPoolsStatsService.formatPoolsStats(): Formats the pool statistics into a readable string with details for each pool.

  	formatPoolsStats(pools: PoolStats[]): string {
  		if (pools.length === 0) {
  			return "📊 No BAMM Pools Found";
  		}
  
  		const formattedStats = pools
  			.map((pool) => {
  				const poolName = `${pool.token0Symbol}/${pool.token1Symbol}`;
  				return dedent`
            📊 Pool: ${poolName}
            - Pool Address: ${pool.poolAddress}
            - BAMM Address: ${pool.bammAddress}
            - TVL: $${formatNumber(pool.tvl || 0)}
            - ${pool.token0Symbol} Locked: ${formatNumber(
  						pool.token0AmountLocked || 0,
  					)}
            - ${pool.token1Symbol} Locked: ${formatNumber(
  						pool.token1AmountLocked || 0,
  					)}
          `;
  			})
  			.join("\n\n");
  
  		return dedent`
        📊 *BAMM Pool Stats:*
        Total: ${pools.length}
  
        ${formattedStats}
      `;
  	}
  }

• src/services/pool-stats.ts:9-18 (schema)

  Type definition for PoolStats used in the service and returned by getPoolsStats().

  export interface PoolStats {
  	poolAddress: string;
  	bammAddress: string;
  	createdAtTimestamp: string;
  	token0Symbol: string;
  	token0AmountLocked: number;
  	token1Symbol: string;
  	token1AmountLocked: number;
  	tvl: number;
  }