get_portfolio_balances
Retrieve token balances for wallet addresses across multiple blockchain networks to monitor portfolio holdings without price data.
Instructions
Get token balances for wallet addresses (faster, no prices/metadata, uses USER_ADDRESS from env if addresses not provided)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addresses | No | Array of address and networks pairs (max 3 addresses, max 20 networks each). Optional - uses USER_ADDRESS from env if not provided | |
| networks | No | Network identifiers to use with USER_ADDRESS (e.g., 'eth-mainnet', 'base-mainnet'). Only used when addresses not provided. Defaults to ['eth-mainnet', 'base-mainnet'] | |
| includeNativeTokens | No | Include native tokens like ETH (optional, default: false) |
Implementation Reference
- src/toolService.js:650-691 (handler)Primary handler function for the get_portfolio_balances MCP tool. Validates and processes input (defaults to USER_ADDRESS), delegates to AgService, formats the response with summary and options.async getPortfolioBalances(params) { const { addresses, includeNativeTokens, networks } = params; // Use provided addresses or default to USER_ADDRESS with specified networks let targetAddresses; if (addresses && Array.isArray(addresses)) { targetAddresses = addresses; } else if (this.userAddress) { // Default to USER_ADDRESS with provided networks or common networks const defaultNetworks = networks || ["eth-mainnet", "base-mainnet"]; targetAddresses = [ { address: this.userAddress, networks: defaultNetworks, }, ]; } else { throw new Error( "Either addresses parameter or USER_ADDRESS environment variable is required" ); } const result = await this.agg.getPortfolioBalances(targetAddresses, { includeNativeTokens, }); return { message: "Portfolio balances retrieved successfully", data: result, summary: `Retrieved balances for ${ targetAddresses.length } address(es) across ${targetAddresses.reduce( (total, addr) => total + addr.networks.length, 0 )} network(s)`, addressUsed: targetAddresses[0].address, note: "Balances only - no prices or metadata for faster response", options: { includeNativeTokens: includeNativeTokens || false, }, }; }
- src/index.js:828-869 (schema)Input schema defining the parameters for get_portfolio_balances tool: addresses array with networks, fallback networks, and includeNativeTokens flag.inputSchema: { type: "object", properties: { addresses: { type: "array", description: "Array of address and networks pairs (max 3 addresses, max 20 networks each). Optional - uses USER_ADDRESS from env if not provided", items: { type: "object", properties: { address: { type: "string", description: "Wallet address", }, networks: { type: "array", items: { type: "string", }, description: "Network identifiers (e.g., 'eth-mainnet', 'base-mainnet')", }, }, required: ["address", "networks"], }, }, networks: { type: "array", items: { type: "string", }, description: "Network identifiers to use with USER_ADDRESS (e.g., 'eth-mainnet', 'base-mainnet'). Only used when addresses not provided. Defaults to ['eth-mainnet', 'base-mainnet']", }, includeNativeTokens: { type: "boolean", description: "Include native tokens like ETH (optional, default: false)", }, }, required: [], },
- src/index.js:1166-1168 (registration)Dispatch registration in MCP CallToolRequestSchema handler: routes get_portfolio_balances calls to toolService.getPortfolioBalances.case TOOL_NAMES.GET_PORTFOLIO_BALANCES: result = await toolService.getPortfolioBalances(args); break;
- src/services/agService.js:280-309 (helper)AgService helper that performs the actual API call to aggregator's /api/portfolio/balances endpoint to retrieve raw balance data.async getPortfolioBalances(addresses, options = {}) { try { const requestBody = { addresses, includeNativeTokens: options.includeNativeTokens }; const response = await fetch(`${this.baseUrl}/api/portfolio/balances`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(requestBody) }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${response.statusText}`); } const data = await response.json(); if (!data.success) { throw new Error(data.error || 'Portfolio balances request failed'); } return data.data; } catch (error) { throw new Error(`Failed to get portfolio balances: ${error.message}`); } }
- src/index.js:824-870 (registration)Full tool registration in ListToolsRequestSchema response, including name, description, and schema for MCP tool discovery.{ name: TOOL_NAMES.GET_PORTFOLIO_BALANCES, description: "Get token balances for wallet addresses (faster, no prices/metadata, uses USER_ADDRESS from env if addresses not provided)", inputSchema: { type: "object", properties: { addresses: { type: "array", description: "Array of address and networks pairs (max 3 addresses, max 20 networks each). Optional - uses USER_ADDRESS from env if not provided", items: { type: "object", properties: { address: { type: "string", description: "Wallet address", }, networks: { type: "array", items: { type: "string", }, description: "Network identifiers (e.g., 'eth-mainnet', 'base-mainnet')", }, }, required: ["address", "networks"], }, }, networks: { type: "array", items: { type: "string", }, description: "Network identifiers to use with USER_ADDRESS (e.g., 'eth-mainnet', 'base-mainnet'). Only used when addresses not provided. Defaults to ['eth-mainnet', 'base-mainnet']", }, includeNativeTokens: { type: "boolean", description: "Include native tokens like ETH (optional, default: false)", }, }, required: [], }, },