get_account_balance
Retrieve the HBAR balance of a Hedera account by providing the account ID and network. Uses JSON-RPC to query mainnet, testnet, or previewnet via the HashPilot MCP server.
Instructions
Get the HBAR balance of a Hedera account using JSON-RPC
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountId | Yes | The Hedera account ID (e.g., 0.0.12345) | |
| network | No | Network to query (mainnet, testnet, previewnet). Default: testnet |
Implementation Reference
- src/tools/account.ts:15-34 (handler)The primary handler function for the 'account_balance' tool (function named getAccountBalance). It orchestrates the tool execution by invoking the Hedera CLI service with the 'account balance' command.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/tools/account.ts:352-364 (schema)Input schema and metadata definition for the account_balance tool within the accountTools export.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'],
- src/index.ts:569-571 (registration)Tool registration in the MCP server's CallToolRequestSchema handler. Maps the tool name 'account_balance' to the getAccountBalance function.case 'account_balance': result = await getAccountBalance(args as { accountId: string }); break;
- src/index.ts:135-148 (schema)Active schema for 'account_balance' tool returned by ListToolsRequestSchema in optimizedToolDefinitions.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'], },
- Low-level helper function in HederaClientService that performs the actual SDK query for account balance using AccountBalanceQuery.async getAccountBalance(accountId: string): Promise<{ hbar: string; tokens: Record<string, string>; }> { try { const client = this.getClient(); const balance = await new AccountBalanceQuery() .setAccountId(AccountId.fromString(accountId)) .execute(client); // Convert token balances to object const tokens: Record<string, string> = {}; if (balance.tokens) { for (const [tokenId, amount] of balance.tokens) { tokens[tokenId.toString()] = amount.toString(); } } return { hbar: balance.hbars.toString(), tokens, }; } catch (error) { logger.error('Failed to get account balance', { accountId, error }); throw error; } }