DeFi Trading Agent MCP Server

Instructions

Implementation Reference

• src/toolService.js:693-746 (handler)

  Main handler function for get_portfolio_transactions tool. Processes input parameters, handles default user address and networks, validates BETA limitations, calls AgService, and returns formatted response with pagination info.
  async getPortfolioTransactions(params) { const { addresses, before, after, limit, 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 BETA supported 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" ); } if (targetAddresses.length !== 1) { throw new Error( "Transactions API currently supports only 1 address (BETA limitation)" ); } const result = await this.agg.getPortfolioTransactions(targetAddresses, { before, after, limit, }); return { message: "Portfolio transactions retrieved successfully", data: result, summary: `Retrieved ${ result.transactions?.length || 0 } transactions for address ${targetAddresses[0].address}`, addressUsed: targetAddresses[0].address, pagination: { limit: limit || 25, before: result.before, after: result.after, totalCount: result.totalCount, }, beta: { limitations: "Currently supports 1 address and max 2 networks (eth-mainnet, base-mainnet)", note: "This endpoint is in BETA with limited functionality", }, }; }
• src/index.js:872-931 (schema)

  MCP tool schema definition including inputSchema with validation for addresses, networks (BETA limits), pagination parameters. Part of the tools list returned by listTools.
  name: TOOL_NAMES.GET_PORTFOLIO_TRANSACTIONS, description: "Get transaction history for a wallet address (BETA: 1 address, ETH/BASE only, uses USER_ADDRESS from env if addresses not provided)", inputSchema: { type: "object", properties: { addresses: { type: "array", description: "Array with single address and networks (BETA limitation: 1 address, max 2 networks). 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", enum: ["eth-mainnet", "base-mainnet"], }, description: "Network identifiers (BETA: only eth-mainnet and base-mainnet supported)", }, }, required: ["address", "networks"], }, maxItems: 1, }, networks: { type: "array", items: { type: "string", enum: ["eth-mainnet", "base-mainnet"], }, description: "Network identifiers to use with USER_ADDRESS (BETA: only eth-mainnet and base-mainnet supported). Only used when addresses not provided. Defaults to ['eth-mainnet', 'base-mainnet']", }, before: { type: "string", description: "Cursor for pagination - get results before this cursor (optional)", }, after: { type: "string", description: "Cursor for pagination - get results after this cursor (optional)", }, limit: { type: "integer", description: "Number of transactions to return (optional, default: 25, max: 50)", minimum: 1, maximum: 50, }, }, required: [], },
• src/index.js:1170-1172 (registration)

  Registration/dispatch handler in the main switch statement that routes calls to get_portfolio_transactions to the toolService method.
  case TOOL_NAMES.GET_PORTFOLIO_TRANSACTIONS: result = await toolService.getPortfolioTransactions(args); break;
• src/services/agService.js:311-349 (helper)

  Helper function in AgService that makes the actual API POST request to the aggregator's /api/portfolio/transactions endpoint.
  async getPortfolioTransactions(addresses, options = {}) { try { const requestBody = { addresses, before: options.before, after: options.after, limit: options.limit }; // Remove undefined values Object.keys(requestBody).forEach(key => { if (requestBody[key] === undefined) { delete requestBody[key]; } }); const response = await fetch(`${this.baseUrl}/api/portfolio/transactions`, { 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 transactions request failed'); } return data.data; } catch (error) { throw new Error(`Failed to get portfolio transactions: ${error.message}`); } }
• src/constants.js:41-41 (helper)

  Constant definition mapping the tool name constant to the string 'get_portfolio_transactions' used throughout the codebase.
  GET_PORTFOLIO_TRANSACTIONS: "get_portfolio_transactions",