transactions_by_version

Overview

Retrieve a transaction by its ledger version number. This is the fastest transaction query method because versions are the primary index for transaction storage. Versions are assigned sequentially to every transaction on the blockchain, providing a total ordering of all state changes in Aptos.

Endpoint

GET /v1/transactions/by_version/{txn_version}

Code Examples

Bash

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

Version Number Properties

Transaction versions have important properties that make them ideal for indexing and state management:

Property	Description
Globally unique	Each version appears exactly once across the entire blockchain
Monotonically increasing	Versions always increase; there are no decreases or resets
No gaps	Every integer from 0 to the current version has a corresponding transaction
Sequential within blocks	Each block contains a contiguous range of versions
Starts at 0	The genesis transaction has version 0
Deterministic ordering	Versions define the canonical order of all state changes

These properties make versions ideal for checkpointing, streaming, and state machine replication. You can always resume processing from any version without missing transactions.

Use Cases

Sequential Processing: Iterate through all transactions by incrementing version numbers, ensuring complete coverage with no missed transactions. This is the foundation of most indexing pipelines.
Block Transaction Retrieval: After getting a block with its version range (first_version to last_version), fetch individual transactions within that range for detailed processing.
Event Source Lookup: When an event references a version number, use this endpoint to retrieve the full transaction that emitted the event, including payload, sender, and other events.
Historical Analysis: Access transactions at specific points in blockchain history using version numbers as stable, permanent references.
State Reconstruction: Replay transactions in version order to reconstruct the state of any account or module at any historical point.
Checkpoint Recovery: After a processing interruption, resume from the last processed version number without risk of duplicate or missed transactions.

Best Practices

Version Range Awareness: Check GET /v1 (ledger info) to get oldest_ledger_version and ledger_version before querying. Versions outside this range return 404 errors.

Version vs Hash: Use version queries when you have version numbers (from blocks, events, or sequential processing). Use hash queries when users provide transaction IDs. Version queries are approximately 30-50% faster.

Sequential Access Patterns: When processing many sequential transactions, version-based queries provide significantly better database locality than hash-based queries, resulting in faster response times.

Bulk Processing: For processing large version ranges, use the GET /v1/transactions?start={version}&limit=100 pagination endpoint instead of individual version queries. Fetching 100 transactions in one call is faster than 100 individual requests.

Immutability and Caching: Transaction data at a specific version never changes. Cache historical transactions (older than the latest few hundred versions) indefinitely to minimize API load. Only very recent versions might be affected by reorgs (extremely rare on Aptos).

404 Disambiguation: A 404 can mean the version is too new (not yet processed) or too old (pruned). Compare the requested version against oldest_ledger_version and ledger_version from ledger info to determine the cause.

System Transaction Handling: Some versions correspond to system transactions (block_metadata, state_checkpoint) rather than user transactions. These have no sender or signature fields. Handle both types in your processing logic.

Performance Considerations

Version-based lookups are the fastest transaction query method, typically completing in 30-80ms. They use the primary index on transaction storage, providing optimal I/O patterns and minimal database overhead.

Response sizes match other transaction queries (2KB-1MB depending on complexity). The reduced query latency compared to hash lookups makes version-based access the preferred method for high-throughput indexing pipelines.

For sequential processing of large version ranges, the transaction streaming API (gRPC) provides substantially better throughput than individual REST queries. However, for spot-checking specific versions or low-volume access, the REST endpoint is simpler to integrate.

Performance comparison of query methods:

Method	Typical Latency	Index Type
By version	30-80ms	Primary index
By hash	50-100ms	Secondary index
List (paginated)	100-200ms per 100 txns	Sequential scan

/v1/transactions/by_hash/{hash} - Look up by hash when version is not known
/v1/transactions - List transactions with pagination for bulk retrieval
/v1/blocks/by_version/{version} - Get the block containing this version
/v1/blocks/by_height/{height} - Get block by height (includes version range)
/v1 - Get current and oldest available versions

On this page