account_balance
Check HBAR and token balances for Hedera accounts using Mirror Node queries to monitor funds and verify holdings without transaction fees.
Instructions
Query HBAR and token balances for any Hedera account.
RETURNS: HBAR balance in ℏ format, list of all associated token balances FREE: No transaction fee (Mirror Node query)
USE FOR: Checking account balances, monitoring funds, verifying token holdings.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountId | Yes | Account ID (format: 0.0.xxxxx) |
Implementation Reference
- src/tools/account.ts:15-34 (handler)The primary handler function that implements the core logic of the 'account_balance' tool. It invokes the hederaCLI service to fetch the account balance and handles errors appropriately.
export async function getAccountBalance(args: { accountId: string }): Promise<ToolResult> { try { logger.info('Getting account balance', { accountId: args.accountId }); const result = await hederaCLI.executeCommand({ command: 'account balance', args: { accountId: args.accountId, }, }); return result; } catch (error) { logger.error('Failed to get account balance', { error }); return { success: false, error: error instanceof Error ? error.message : 'Unknown error', }; } } - src/index.ts:135-149 (schema)Input schema and metadata for the 'account_balance' tool, provided in the optimizedToolDefinitions array and returned by the MCP listTools handler.
name: 'account_balance', description: `Query HBAR and token balances for any Hedera account. RETURNS: HBAR balance in ℏ format, list of all associated token balances FREE: No transaction fee (Mirror Node query) USE FOR: Checking account balances, monitoring funds, verifying token holdings.`, inputSchema: { type: 'object' as const, properties: { accountId: { type: 'string', description: 'Account ID (format: 0.0.xxxxx)' }, }, required: ['accountId'], }, }, - src/index.ts:569-571 (registration)Registration and dispatch logic in the main MCP tool execution switch statement, mapping incoming 'account_balance' calls to the handler function.
case 'account_balance': result = await getAccountBalance(args as { accountId: string }); break; - src/tools/account.ts:352-366 (schema)Modular tool schema definition within the exported accountTools array, matching the structure used in main index.
name: 'account_balance', description: 'Get the HBAR balance and token balances for a Hedera account. Returns the account balance in HBAR and a list of all associated token balances.', inputSchema: { type: 'object' as const, properties: { accountId: { type: 'string', description: 'Hedera account ID (format: 0.0.xxxxx)', pattern: '^0\\.0\\.\\d+$', }, }, required: ['accountId'], }, },