DeFi Trading Agent MCP Server

Instructions

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