# 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:

```json
{
  "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

```bash
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.