get_balance
Retrieve the current balance of a wallet for a specific or all networks, with optional fiat currency conversion.
Instructions
Get the current balance of the wallet.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| network | No | Query balance for specific network (e.g., "polygon-mainnet" or CAIP-2 "eip155:137"). Use "all" for all networks. Required for EVM wallets; auto-resolved for Solana. | |
| display_currency | No | Display currency for balance conversion (e.g. KRW, EUR). Defaults to server setting. | |
| wallet_id | No | Target wallet ID. Required for multi-wallet sessions; auto-resolved when session has a single wallet. |
Implementation Reference
- Main handler for the 'get_balance' MCP tool. Registers the tool with Zod schema for network, display_currency, and wallet_id params. Calls GET /v1/wallet/balance API endpoint and returns the result via toToolResult helper.
export function registerGetBalance(server: McpServer, apiClient: ApiClient, walletContext?: WalletContext): void { server.tool( 'get_balance', withWalletPrefix('Get the current balance of the wallet.', walletContext?.walletName), { network: z.string().optional().describe('Query balance for specific network (e.g., "polygon-mainnet" or CAIP-2 "eip155:137"). Use "all" for all networks. Required for EVM wallets; auto-resolved for Solana.'), display_currency: z.string().optional().describe('Display currency for balance conversion (e.g. KRW, EUR). Defaults to server setting.'), wallet_id: z.string().optional().describe('Target wallet ID. Required for multi-wallet sessions; auto-resolved when session has a single wallet.'), }, async (args) => { const params = new URLSearchParams(); if (args.network) params.set('network', args.network); if (args.display_currency) params.set('display_currency', args.display_currency); if (args.wallet_id) params.set('walletId', args.wallet_id); const qs = params.toString(); const result = await apiClient.get('/v1/wallet/balance' + (qs ? '?' + qs : '')); return toToolResult(result); }, ); } - Zod input schema for get_balance tool: network (optional string), display_currency (optional string), wallet_id (optional string).
{ network: z.string().optional().describe('Query balance for specific network (e.g., "polygon-mainnet" or CAIP-2 "eip155:137"). Use "all" for all networks. Required for EVM wallets; auto-resolved for Solana.'), display_currency: z.string().optional().describe('Display currency for balance conversion (e.g. KRW, EUR). Defaults to server setting.'), wallet_id: z.string().optional().describe('Target wallet ID. Required for multi-wallet sessions; auto-resolved when session has a single wallet.'), }, - packages/mcp/src/server.ts:17-94 (registration)Import and registration of registerGetBalance in the MCP server factory. Line 17 imports the function, line 94 calls it with server, apiClient, and walletContext.
import { registerGetBalance } from './tools/get-balance.js'; import { registerGetAddress } from './tools/get-address.js'; import { registerGetAssets } from './tools/get-assets.js'; import { registerListTransactions } from './tools/list-transactions.js'; import { registerGetTransaction } from './tools/get-transaction.js'; import { registerGetNonce } from './tools/get-nonce.js'; import { registerCallContract } from './tools/call-contract.js'; import { registerApproveToken } from './tools/approve-token.js'; import { registerSendBatch } from './tools/send-batch.js'; import { registerGetWalletInfo } from './tools/get-wallet-info.js'; import { registerEncodeCalldata } from './tools/encode-calldata.js'; import { registerSignTransaction } from './tools/sign-transaction.js'; import { registerX402Fetch } from './tools/x402-fetch.js'; import { registerWcConnect } from './tools/wc-connect.js'; import { registerWcStatus } from './tools/wc-status.js'; import { registerWcDisconnect } from './tools/wc-disconnect.js'; import { registerConnectInfo } from './tools/connect-info.js'; import { registerGetPolicies } from './tools/get-policies.js'; import { registerListSessions } from './tools/list-sessions.js'; import { registerGetTokens } from './tools/get-tokens.js'; import { registerListIncomingTransactions } from './tools/list-incoming-transactions.js'; import { registerGetIncomingSummary } from './tools/get-incoming-summary.js'; import { registerGetDefiPositions } from './tools/get-defi-positions.js'; import { registerGetHealthFactor } from './tools/get-health-factor.js'; import { registerSimulateTransaction } from './tools/simulate-transaction.js'; import { registerErc8004GetAgentInfo } from './tools/erc8004-get-agent-info.js'; import { registerErc8004GetReputation } from './tools/erc8004-get-reputation.js'; import { registerErc8004GetValidationStatus } from './tools/erc8004-get-validation-status.js'; import { registerGetProviderStatus } from './tools/get-provider-status.js'; import { registerSignMessage } from './tools/sign-message.js'; import { registerErc8128SignRequest } from './tools/erc8128-sign-request.js'; import { registerErc8128VerifySignature } from './tools/erc8128-verify-signature.js'; import { registerListNfts } from './tools/list-nfts.js'; import { registerGetNftMetadata } from './tools/get-nft-metadata.js'; import { registerTransferNft } from './tools/transfer-nft.js'; import { registerBuildUserop } from './tools/build-userop.js'; import { registerSignUserop } from './tools/sign-userop.js'; import { registerHyperliquidTools } from './tools/hyperliquid.js'; import { registerPolymarketTools } from './tools/polymarket.js'; import { registerListOffchainActions } from './tools/list-offchain-actions.js'; import { registerListCredentials } from './tools/list-credentials.js'; import { registerGetRpcProxyUrl } from './tools/get-rpc-proxy-url.js'; import { registerResolveAsset } from './tools/resolve-asset.js'; // Resource registrations (Task 2) import { registerWalletBalance } from './resources/wallet-balance.js'; import { registerWalletAddress } from './resources/wallet-address.js'; import { registerSystemStatus } from './resources/system-status.js'; import { registerSkillResources } from './resources/skills.js'; export interface WalletContext { walletName?: string; // e.g., 'trading-bot' } /** * Prefix description with wallet name for multi-wallet identification (MCPS-03). */ export function withWalletPrefix(description: string, walletName?: string): string { return walletName ? `[${walletName}] ${description}` : description; } export function createMcpServer(apiClient: ApiClient, walletContext?: WalletContext): McpServer { const serverName = walletContext?.walletName ? `waiaas-${walletContext.walletName}` : 'waiaas-wallet'; const server = new McpServer({ name: serverName, version: PKG_VERSION, }); // Register 42 tools registerConnectInfo(server, apiClient); registerListSessions(server, apiClient); registerGetPolicies(server, apiClient, walletContext); registerGetTokens(server, apiClient, walletContext); registerSendToken(server, apiClient, walletContext); registerGetBalance(server, apiClient, walletContext); - ApiClient.get() method used by the handler to make the actual HTTP GET request to the daemon's /v1/wallet/balance endpoint.
export function toToolResult<T>(result: ApiResult<T>): CallToolResult { if ('ok' in result && result.ok) { return { content: [{ type: 'text', text: JSON.stringify(result.data) }], }; } if ('expired' in result && result.expired) { return { content: [{ type: 'text', text: JSON.stringify({ session_expired: true, message: result.message, action: 'Run waiaas mcp setup to get a new token', }), }], // NO isError (H-04: prevents Claude Desktop from disconnecting) }; } if ('networkError' in result && result.networkError) { return { content: [{ type: 'text', text: JSON.stringify({ network_error: true, message: result.message, }), }], // NO isError }; } // Actual API error -- isError: true if ('error' in result) { return { content: [{ type: 'text', text: JSON.stringify({ error: true, ...result.error, }), }], isError: true, }; } // Should never happen -- fallback return { content: [{ type: 'text', text: JSON.stringify({ error: true, message: 'Unknown error' }) }], isError: true, }; } /** * Convert ApiResult to MCP resource result format (ReadResourceResult). */ export function toResourceResult<T>(uri: string, result: ApiResult<T>): ReadResourceResult { if ('ok' in result && result.ok) { return { contents: [{ uri, text: JSON.stringify(result.data), mimeType: 'application/json', }], }; } if ('expired' in result && result.expired) { return { contents: [{ uri, text: JSON.stringify({ session_expired: true, message: result.message, action: 'Run waiaas mcp setup to get a new token', }), mimeType: 'application/json', }], }; } if ('networkError' in result && result.networkError) { return { contents: [{ uri, text: JSON.stringify({ network_error: true, message: result.message, }), mimeType: 'application/json', }], }; } if ('error' in result) { return { contents: [{ uri, text: JSON.stringify({ error: true, ...result.error, }), mimeType: 'application/json', }], }; } return { contents: [{ uri, text: JSON.stringify({ error: true, message: 'Unknown error' }), mimeType: 'application/json', }], }; } // --- ApiClient --- export class ApiClient { private readonly sessionManager: SessionManager; private readonly baseUrl: string; constructor(sessionManager: SessionManager, baseUrl: string) { this.sessionManager = sessionManager; this.baseUrl = baseUrl.replace(/\/+$/, ''); } async get<T>(path: string): Promise<ApiResult<T>> {