get_portfolio_tokens
Retrieve token balances, prices, and metadata for wallet addresses across multiple networks. Supports custom addresses or uses USER_ADDRESS from environment; optional native token inclusion enhances portfolio insights.
Instructions
Get tokens with balances, prices, and metadata for wallet addresses (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'] | |
| withMetadata | No | Include token metadata (optional, default: true) | |
| withPrices | No | Include token prices (optional, default: true) |
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"
},
"withMetadata": {
"description": "Include token metadata (optional, default: true)",
"type": "boolean"
},
"withPrices": {
"description": "Include token prices (optional, default: true)",
"type": "boolean"
}
},
"required": [],
"type": "object"
}
Implementation Reference
- src/toolService.js:598-648 (handler)Main MCP tool handler in ToolService class. Processes input parameters, defaults to USER_ADDRESS if no addresses provided, calls AgService.getPortfolioTokens, and formats the response.async getPortfolioTokens(params) { const { addresses, withMetadata, withPrices, 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.getPortfolioTokens(targetAddresses, { withMetadata, withPrices, includeNativeTokens, }); return { message: "Portfolio tokens retrieved successfully", data: result, summary: `Retrieved tokens for ${ targetAddresses.length } address(es) across ${targetAddresses.reduce( (total, addr) => total + addr.networks.length, 0 )} network(s)`, addressUsed: targetAddresses[0].address, options: { withMetadata: withMetadata !== false, withPrices: withPrices !== false, includeNativeTokens: includeNativeTokens || false, }, }; }
- src/services/agService.js:247-278 (handler)Core implementation in AgService class. Makes POST request to external Aggregator API /api/portfolio/tokens endpoint with addresses and options.async getPortfolioTokens(addresses, options = {}) { try { const requestBody = { addresses, withMetadata: options.withMetadata, withPrices: options.withPrices, includeNativeTokens: options.includeNativeTokens }; const response = await fetch(`${this.baseUrl}/api/portfolio/tokens`, { 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 tokens request failed'); } return data.data; } catch (error) { throw new Error(`Failed to get portfolio tokens: ${error.message}`); } }
- src/index.js:770-822 (schema)Tool schema definition in the ListToolsRequestHandler, including input schema with properties for addresses, networks, metadata, prices, and native tokens.name: TOOL_NAMES.GET_PORTFOLIO_TOKENS, description: "Get tokens with balances, prices, and metadata for wallet addresses (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']", }, withMetadata: { type: "boolean", description: "Include token metadata (optional, default: true)", }, withPrices: { type: "boolean", description: "Include token prices (optional, default: true)", }, includeNativeTokens: { type: "boolean", description: "Include native tokens like ETH (optional, default: false)", }, }, required: [], },
- src/index.js:1162-1164 (registration)Tool registration in the CallToolRequestHandler switch statement, dispatching to toolService.getPortfolioTokens.case TOOL_NAMES.GET_PORTFOLIO_TOKENS: result = await toolService.getPortfolioTokens(args); break;
- src/constants.js:39-39 (helper)Constant definition for the tool name used in registration and dispatching.GET_PORTFOLIO_TOKENS: "get_portfolio_tokens",