blocks_by_version

Overview

Fetch the block that contains a given ledger version. This endpoint is useful when you have a transaction version and need to understand its block context, including block metadata, timestamp, and related transactions.

Endpoint

GET /v1/blocks/by_version/{version}

Request

Path Parameters

Name	Type	Required	Description
version	string	Yes	Ledger version (transaction version)

Query Parameters

Name	Type	Required	Description
with_transactions	boolean	No	Include full transaction data in response

Response

Success Response (200)

Returns a block object containing:

{
  "block_height": "1000000",
  "block_hash": "0x...",
  "block_timestamp": "1234567890",
  "first_version": "123456700",
  "last_version": "123456789",
  "transactions": [...]
}

When with_transactions=true, the transactions array contains complete transaction objects. Without this parameter, only block metadata is returned.

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid version format
404	version_not_found	Version doesn't exist yet
500	internal_error	Server error

Code Examples

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

Use Cases

This endpoint serves several important purposes in blockchain development:

1. Transaction Context Discovery: Given a specific transaction version, retrieve its block context to understand when and how it was processed, including block timestamp and proposer information.

2. Block Explorer Implementation: Build block explorers that allow users to navigate from individual transactions to their containing blocks, showing all transactions processed together.

3. Temporal Analysis: Analyze transaction ordering and timing within blocks to understand MEV opportunities, transaction dependencies, or validator behavior.

4. Event Correlation: When investigating events across multiple transactions, use this endpoint to group related transactions that were executed in the same block.

5. Audit Trail Construction: Create comprehensive audit trails by linking transactions to their block context, providing immutable timestamps and ordering guarantees.

6. State Snapshot Coordination: Coordinate state snapshots across multiple accounts or resources by identifying block boundaries that represent consistent global state.

Best Practices

Version vs Height: This endpoint uses transaction version (ledger version), not block height. Transaction versions are sequential across all transactions, while block heights increment per block. Use blocks/by_height if you have a block height instead.

Pagination Strategy: When with_transactions=true, large blocks can return megabytes of data. If you need to process many blocks, consider fetching metadata first, then selectively fetching transaction details only when needed.

Caching: Block data is immutable once finalized. Implement aggressive caching for historical blocks (older than 100 versions from chain head) to minimize API load.

Version Boundaries: Each block contains a range of versions from first_version to last_version. To process all transactions in a block, iterate through this range using individual transaction queries if needed.

Performance Considerations

Queries without with_transactions are fast and lightweight (typically under 50ms). Including full transaction data can increase response time to 200-500ms for blocks with many transactions, depending on transaction complexity and payload sizes. The response size can range from a few KB (metadata only) to several MB (large blocks with full transaction data).

For high-throughput applications processing many blocks sequentially, consider using the transaction streaming API instead of polling individual blocks.