get_coin_balance
Check Aptos account balances for specific coin types, including custom tokens, to monitor holdings and verify transactions on the blockchain.
Instructions
Get the balance of a specific coin type for an Aptos account. This is used for checking the balance of custom coins or tokens. Returns the coin balance and metadata.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_address | Yes | Aptos account address, e.g., 0x1 or 0x742d35Cc6634C0532925a3b8D6Ac0C4db9c8b3 | |
| coin_type | Yes | Coin type identifier, e.g., '0x1::aptos_coin::AptosCoin' or custom coin type |
Implementation Reference
- src/tools/coin/getCoinBalance.ts:29-53 (handler)The main handler function that validates input arguments, calls the performGetCoinBalance helper, formats the response, and handles errors.export async function getCoinBalanceHandler(args: Record<string, any> | undefined) { if (!isGetCoinBalanceArgs(args)) { throw new Error("Invalid arguments for get_coin_balance"); } const { account_address, coin_type } = args; try { const results = await performGetCoinBalance(account_address, coin_type); return { content: [{ type: "text", text: results }], isError: false, }; } catch (error) { return { content: [ { type: "text", text: `Error getting coin balance: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } }
- Tool definition including name, description, and input schema for validating arguments.export const GET_COIN_BALANCE: Tool = { name: "get_coin_balance", description: "Get the balance of a specific coin type for an Aptos account. This is used for checking the balance of custom coins or tokens. Returns the coin balance and metadata.", inputSchema: { type: "object", properties: { account_address: { type: "string", description: "Aptos account address, e.g., 0x1 or 0x742d35Cc6634C0532925a3b8D6Ac0C4db9c8b3", }, coin_type: { type: "string", description: "Coin type identifier, e.g., '0x1::aptos_coin::AptosCoin' or custom coin type", }, }, required: ["account_address", "coin_type"], }, };
- Core helper function that interacts with the Aptos client to fetch the coin balance and formats the output string.export async function performGetCoinBalance(accountAddress: string, coinType: string): Promise<string> { try { const aptos = getAptosClient(); // Get account coin balance const balance = await aptos.getAccountCoinAmount({ accountAddress, coinType: coinType as `${string}::${string}::${string}`, }); // Try to get coin info for additional details let coinInfo = null; try { // Note: getCoinInfo might not be available in all SDK versions // coinInfo = await aptos.getCoinInfo({ coinType }); } catch (error) { // Coin info might not be available for all coins console.warn('Could not fetch coin info:', error); } let result = `Coin Balance Information: Account: ${formatAddress(accountAddress)} Coin Type: ${coinType} Balance: ${balance}`; // Note: Coin info functionality is commented out due to SDK compatibility // if (coinInfo) { // const formattedBalance = formatCoinAmount(balance, coinInfo.decimals); // result += ` // Formatted Balance: ${formattedBalance} ${coinInfo.symbol} // Coin Name: ${coinInfo.name} // Coin Symbol: ${coinInfo.symbol} // Decimals: ${coinInfo.decimals}`; // } result += ` Full Account Address: ${accountAddress}`; return result; } catch (error) { console.error('Error getting coin balance:', error); // Check if account doesn't exist or doesn't have this coin if (error instanceof Error && (error.message.includes('not found') || error.message.includes('does not exist'))) { return `Coin Balance Information: Account: ${formatAddress(accountAddress)} Coin Type: ${coinType} Balance: 0 Status: Account does not have this coin type or account does not exist Note: Account needs to register for this coin type before receiving it`; } throw new Error(`Failed to get coin balance: ${error instanceof Error ? error.message : String(error)}`); } }
- Type guard function for validating get_coin_balance arguments.export function isGetCoinBalanceArgs(args: unknown): args is { account_address: string; coin_type: string } { return ( typeof args === "object" && args !== null && "account_address" in args && typeof (args as any).account_address === "string" && "coin_type" in args && typeof (args as any).coin_type === "string" ); }
- src/index.ts:37-57 (registration)Registration of the get_coin_balance tool in the main tools list used by the MCP server.const TOOLS_LIST = [ // Account tools CREATE_ACCOUNT, GET_ACCOUNT_INFO, FUND_ACCOUNT, // Native APT tools GET_APT_BALANCE, TRANSFER_APT, // Coin tools GET_COIN_BALANCE, TRANSFER_COIN, DEPLOY_COIN, MINT_COIN, REGISTER_COIN, // Transaction tools GET_TRANSACTION_STATUS, GET_ACCOUNT_TRANSACTIONS, ];