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",