GET_POSITIONS

Instructions

Implementation Reference

• src/tools/get-positions.ts:1-29 (handler)

  The GET_POSITIONS tool definition and execute handler. It initializes WalletService and BammPositionsService, calls getPositions() and formatPositions() to fetch and display all active BAMM positions for the user.

  import { BammPositionsService } from "../services/get-positions.js";
  import { WalletService } from "../services/wallet.js";
  
  export const getPositionsTool = {
  	name: "GET_POSITIONS",
  	description: "Get all your active BAMM positions",
  	// 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 positionsService = new BammPositionsService(walletService);
  
  			const positions = await positionsService.getPositions();
  			const formattedPositions = positionsService.formatPositions(positions);
  
  			return formattedPositions;
  		} catch (error) {
  			if (error instanceof Error) {
  				return `❌ Failed to retrieve positions: ${error.message}`;
  			}
  			return "❌ An unknown error occurred while retrieving positions";
  		}
  	},
  };

• src/services/get-positions.ts:9-21 (schema)

  The BammPosition interface defining the schema of a position: bamm address, vault (token0, token1, rented), pairAddress, poolName, token0Symbol, token1Symbol.

  export interface BammPosition {
  	bamm: Address;
  	vault: {
  		token0: bigint;
  		token1: bigint;
  		rented: bigint;
  	} | null;
  	// Additional Frax pool fields
  	pairAddress: string;
  	poolName: string;
  	token0Symbol: string;
  	token1Symbol: string;
  }

• src/services/get-positions.ts:30-102 (helper)

  The getPositions() method in BammPositionsService. Queries the BAMM factory for all BAMM addresses, checks if the user has a position in each via isUser(), fetches vault details and Fraxswap pool metadata for each active position.

  async getPositions(): Promise<BammPosition[]> {
  	const publicClient = this.walletService.getPublicClient();
  	const walletClient = this.walletService.getWalletClient();
  
  	if (!walletClient || !walletClient.account) {
  		throw new Error("Wallet client is not initialized");
  	}
  
  	const userAddress = walletClient.account.address;
  
  	// 1. Retrieve the list of all BAMM addresses from the factory
  	const bammsArray = [
  		...(await publicClient.readContract({
  			address: BAMM_ADDRESSES.FACTORY,
  			abi: BAMM_FACTORY_ABI,
  			functionName: "bammsArray",
  			args: [],
  		})),
  	];
  
  	const positions: BammPosition[] = [];
  
  	// 2. Loop through each BAMM contract address
  	for (const bamm of bammsArray) {
  		// 3. Check if the user is registered in this BAMM using isUser
  		const isUser: boolean = await publicClient.readContract({
  			address: bamm,
  			abi: BAMM_ABI,
  			functionName: "isUser",
  			args: [userAddress],
  		});
  
  		// 4. If the user is registered, get their vault details
  		if (isUser) {
  			const vault = await publicClient.readContract({
  				address: bamm,
  				abi: BAMM_ABI,
  				functionName: "getUserVault",
  				args: [userAddress],
  			});
  			// get pair address from the BAMM contract
  			const pairAddress = await publicClient.readContract({
  				address: bamm,
  				abi: BAMM_ABI,
  				functionName: "pair",
  				args: [],
  			});
  			// call fraxswap API to get the pool details
  			const response = await fetch(
  				`https://api.frax.finance/v2/fraxswap/pools/${pairAddress}`,
  			);
  			if (!response.ok) {
  				throw new Error(
  					`Failed to fetch pool details: ${response.statusText}`,
  				);
  			}
  			const poolData = await response.json();
  			const poolName = poolData.pools[0].poolName;
  			const token0Symbol = poolData.pools[0].token0Symbol;
  			const token1Symbol = poolData.pools[0].token1Symbol;
  			positions.push({
  				bamm,
  				vault,
  				pairAddress,
  				poolName,
  				token0Symbol,
  				token1Symbol,
  			});
  		}
  	}
  
  	return positions;
  }

• src/services/get-positions.ts:104-135 (helper)

  The formatPositions() method in BammPositionsService. Formats all BAMM positions into a human-readable message string with token amounts and rented info, filtering out zero-value or null positions.

  	formatPositions(positions: BammPosition[]) {
  		if (positions.length === 0 || positions.every((v) => !v)) {
  			return "📊 No Active BAMM Positions Found";
  		}
  
  		const formattedPositions = positions
  			.map((pos) => {
  				// Skip if vault is null
  				if (!pos.vault) {
  					return null;
  				}
  
  				// return if token0 and token1 is 0
  				if (pos.vault.token0 === 0n && pos.vault.token1 === 0n) {
  					return null;
  				}
  
  				return dedent`
              **💰 BAMM Position**
              - bamm: ${pos.bamm}
  						- Pair: ${pos.pairAddress}
              - ${pos.token0Symbol}: ${formatWeiToNumber(pos.vault.token0)}
              - ${pos.token1Symbol}: ${formatWeiToNumber(pos.vault.token1)}
  						- rented: ${formatWeiToNumber(pos.vault.rented)}
          `;
  			})
  			.filter(Boolean)
  			.join("\n\n");
  
  		return `📊 *Your Active BAMM Positions*\n\n${formattedPositions}`;
  	}
  }

• src/index.ts:21-25 (registration)

  Registration of the GET_POSITIONS tool on the FastMCP server via server.addTool(getPositionsTool).

  server.addTool(getPositionsTool);
  server.addTool(lendTool);
  server.addTool(poolStatsTool);
  server.addTool(removeCollateralTool);
  server.addTool(repayTool);