ledger_info

Endpoint#

GET /v1

Response#

{
  "chain_id": 1,
  "epoch": "string",
  "ledger_version": "string",
  "oldest_ledger_version": "string",
  "ledger_timestamp": "string",
  "block_height": "string",
  "oldest_block_height": "string",
  "node_role": "fullnode|validator|..."
}

Code Examples#

curl -X GET https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1 \
  -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")
ledger_info = client.info()
print(f"Chain ID: {ledger_info['chain_id']}")
print(f"Latest version: {ledger_info['ledger_version']}")
print(f"Block height: {ledger_info['block_height']}")

TypeScript example:

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(`Epoch: ${ledgerInfo.epoch}, Version: ${ledgerInfo.ledger_version}`);

Use Cases#

This endpoint serves as the foundation for many blockchain operations:

Transaction Building: Retrieve the current ledger version and chain ID, both required for constructing valid transactions. The chain ID prevents replay attacks across different networks.
Sync Status Verification: Monitor the node's sync progress by comparing ledger_version against known network heights. Essential for ensuring your node or API provider is fully synced before executing critical operations.
Historical Query Planning: Use oldest_ledger_version and oldest_block_height to determine the available historical data range. Queries before these values will fail.
Block Explorer Navigation: Power block explorers with current height and version information, enabling users to navigate to the latest blocks and transactions.
Time-Based Queries: Convert between block times and versions using ledger_timestamp. Useful for retrieving state at specific historical moments.
Network Health Monitoring: Track epoch changes and ledger_timestamp progression to monitor network health and validator set transitions.

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 the chain_id matches your expected network (1 for mainnet, 2 for testnet). This prevents accidental cross-network transaction submissions.

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

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. Convert appropriately for your application's time handling.

Performance Considerations#

This endpoint is highly optimized and typically responds in 20-50ms. 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. However, for applications requiring real-time updates, consider polling every 5-10 seconds rather than every block to balance freshness with API efficiency.

The node_role field indicates whether you're querying a validator or fullnode. Validators have the most up-to-date data but are rarely exposed publicly. Fullnodes (like Dwellir's API) lag by a few seconds but provide stable, scalable access.

/v1/-/healthy - Quick health check without detailed info
/v1/blocks/by_height/{height} - Fetch specific block data
/v1/transactions - Query recent transactions