get_cosmos_balance
Query Cosmos blockchain balance for any address across networks like Osmosis, Juno, Kava, and Akash. Specify blockchain, address, and optional denomination to retrieve token holdings.
Instructions
Get balance for a Cosmos SDK address on any Cosmos chain
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | Cosmos address | |
| blockchain | Yes | Blockchain name (e.g., "osmosis", "juno", "kava", "akash") | |
| denom | No | Optional: Specific denomination to query (e.g., "uosmo", "ujuno") | |
| network | No | Network type (defaults to mainnet) |
Implementation Reference
- src/handlers/cosmos-handlers.ts:385-402 (handler)Handler logic for executing the 'get_cosmos_balance' tool: extracts parameters from args and delegates to CosmosService.getBalance, then returns formatted response.case 'get_cosmos_balance': { const blockchain = args?.blockchain as string; const address = args?.address as string; const denom = args?.denom as string | undefined; const network = (args?.network as 'mainnet' | 'testnet') || 'mainnet'; const result = await cosmosService.getBalance(blockchain, address, denom, network); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], isError: !result.success, }; }
- Tool schema definition: specifies name, description, input schema with properties for blockchain, address, optional denom and network.{ name: 'get_cosmos_balance', description: 'Get balance for a Cosmos SDK address on any Cosmos chain', inputSchema: { type: 'object', properties: { blockchain: { type: 'string', description: 'Blockchain name (e.g., "osmosis", "juno", "kava", "akash")', }, address: { type: 'string', description: 'Cosmos address', }, denom: { type: 'string', description: 'Optional: Specific denomination to query (e.g., "uosmo", "ujuno")', }, network: { type: 'string', enum: ['mainnet', 'testnet'], description: 'Network type (defaults to mainnet)', }, }, required: ['blockchain', 'address'], }, },
- src/index.ts:88-101 (registration)Registers all tools including Cosmos tools via registerCosmosHandlers(server, cosmosService) in the tools array provided to the MCP server.const tools: Tool[] = [ ...registerBlockchainHandlers(server, blockchainService), ...registerDomainHandlers(server, domainResolver), ...registerTransactionHandlers(server, advancedBlockchain), ...registerTokenHandlers(server, advancedBlockchain), ...registerMultichainHandlers(server, advancedBlockchain), ...registerContractHandlers(server, advancedBlockchain), ...registerUtilityHandlers(server, advancedBlockchain), ...registerEndpointHandlers(server, endpointManager), ...registerSolanaHandlers(server, solanaService), ...registerCosmosHandlers(server, cosmosService), ...registerSuiHandlers(server, suiService), ...registerDocsHandlers(server, docsManager), ];
- src/services/cosmos-service.ts:77-96 (helper)Core helper function in CosmosService that constructs the REST API URL for bank balances and performs the fetch request.async getBalance( blockchain: string, address: string, denom?: string, network: 'mainnet' | 'testnet' = 'mainnet' ): Promise<EndpointResponse> { try { const baseUrl = this.getRestUrl(blockchain, network); const url = denom ? `${baseUrl}/cosmos/bank/v1beta1/balances/${address}/by_denom?denom=${denom}` : `${baseUrl}/cosmos/bank/v1beta1/balances/${address}`; return this.fetchRest(url); } catch (error) { return { success: false, error: error instanceof Error ? error.message : 'Failed to get Cosmos balance', }; } }