get_transaction_status

Check transaction status and details on the Aptos blockchain using a transaction hash to verify success and obtain comprehensive information.

Instructions

Get the status and details of a transaction by its hash. This is used for checking if a transaction was successful and getting detailed information about it. Returns comprehensive transaction information.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`transaction_hash`	Yes	Transaction hash to check, e.g., 0x1234567890abcdef...

Implementation Reference

src/tools/transaction/getTransactionStatus.ts:25-49 (handler)

Main handler function for get_transaction_status tool. Validates input args and delegates to performGetTransactionStatus, handling errors and formatting response.

export async function getTransactionStatusHandler(args: Record<string, any> | undefined) {
  if (!isGetTransactionStatusArgs(args)) {
    throw new Error("Invalid arguments for get_transaction_status");
  }

  const { transaction_hash } = args;

  try {
    const results = await performGetTransactionStatus(transaction_hash);
    return {
      content: [{ type: "text", text: results }],
      isError: false,
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Error getting transaction status: ${error instanceof Error ? error.message : String(error)}`,
        },
      ],
      isError: true,
    };
  }
}

src/tools/transaction/getTransactionStatus.ts:5-18 (schema)

Tool schema definition including name, description, and inputSchema for validating transaction_hash parameter.

export const GET_TRANSACTION_STATUS: Tool = {
  name: "get_transaction_status",
  description: "Get the status and details of a transaction by its hash. This is used for checking if a transaction was successful and getting detailed information about it. Returns comprehensive transaction information.",
  inputSchema: {
    type: "object",
    properties: {
      transaction_hash: {
        type: "string",
        description: "Transaction hash to check, e.g., 0x1234567890abcdef...",
      },
    },
    required: ["transaction_hash"],
  },
};

src/tools/transaction/getTransactionStatus.ts:56-168 (helper)

Core helper function that fetches transaction details using Aptos client, formats comprehensive status info including success, gas, payload, events, etc.

export async function performGetTransactionStatus(transactionHash: string): Promise<string> {
  try {
    const aptos = getAptosClient();
    
    // Get transaction details
    const transaction = await aptos.getTransactionByHash({ transactionHash });

    let result = `Transaction Status:
Hash: ${transaction.hash}`;

    // Check if this is a committed transaction (not pending)
    if (transaction.type !== 'pending_transaction') {
      result += `
Version: ${transaction.version}
Success: ${transaction.success ? '✅ Success' : '❌ Failed'}
Gas Used: ${transaction.gas_used}
VM Status: ${transaction.vm_status}`;
    } else {
      result += `
Status: ⏳ Pending`;
    }

    // Add additional information for committed transactions
    if (transaction.type !== 'pending_transaction') {
      // Add sender information if available
      if ('sender' in transaction) {
        result += `
Sender: ${formatAddress(transaction.sender)}`;
      }

      // Add sequence number if available
      if ('sequence_number' in transaction) {
        result += `
Sequence Number: ${transaction.sequence_number}`;
      }

      // Add max gas amount if available
      if ('max_gas_amount' in transaction) {
        result += `
Max Gas Amount: ${transaction.max_gas_amount}`;
      }

      // Add gas unit price if available
      if ('gas_unit_price' in transaction) {
        result += `
Gas Unit Price: ${transaction.gas_unit_price}`;
      }

      // Add timestamp if available
      if ('timestamp' in transaction) {
        const date = new Date(parseInt(transaction.timestamp) / 1000);
        result += `
Timestamp: ${date.toISOString()}`;
      }
    }

    // Add payload information if available (only for committed transactions)
    if (transaction.type !== 'pending_transaction' && 'payload' in transaction && transaction.payload) {
      result += `

Payload Information:
Type: ${transaction.payload.type}`;

      if (transaction.payload.type === 'entry_function_payload' && 'function' in transaction.payload) {
        result += `
Function: ${transaction.payload.function}`;

        if ('type_arguments' in transaction.payload && transaction.payload.type_arguments && transaction.payload.type_arguments.length > 0) {
          result += `
Type Arguments: ${transaction.payload.type_arguments.join(', ')}`;
        }

        if ('arguments' in transaction.payload && transaction.payload.arguments && transaction.payload.arguments.length > 0) {
          result += `
Arguments: ${transaction.payload.arguments.join(', ')}`;
        }
      }
    }

    // Add events information if available (only for committed transactions)
    if (transaction.type !== 'pending_transaction' && 'events' in transaction && transaction.events && transaction.events.length > 0) {
      result += `

Events (${transaction.events.length}):`;
      transaction.events.slice(0, 5).forEach((event, index) => {
        result += `
  ${index + 1}. Type: ${event.type}`;
        if (event.data) {
          result += `
     Data: ${JSON.stringify(event.data)}`;
        }
      });

      if (transaction.events.length > 5) {
        result += `
  ... and ${transaction.events.length - 5} more events`;
      }
    }

    return result;
  } catch (error) {
    console.error('Error getting transaction status:', error);
    
    if (error instanceof Error && error.message.includes('not found')) {
      return `Transaction Status:
Hash: ${transactionHash}
Status: ❌ Transaction not found
Note: Transaction may not exist or may not have been processed yet`;
    }
    
    throw new Error(`Failed to get transaction status: ${error instanceof Error ? error.message : String(error)}`);
  }
}

src/index.ts:138-141 (registration)

Tool registration in main server switch statement in index.ts, dispatching to getTransactionStatusHandler.

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

src/tools/transaction/getTransactionStatus.ts:175-182 (schema)

Runtime validation function for input arguments ensuring transaction_hash is a string.

export function isGetTransactionStatusArgs(args: unknown): args is { transaction_hash: string } {
  return (
    typeof args === "object" &&
    args !== null &&
    "transaction_hash" in args &&
    typeof (args as any).transaction_hash === "string"
  );
}

src/http-server.ts:116-117 (registration)
Tool registration in HTTP server switch statement.
```
case "get_transaction_status":
  return await getTransactionStatusHandler(args);
```

Aptos Blockchain MCP