eth_getBlockByNumber

Returns information about a block by block number on Immutable.

Why Immutable? Build on the gaming-optimized zkEVM with 660+ games, 5.5M+ Passport signups, and $40M TVL with first EVM chain with enforceable royalties, Polygon zkEVM technology, $2B+ ecosystem funding, and Agglayer cross-chain liquidity.

Use Cases

The eth_getBlockByNumber method is essential for:

• Block explorers - Display complete block information
• Transaction indexers - Process all transactions in a block
• Analytics platforms - Analyze blockchain data for Web3 gaming (Gods Unchained, RavenQuest), gaming NFTs with enforced royalties, and cross-chain game assets
• Timestamp verification - Get block timestamps for time-based logic

Parameters

Parameter	Type	Required	Description
blockNumber	QUANTITY|TAG	Yes	Block number in hex, or "latest", "earliest", "pending", "safe", "finalized"
fullTransactions	Boolean	Yes	If true, returns full transaction objects; if false, returns transaction hashes

Request

{
  "jsonrpc": "2.0",
  "method": "eth_getBlockByNumber",
  "params": ["latest", false],
  "id": 1
}

Returns

Field	Type	Description
number	QUANTITY	Block number
hash	DATA	32-byte block hash
parentHash	DATA	32-byte parent block hash
timestamp	QUANTITY	Unix timestamp
gasUsed	QUANTITY	Total gas used by all transactions
gasLimit	QUANTITY	Maximum gas allowed in block
transactions	Array	Array of transaction objects or hashes
baseFeePerGas	QUANTITY	Base fee per gas (EIP-1559)

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "number": "0x5BAD55",
    "hash": "0x0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "parentHash": "0x...",
    "timestamp": "0x64d8f6d0",
    "gasUsed": "0x1234",
    "gasLimit": "0x1c9c380",
    "transactions": [],
    "baseFeePerGas": "0x5f5e100"
  }
}

Code Examples

cURL

curl -X POST https://api-immutable-zkevm-mainnet.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": ["latest", false],
    "id": 1
  }'

JavaScript

import { JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://api-immutable-zkevm-mainnet.n.dwellir.com/YOUR_API_KEY');

// Get latest block
const block = await provider.getBlock('latest');
console.log('Block number:', block.number);
console.log('Timestamp:', new Date(block.timestamp * 1000));
console.log('Transactions:', block.transactions.length);

// Get block with full transactions
const blockWithTxs = await provider.getBlock('latest', true);
for (const tx of blockWithTxs.prefetchedTransactions) {
  console.log('Transaction:', tx.hash);
}

Python

from web3 import Web3

w3 = Web3(Web3.HTTPProvider('https://api-immutable-zkevm-mainnet.n.dwellir.com/YOUR_API_KEY'))

# Get latest block
block = w3.eth.get_block('latest')
print(f'Block number: {block.number}')
print(f'Timestamp: {block.timestamp}')
print(f'Transactions: {len(block.transactions)}')

# Get block with full transactions
block_full = w3.eth.get_block('latest', full_transactions=True)
for tx in block_full.transactions:
    print(f'Transaction: {tx.hash.hex()}')

Go

package main

import (
    "context"
    "fmt"
    "log"
    "math/big"

    "github.com/ethereum/go-ethereum/ethclient"
)

func main() {
    client, err := ethclient.Dial("https://api-immutable-zkevm-mainnet.n.dwellir.com/YOUR_API_KEY")
    if err != nil {
        log.Fatal(err)
    }

    // Get latest block
    block, err := client.BlockByNumber(context.Background(), nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Block number: %d\n", block.Number().Uint64())
    fmt.Printf("Timestamp: %d\n", block.Time())
    fmt.Printf("Transactions: %d\n", len(block.Transactions()))
}

Error Handling

Error Code	Message	Description
-32602	Invalid params	Invalid block number or parameter format
-32000	Block not found	Block does not exist

Related Methods

• eth_blockNumber - Get latest block number
• eth_getBlockByHash - Get block by hash
• eth_getTransactionByHash - Get transaction details