transactions_by_version

Overview

Retrieve a transaction by its ledger version number. This is the fastest way to query transactions when you know the version, which is assigned sequentially to every transaction on the blockchain. Versions provide a total ordering of all state changes in Aptos.

Endpoint

GET /v1/transactions/by_version/{txn_version}

Request

Path Parameters

Name	Type	Required	Description
txn_version	string	Yes	Ledger version number (non-negative integer as string)

Query Parameters

None.

Response

Success Response (200)

Returns a complete transaction object:

{
  "version": "123456789",
  "hash": "0x...",
  "state_change_hash": "0x...",
  "event_root_hash": "0x...",
  "gas_used": "8",
  "success": true,
  "vm_status": "Executed successfully",
  "sender": "0x...",
  "sequence_number": "42",
  "max_gas_amount": "2000",
  "gas_unit_price": "100",
  "expiration_timestamp_secs": "1234567890",
  "payload": {...},
  "signature": {...},
  "events": [...],
  "timestamp": "1234567890"
}

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid version format (must be non-negative integer)
404	transaction_not_found	Version doesn't exist yet or is before oldest_ledger_version

Code Examples

curl -X GET https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions/by_version/123456789 \
  -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_version(123456789)
print(f"Hash: {txn['hash']}, Sender: {txn['sender']}")

TypeScript example:

const txn = await aptos.getTransactionByVersion({
  ledgerVersion: 123456789n
});
console.log(`Gas used: ${txn.gas_used}`);

Use Cases

Version-based transaction queries are essential for many blockchain operations:

1. Sequential Processing: Iterate through all transactions sequentially by incrementing version numbers, ensuring no transactions are missed during indexing or analysis.

2. Event Stream Processing: Process transactions in order from a known checkpoint version, maintaining consistent state reconstruction.

3. Block Processing: After retrieving a block with its version range (first_version to last_version), fetch individual transactions within that range.

4. Historical Analysis: Access transactions at specific points in blockchain history using version numbers as stable references.

5. State Snapshots: Reconstruct state at any historical version by replaying all transactions up to that version.

6. Performance Optimization: Version lookups are faster than hash lookups because versions are the primary index for transaction storage.

Best Practices

Version Range Awareness: Check /v1 (ledger_info) to get oldest_ledger_version and ledger_version to understand the available version range. Queries outside this range will fail.

Sequential Access Patterns: When processing many sequential transactions, version-based queries are significantly more efficient than hash-based queries due to better database locality.

Pagination: For bulk processing, use the /v1/transactions endpoint with pagination instead of individual version queries.

Version vs Hash: Use version queries when you have version numbers (from blocks, event streams, or sequential processing). Use hash queries when users provide transaction IDs.

Immutability: Transaction data at a specific version is immutable. Implement aggressive caching for historical versions (older than latest - 100) to minimize API load.

Error Handling: A 404 can mean the version is too new (not yet processed) or too old (pruned). Compare against ledger_info to distinguish these cases.

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.

Response sizes match other transaction queries (10KB-1MB depending on transaction complexity). However, the reduced query latency makes version-based access preferred for high-throughput indexing pipelines.

For sequential processing of large version ranges, consider using the transaction streaming API which provides better throughput than individual REST queries.

Version Number Properties

Transaction versions have important properties:

• Globally unique across the entire blockchain
• Monotonically increasing with no gaps
• Assigned sequentially in block order
• Starts at version 0 (genesis transaction)
• Each block contains a contiguous range of versions

These properties make versions ideal for streaming, checkpointing, and state machine replication use cases.