get_user_balance
Retrieve token balances for specific users on designated blockchain networks to monitor holdings and verify transaction eligibility.
Instructions
Get user token balance on a specific chain
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chainId | Yes | Chain ID to check balance on | |
| tokenAddress | Yes | Token contract address | |
| userAddress | Yes | User address to check balance for |
Implementation Reference
- src/index.ts:265-290 (registration)Registration of the 'get_user_balance' tool including name, description, and input schema definition.
{ name: 'get_user_balance', description: 'Get user token balance on a specific chain', inputSchema: { type: 'object', properties: { chainId: { oneOf: [ { type: 'number' }, { type: 'string' }, ], description: 'Chain ID to check balance on', }, tokenAddress: { type: 'string', description: 'Token contract address', }, userAddress: { type: 'string', description: 'User address to check balance for', }, }, required: ['chainId', 'tokenAddress', 'userAddress'], additionalProperties: false, }, }, - src/types/index.ts:182-188 (schema)Zod input schema (BalanceQuerySchema) used for validating get_user_balance tool arguments.
export const BalanceQuerySchema = z.object({ chainId: z.union([z.number(), z.string()]), tokenAddress: z.string(), userAddress: z.string(), }); export type BalanceQuery = z.infer<typeof BalanceQuerySchema>; - src/index.ts:447-458 (handler)Main tool handler 'getUserBalance' that parses input schema and calls BalanceService for execution.
private async getUserBalance(args: any): Promise<MCPToolResult> { try { const request = BalanceQuerySchema.parse(args); const result = await this.balanceService.getBalance(request); return createSuccessResponse(result); } catch (error) { return createErrorResponse( error instanceof Error ? error.message : String(error), 'BALANCE_ERROR' ); } } - src/services/balance.ts:55-74 (handler)Core balance fetching logic in BalanceService.getBalance, dispatching to chain-specific balance retrievers.
async getBalance(query: BalanceQuery): Promise<BalanceResponse> { const { chainId, tokenAddress, userAddress } = query; const chainIdTyped = chainId as SupportedChainId; try { if (isEVMChain(chainIdTyped)) { return await this.getEVMBalance(chainIdTyped, tokenAddress, userAddress); } else if (isSolanaChain(chainIdTyped)) { return await this.getSolanaBalance(chainIdTyped, tokenAddress, userAddress); } else if (isSuiChain(chainIdTyped)) { return await this.getSuiBalance(chainIdTyped, tokenAddress, userAddress); } else if (isCosmosChain(chainIdTyped)) { return await this.getCosmosBalance(chainIdTyped, tokenAddress, userAddress); } else { throw new Error(`Unsupported chain: ${chainId}`); } } catch (error) { throw new Error(`Failed to get balance: ${error instanceof Error ? error.message : String(error)}`); } } - src/types/index.ts:191-200 (schema)Zod output schema (BalanceResponseSchema) defining the structure of balance query results.
export const BalanceResponseSchema = z.object({ chainId: z.union([z.number(), z.string()]), tokenAddress: z.string(), balance: z.string(), decimals: z.number(), symbol: z.string(), formattedBalance: z.string(), }); export type BalanceResponse = z.infer<typeof BalanceResponseSchema>;