get_portfolio_balances
Retrieve token balances for specified wallet addresses or default env address across multiple blockchain networks. Supports native token inclusion for comprehensive portfolio tracking in DeFi Trading Agent MCP Server.
Instructions
Get token balances for wallet addresses (faster, no prices/metadata, uses USER_ADDRESS from env if addresses not provided)
Input 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 | |
| includeNativeTokens | No | Include native tokens like ETH (optional, default: false) | |
| 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'] |
Input Schema (JSON Schema)
{
"properties": {
"addresses": {
"description": "Array of address and networks pairs (max 3 addresses, max 20 networks each). Optional - uses USER_ADDRESS from env if not provided",
"items": {
"properties": {
"address": {
"description": "Wallet address",
"type": "string"
},
"networks": {
"description": "Network identifiers (e.g., 'eth-mainnet', 'base-mainnet')",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"address",
"networks"
],
"type": "object"
},
"type": "array"
},
"includeNativeTokens": {
"description": "Include native tokens like ETH (optional, default: false)",
"type": "boolean"
},
"networks": {
"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']",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [],
"type": "object"
}
Implementation Reference
- src/toolService.js:650-691 (handler)Main execution handler for the 'get_portfolio_balances' tool. Processes input parameters, handles defaulting to USER_ADDRESS, delegates to agService for data retrieval, and formats the response with summary.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:825-870 (schema)Input schema definition for the 'get_portfolio_balances' tool, specifying the expected parameters including addresses (array of objects with address and networks), networks array, and includeNativeTokens boolean.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: [], }, },
- src/index.js:1166-1168 (registration)Tool dispatcher registration in the switch statement, which calls the handler function toolService.getPortfolioBalances with the provided arguments.case TOOL_NAMES.GET_PORTFOLIO_BALANCES: result = await toolService.getPortfolioBalances(args); break;
- src/services/agService.js:280-309 (helper)Helper service method in agService that makes the actual API POST request to retrieve portfolio balances data from the backend.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/constants.js:40-40 (helper)Constant definition for the tool name 'get_portfolio_balances' used throughout the codebase.GET_PORTFOLIO_BALANCES: "get_portfolio_balances",