get-transactions

Instructions

Implementation Reference

• src/server.ts:187-224 (handler)

  Handler for the 'get-transactions' tool: validates input with TransactionHistorySchema, calls etherscanService.getTransactionHistory, formats transactions into a readable text response.

  if (name === "get-transactions") {
    try {
      const { address, limit } = TransactionHistorySchema.parse(args);
      const transactions = await etherscanService.getTransactionHistory(
        address,
        limit
      );
      const formattedTransactions = transactions
        .map((tx) => {
          const date = new Date(tx.timestamp * 1000).toLocaleString();
          return (
            `Block ${tx.blockNumber} (${date}):\n` +
            `Hash: ${tx.hash}\n` +
            `From: ${tx.from}\n` +
            `To: ${tx.to}\n` +
            `Value: ${tx.value} ETH\n` +
            `---`
          );
        })
        .join("\n");
  
      const response =
        transactions.length > 0
          ? `Recent transactions for ${address}:\n\n${formattedTransactions}`
          : `No transactions found for ${address}`;
  
      return {
        content: [{ type: "text", text: response }],
      };
    } catch (error) {
      if (error instanceof z.ZodError) {
        throw new Error(
          `Invalid input: ${error.errors.map((e) => e.message).join(", ")}`
        );
      }
      throw error;
    }
  }

• src/server.ts:42-47 (schema)

  Zod schema for validating input parameters (address and optional limit) for the get-transactions tool.

  const TransactionHistorySchema = z.object({
    address: z
      .string()
      .regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address format"),
    limit: z.number().min(1).max(100).optional(),
  });

• src/server.ts:81-101 (registration)

  Tool registration in listTools response, defining name, description, and input schema.

  {
    name: "get-transactions",
    description: "Get recent transactions for an Ethereum address",
    inputSchema: {
      type: "object",
      properties: {
        address: {
          type: "string",
          description: "Ethereum address (0x format)",
          pattern: "^0x[a-fA-F0-9]{40}$",
        },
        limit: {
          type: "number",
          description: "Number of transactions to return (max 100)",
          minimum: 1,
          maximum: 100,
        },
      },
      required: ["address"],
    },
  },

• src/services/etherscanService.ts:64-95 (helper)

  EtherscanService.getTransactionHistory: fetches transaction list from Etherscan API via fetch, validates address, formats into Transaction interface objects.

  async getTransactionHistory(address: string, limit: number = 10): Promise<Transaction[]> {
    try {
      // Validate the address
      const validAddress = ethers.getAddress(address);
      
      // Get transactions directly from Etherscan API
      const result = await fetch(
        `https://api.etherscan.io/api?module=account&action=txlist&address=${validAddress}&startblock=0&endblock=99999999&page=1&offset=${limit}&sort=desc&apikey=${this.provider.apiKey}`
      );
      
      const data = await result.json();
      
      if (data.status !== "1" || !data.result) {
        throw new Error(data.message || "Failed to fetch transactions");
      }
  
      // Format the results
      return data.result.slice(0, limit).map((tx: any) => ({
        hash: tx.hash,
        from: tx.from,
        to: tx.to || 'Contract Creation',
        value: ethers.formatEther(tx.value),
        timestamp: parseInt(tx.timeStamp) || 0,
        blockNumber: parseInt(tx.blockNumber) || 0
      }));
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to get transaction history: ${error.message}`);
      }
      throw error;
    }
  }

• src/services/etherscanService.ts:3-10 (helper)

  TypeScript interface defining the structure of a Transaction object returned by getTransactionHistory.

  export interface Transaction {
    hash: string;
    from: string;
    to: string;
    value: string;
    timestamp: number;
    blockNumber: number;
  }