# ledger_info

## Overview

Retrieve current ledger information and chain metadata. This is the most fundamental Aptos REST API endpoint, returning the chain ID, current epoch, latest ledger version, block height, and node role. It serves as the starting point for transaction building, sync verification, and network health monitoring.

## Endpoint

`GET /v1`

## Request Parameters

This method accepts no parameters.

## Request Example

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

## Response Fields

- `chain_id` (`integer, required`): Network identifier: `1` = mainnet, `2` = testnet, other values for devnets
- `epoch` (`string, required`): Current epoch number; increments when the validator set changes
- `ledger_version` (`string, required`): Latest committed transaction version (global sequence number)
- `oldest_ledger_version` (`string, required`): Oldest version available on this node (pruned nodes start higher than 0)
- `ledger_timestamp` (`string, required`): Timestamp of the latest committed transaction in microseconds since Unix epoch
- `block_height` (`string, required`): Latest block height (number of blocks since genesis)
- `oldest_block_height` (`string, required`): Oldest block available on this node
- `node_role` (`string, required`): Node type: `full_node` or `validator`
- `git_hash` (`string, required`): Git commit hash of the node software

## Successful Response

```json
{
  "chain_id": 1,
  "epoch": "5000",
  "ledger_version": "500000000",
  "oldest_ledger_version": "0",
  "ledger_timestamp": "1700000000000000",
  "block_height": "150000000",
  "oldest_block_height": "0",
  "node_role": "full_node",
  "git_hash": "abc123..."
}
```

## Error Responses

### Error 1

- Description: Network identifier: `1` = mainnet, `2` = testnet, other values for devnets

### Error 2

- Description: Current epoch number; increments when the validator set changes

### Error 3

- Description: Latest committed transaction version (global sequence number)

### Error 4

- Description: Oldest version available on this node (pruned nodes start higher than 0)

### Error 5

- Description: Timestamp of the latest committed transaction in microseconds since Unix epoch

### Error 6

- Description: Latest block height (number of blocks since genesis)

### Error 7

- Description: Oldest block available on this node

### Error 8

- Description: Node type: `full_node` or `validator`

### Error 9

- Description: Git commit hash of the node software

## Code Examples

cURL
Python
TypeScript
Rust

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

```python
from aptos_sdk.client import RestClient

client = RestClient("https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1")
info = client.info()

print(f"Chain ID:       {info['chain_id']}")
print(f"Epoch:          {info['epoch']}")
print(f"Ledger version: {info['ledger_version']}")
print(f"Block height:   {info['block_height']}")

# Convert timestamp to human-readable
import datetime
ts_seconds = int(info['ledger_timestamp']) / 1_000_000
dt = datetime.datetime.fromtimestamp(ts_seconds, tz=datetime.timezone.utc)
print(f"Latest block:   {dt.isoformat()}")
```

```typescript
import { Aptos, AptosConfig } from "@aptos-labs/ts-sdk";

const config = new AptosConfig({
  fullnode: "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1"
});
const aptos = new Aptos(config);

const ledgerInfo = await aptos.getLedgerInfo();
console.log(`Chain ID:    ${ledgerInfo.chain_id}`);
console.log(`Epoch:       ${ledgerInfo.epoch}`);
console.log(`Version:     ${ledgerInfo.ledger_version}`);
console.log(`Block height: ${ledgerInfo.block_height}`);

// Check sync freshness
const ageMs = Date.now() - Number(ledgerInfo.ledger_timestamp) / 1000;
console.log(`Data age: ${(ageMs / 1000).toFixed(1)}s`);
```

```rust
use aptos_sdk::rest_client::Client;

let client = Client::new("https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1".parse()?);
let info = client.get_ledger_information().await?;

println!("Chain ID: {}", info.inner().chain_id);
println!("Epoch: {}", info.inner().epoch);
println!("Version: {}", info.inner().version);
println!("Block height: {}", info.inner().block_height);
```

## Use Cases

1. **Transaction Building**: Retrieve the current chain ID and ledger version, both required for constructing valid transactions. The chain ID prevents replay attacks across different networks (mainnet vs testnet).

2. **Sync Status Verification**: Monitor the node's sync progress by comparing `ledger_version` and `ledger_timestamp` against known network state. A `ledger_timestamp` more than 30 seconds behind real time indicates the node is not fully synced.

3. **Historical Query Planning**: Use `oldest_ledger_version` and `oldest_block_height` to determine the range of available historical data. Queries before these values will fail with 404 errors.

4. **Block Explorer Navigation**: Power block explorers with the current height and version, enabling users to navigate to the latest blocks and understand overall chain progress.

5. **Time-Based Queries**: Convert between wall-clock time and ledger versions using `ledger_timestamp`. This enables retrieving state "as of" a specific point in time by finding the corresponding version.

6. **Network Health Monitoring**: Track `epoch` changes to monitor validator set transitions. Track `ledger_timestamp` progression to detect chain stalls or slowdowns. Alert when the gap between real time and ledger time exceeds a threshold.

7. **Multi-Node Comparison**: Query multiple API endpoints and compare `ledger_version` values to verify they are in sync. A large version gap between providers may indicate network partitions or node issues.

## Response Fields Deep Dive

### chain\_id

The chain ID is a critical safety parameter:

- **Mainnet**: `1`
- **Testnet**: `2`
- **Devnet**: varies by deployment

Always validate `chain_id` matches your expected network before submitting transactions. Submitting a mainnet transaction to testnet (or vice versa) will fail due to chain ID mismatch in the signature.

### epoch

Epochs define validator set boundaries. When the epoch increments:

- The validator set may change (new validators join, existing ones leave)
- Staking rewards are distributed
- Governance proposals may take effect

Epoch duration on mainnet is approximately 2 hours. Track epoch transitions to monitor governance and staking events.

### ledger\_version vs block\_height

These are related but distinct concepts:

- `ledger_version` counts individual transactions (global sequence number)
- `block_height` counts blocks (each containing one or more transactions)
- A single block contains `last_version - first_version + 1` transactions

Use `ledger_version` for transaction-level operations and `block_height` for block-level operations.

### ledger\_timestamp

The timestamp is in **microseconds** since Unix epoch (not milliseconds or seconds). Common conversions:

- To seconds: divide by 1,000,000
- To milliseconds: divide by 1,000
- To JavaScript Date: `new Date(Number(timestamp) / 1000)`

## Best Practices

**Caching Strategy**: Ledger info changes every block (approximately every 4 seconds on mainnet). Cache this data for 2-5 seconds to minimize API calls while maintaining reasonable freshness.

**Chain ID Validation**: Always verify `chain_id` matches your expected network before building transactions. This single check prevents accidental cross-network submissions.

**Version Management**: When building transactions, fetch fresh ledger info to get the latest version. Stale version data can cause transaction expiration issues or references to pruned state.

**Historical Data Awareness**: Check `oldest_ledger_version` before attempting historical queries. Nodes prune old data, and querying beyond the oldest version returns errors.

**Timestamp Precision**: The `ledger_timestamp` is in microseconds since Unix epoch. Ensure your timestamp conversion handles this correctly -- a common bug is treating it as milliseconds.

**Health Check Integration**: Incorporate this endpoint into your application's health checks. If `ledger_timestamp` is more than 30 seconds behind, treat the API as degraded and consider failing over to an alternative endpoint.

## Performance Considerations

This endpoint is highly optimized and typically responds in 10-30ms. It queries metadata from the node's fast-access cache layer without touching the transaction database or blockchain state.

Response size is minimal (under 1KB), making it suitable for frequent polling. For applications requiring real-time updates, poll every 4-5 seconds (matching block time) rather than faster, which provides no additional freshness.

The `node_role` field indicates whether you are querying a validator or fullnode. Dwellir's API endpoints are fullnodes, which provide stable, scalable access with minimal lag behind validators (typically 1-2 seconds).

## Related Endpoints

- `/v1/-/healthy` - Quick health check endpoint (returns 200 if node is healthy)
- `/v1/blocks/by_height/{height}` - Fetch a specific block by height
- `/v1/transactions` - List recent transactions starting from the latest version
- `/v1/spec` - OpenAPI specification for all available endpoints