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. The response includes full execution results, events emitted, and gas consumption details.

Endpoint

GET /v1/transactions/by_hash/{txn_hash}

Code Examples

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

Use Cases

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

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

3. Block Explorer Links: Enable users to click transaction hashes in your UI and view complete transaction details, including payload, events, and gas consumption.

4. Debugging Failed Transactions: When transactions fail, retrieve the full transaction object to inspect vm_status and understand why execution failed (insufficient balance, abort codes, out of gas, etc.).

5. Event Processing: Extract emitted events from specific transactions to update application state, trigger notifications, or maintain off-chain indexes.

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

Understanding vm_status

The vm_status field contains the execution result. Common values:

When success is false, the vm_status provides the specific error. Move abort codes are module-specific -- check the module's source code to decode the error constant name.

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 can return 200 with type: "pending_transaction" while they are still in the mempool. Use wait_by_hash or poll this endpoint until the response changes to a committed transaction payload.

Caching: Transaction data is immutable once committed. Cache successfully retrieved transactions indefinitely to minimize API calls. Only pending transactions (404 responses) need re-fetching.

Sequence vs Hash: If you know the transaction version (from block data or event streams), use /transactions/by_version for faster lookups. Hash lookups use a secondary index and are slightly slower.

Error Interpretation: Always check both success and vm_status fields. A transaction can be committed (not 404) but fail at the application level (success: false). Failed transactions still consume gas.

Event Parsing: Events in the response follow the same structure as the events endpoints. Use the type field to filter for events relevant to your application.

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 in the transaction database.

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

For bulk transaction retrieval, use version-based queries or the transaction list endpoint with pagination instead of individual hash lookups, as they provide better database locality and throughput.

Related Endpoints

• /v1/transactions/by_version/{version} - Faster lookup when version is known
• /v1/transactions/wait_by_hash/{hash} - Block until transaction is confirmed
• /v1/transactions - Submit a new transaction
• /v1/transactions/simulate - Test a transaction before submitting
• /v1/accounts/{address}/transactions - List all transactions for an account