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
`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: [],
  },
},

DeFi Trading Agent MCP Server