Aptos Blockchain MCP

Instructions

Implementation Reference

• src/tools/transaction/getAccountTransactions.ts:30-54 (handler)

  The main handler function for the get_account_transactions tool. Validates arguments, calls the perform function, and formats the response or error.

  export async function getAccountTransactionsHandler(args: Record<string, any> | undefined) {
    if (!isGetAccountTransactionsArgs(args)) {
      throw new Error("Invalid arguments for get_account_transactions");
    }
  
    const { account_address, limit = 10 } = args;
  
    try {
      const results = await performGetAccountTransactions(account_address, limit);
      return {
        content: [{ type: "text", text: results }],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error getting account transactions: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/transaction/getAccountTransactions.ts:5-23 (schema)

  Input schema and metadata definition for the get_account_transactions tool.

  export const GET_ACCOUNT_TRANSACTIONS: Tool = {
    name: "get_account_transactions",
    description: "Get recent transactions for an Aptos account. This is used for viewing transaction history and activity for an account. Returns a list of recent transactions with details.",
    inputSchema: {
      type: "object",
      properties: {
        account_address: {
          type: "string",
          description: "Aptos account address, e.g., 0x1 or 0x742d35Cc6634C0532925a3b8D6Ac0C4db9c8b3",
        },
        limit: {
          type: "number",
          description: "Maximum number of transactions to return (optional, default: 10, max: 100)",
          default: 10,
        },
      },
      required: ["account_address"],
    },
  };

• src/tools/transaction/getAccountTransactions.ts:62-145 (helper)

  Core helper function that fetches transactions from Aptos client, formats them into a detailed string response, handles errors.

  export async function performGetAccountTransactions(accountAddress: string, limit: number = 10): Promise<string> {
    try {
      const aptos = getAptosClient();
      
      // Ensure limit is within reasonable bounds
      const safeLimit = Math.min(Math.max(limit, 1), 100);
      
      // Get account transactions
      const transactions = await aptos.getAccountTransactions({
        accountAddress,
        options: {
          limit: safeLimit,
        },
      });
  
      if (transactions.length === 0) {
        return `Account Transactions:
  Account: ${formatAddress(accountAddress)}
  Transactions: No transactions found
  
  Note: Account may not have any transactions yet or may not exist`;
      }
  
      let result = `Account Transactions:
  Account: ${formatAddress(accountAddress)}
  Total Retrieved: ${transactions.length}
  
  Recent Transactions:`;
  
      transactions.forEach((tx, index) => {
        result += `
  
  ${index + 1}. Transaction Hash: ${tx.hash}`;
  
        // Only show detailed info for committed transactions
        if (tx.type !== 'pending_transaction') {
          result += `
     Version: ${tx.version}
     Success: ${tx.success ? '✅' : '❌'}
     Gas Used: ${tx.gas_used}`;
  
          // Add timestamp if available
          if ('timestamp' in tx) {
            const date = new Date(parseInt(tx.timestamp) / 1000);
            result += `
     Time: ${date.toISOString()}`;
          }
  
          // Add sequence number if available
          if ('sequence_number' in tx) {
            result += `
     Sequence: ${tx.sequence_number}`;
          }
  
          // Add payload function if available
          if ('payload' in tx && tx.payload && tx.payload.type === 'entry_function_payload' && 'function' in tx.payload) {
            result += `
     Function: ${tx.payload.function}`;
          }
        } else {
          result += `
     Status: ⏳ Pending`;
        }
      });
  
      result += `
  
  Full Account Address: ${accountAddress}`;
  
      return result;
    } catch (error) {
      console.error('Error getting account transactions:', error);
      
      if (error instanceof Error && error.message.includes('not found')) {
        return `Account Transactions:
  Account: ${formatAddress(accountAddress)}
  Status: Account does not exist or has no transactions
  
  Note: Account needs to be initialized with at least one transaction`;
      }
      
      throw new Error(`Failed to get account transactions: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/tools/transaction/getAccountTransactions.ts:152-163 (helper)

  Type guard function to validate input arguments for the tool.

  export function isGetAccountTransactionsArgs(args: unknown): args is { 
    account_address: string; 
    limit?: number 
  } {
    return (
      typeof args === "object" &&
      args !== null &&
      "account_address" in args &&
      typeof (args as any).account_address === "string" &&
      (!(args as any).limit || typeof (args as any).limit === "number")
    );
  }

• src/index.ts:140-141 (registration)

  Tool handler registration in the main MCP server's switch statement for tool calls.

  case "get_account_transactions":
    return await getAccountTransactionsHandler(args);