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

Code Examples

Bash

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

Use Cases

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).
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.
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.
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.
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.
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.
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).

/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

On this page