transactions_by_hash

Overview

Retrieve a transaction by its unique hash. This is the primary method for looking up transactions when users provide transaction IDs, typically after submission or from block explorers.

Endpoint

GET /v1/transactions/by_hash/{txn_hash}

Request

Path Parameters

Name	Type	Required	Description
txn_hash	string	Yes	0x-prefixed transaction hash (64 hex characters)

Query Parameters

None.

Response

Success Response (200)

Returns a complete transaction object including execution results:

{
  "version": "123456789",
  "hash": "0x0985b017...",
  "state_change_hash": "0x...",
  "event_root_hash": "0x...",
  "gas_used": "8",
  "success": true,
  "vm_status": "Executed successfully",
  "sender": "0xabc...",
  "sequence_number": "42",
  "payload": {...},
  "events": [...],
  "timestamp": "1234567890"
}

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid hash format
404	transaction_not_found	Transaction doesn't exist or pending

Code Examples

curl -X GET https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions/by_hash/0x0985b0179db0c0971bb9bf331dff7fdae6dacf73cee48a1ec6be614f41d4d383 \
  -H "Accept: application/json"

Python example:

from aptos_sdk.client import RestClient

client = RestClient("https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1")
txn = client.transaction_by_hash("0x0985b017...")
print(f"Success: {txn['success']}, Gas: {txn['gas_used']}")

TypeScript example:

const txn = await aptos.getTransactionByHash({
  transactionHash: "0x0985b017..."
});
console.log(`Status: ${txn.vm_status}`);

Use Cases

Transaction hash lookups are fundamental to blockchain applications:

1. Transaction Confirmation: After submitting a transaction, poll by hash to check execution status and confirm success or failure.

2. Receipt Generation: Retrieve full transaction details including events, gas usage, and state changes to generate user-facing receipts.

3. Block Explorer Links: Enable users to click transaction hashes in your UI and view complete transaction details.

4. Debugging Failed Transactions: When transactions fail, retrieve the full transaction object to inspect vm_status and understand why execution failed.

5. Event Processing: Extract emitted events from specific transactions to update application state or trigger notifications.

6. Audit Logging: Store transaction hashes in your database, then retrieve full details on-demand for audit trails without storing complete transaction data.

Best Practices

Hash Format: Transaction hashes must be 0x-prefixed 64-character hex strings (32 bytes). Validate format before querying to avoid 400 errors.

Pending Transactions: Newly submitted transactions return 404 until they're executed and committed. Use /transactions/wait_by_hash for blocking behavior.

Caching: Transaction data is immutable once committed. Cache successfully retrieved transactions indefinitely to minimize API calls.

Sequence vs Hash: If you know the transaction version (sequence number in the global ledger), use /transactions/by_version for faster lookups.

Error Interpretation: Check both success and vm_status fields. A transaction can execute (success: false) but fail application-level checks.

Performance Considerations

Hash lookups use indexed storage and typically complete in 50-100ms. This is slightly slower than version-based lookups because hash indexes are secondary indexes.

Transaction objects can be large (10KB-1MB) depending on payload size, number of events, and state changes. Complex smart contract interactions generate larger responses.

For bulk transaction retrieval, consider using version-based queries or the transaction list endpoint with pagination instead of individual hash lookups.