For AI agents: a documentation index is available at /llms.txt. Markdown versions of pages are available by appending .md to any documentation URL.
Skip to main content

Block methods

These methods query blocks and their contents, including block details, transaction counts, receipts, and uncles.

eth_getBlockByHash​

Returns information about the block matching the specified block hash.

Parameters​

  • hash: string - 32-byte hash of a block.

  • verbose: boolean - If true, returns the full transaction objects; if false, returns the transaction hashes.

Returns​

  • Block object, or null when there is no block.

    • number: quantity, integer - Block number. null when block is pending.

    • hash: data, 32 bytes - Hash of the block. null when block is pending.

    • parentHash: data, 32 bytes - Hash of the parent block.

    • nonce: data, 8 bytes - Hash of the generated proof of work. null when block is pending.

    • sha3Uncles: data, 32 bytes - SHA3 of the uncle's data in the block.

    • logsBloom: data, 256 bytes - Bloom filter for the block logs. null when block is pending.

    • transactionsRoot: data, 32 bytes - Root of the transaction trie for the block.

    • stateRoot: data, 32 bytes - Root of the final state trie for the block.

    • receiptsRoot: data, 32 bytes - Root of the receipts trie for the block.

    • miner: data, 20 bytes - Address to pay mining rewards to.

    • difficulty: quantity, integer - Difficulty for this block.

    • totalDifficulty: quantity, integer - Total difficulty of the chain until this block. This field is only returned for pre-merge (Proof of Work) blocks. This value will always be 0 for an uncle block.

    • extraData: data - Extra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option. Stores extra data when used with IBFT.

    • size: quantity, integer - Size of block in bytes.

    • gasLimit: quantity - Maximum gas allowed in this block.

    • gasUsed: quantity - Total gas used by all transactions in this block.

    • timestamp: quantity - Hex-encoded Unix timestamp (in seconds) for block assembly.

    • transactions: array - Array of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.

      • accessList: array - (Optional) List of addresses and storage keys the transaction plans to access. Used in ACCESS_LIST transactions and may be used in EIP1559 transactions.

      • blockHash: data, 32 bytes - Hash of the block containing this transaction. null when transaction is pending.

      • blockNumber: quantity - Block number of the block containing this transaction. null when transaction is pending.

      • blockTimestamp: quantity - Hex-encoded Unix timestamp (in seconds) of the block containing this transaction. null when transaction is pending.

      • chainId: quantity - Chain ID.

      • from: data, 20 bytes - Address of the sender.

      • gas: quantity - Gas provided by the sender.

      • gasPrice: quantity - (Optional) Gas price, in Wei, provided by the sender. Used only in non-EIP1559 transactions.

      • maxPriorityFeePerGas: quantity, integer - (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in EIP1559 transactions.

      • maxFeePerGas: quantity, integer - (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in EIP1559 transactions.

      • hash: data, 32 bytes - Hash of the transaction.

      • input: data - Data sent with the transaction to create or invoke a contract.

      • nonce: quantity - Number of transactions made by the sender before this one.

      • to: data, 20 bytes - Address of the receiver. null if a contract creation transaction.

      • transactionIndex: quantity, integer - Index position of the transaction in the block. null when transaction is pending.

      • transactionType: string - Transaction type.

      • value: quantity - Value transferred, in Wei.

      • v: quantity - ECDSA Recovery ID.

      • r: data, 32 bytes - ECDSA signature r.

      • s: data, 32 bytes - ECDSA signature s.

    • uncles: array - Array of uncle hashes.

    • baseFeePerGas: quantity - The block's base fee per gas. This field is empty for blocks created before EIP-1559.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByHash",
    "params": [
      "0xd5f1812548be429cbdc6376b29611fc49e06f1359758c4ceaaa3b393e2239f9c",
      false
    ],
    "id": 53
  }'

eth_getBlockByNumber​

Returns information about the block matching the specified block number.

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

  • verbose: boolean - If true, returns the full transaction objects; if false, returns only the hashes of the transactions.

Returns​

  • Block object, or null when there is no block.

    • number: quantity, integer - Block number. null when block is pending.

    • hash: data, 32 bytes - Hash of the block. null when block is pending.

    • parentHash: data, 32 bytes - Hash of the parent block.

    • nonce: data, 8 bytes - Hash of the generated proof of work. null when block is pending.

    • sha3Uncles: data, 32 bytes - SHA3 of the uncle's data in the block.

    • logsBloom: data, 256 bytes - Bloom filter for the block logs. null when block is pending.

    • transactionsRoot: data, 32 bytes - Root of the transaction trie for the block.

    • stateRoot: data, 32 bytes - Root of the final state trie for the block.

    • receiptsRoot: data, 32 bytes - Root of the receipts trie for the block.

    • miner: data, 20 bytes - Address to pay mining rewards to.

    • difficulty: quantity, integer - Difficulty for this block.

    • totalDifficulty: quantity, integer - Total difficulty of the chain until this block. This field is only returned for pre-merge (Proof of Work) blocks. This value will always be 0 for an uncle block.

    • extraData: data - Extra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option. Stores extra data when used with IBFT.

    • size: quantity, integer - Size of block in bytes.

    • gasLimit: quantity - Maximum gas allowed in this block.

    • gasUsed: quantity - Total gas used by all transactions in this block.

    • timestamp: quantity - Hex-encoded Unix timestamp (in seconds) for block assembly.

    • transactions: array - Array of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.

      • accessList: array - (Optional) List of addresses and storage keys the transaction plans to access. Used in ACCESS_LIST transactions and may be used in EIP1559 transactions.

      • blockHash: data, 32 bytes - Hash of the block containing this transaction. null when transaction is pending.

      • blockNumber: quantity - Block number of the block containing this transaction. null when transaction is pending.

      • blockTimestamp: quantity - Hex-encoded Unix timestamp (in seconds) of the block containing this transaction. null when transaction is pending.

      • chainId: quantity - Chain ID.

      • from: data, 20 bytes - Address of the sender.

      • gas: quantity - Gas provided by the sender.

      • gasPrice: quantity - (Optional) Gas price, in Wei, provided by the sender. Used only in non-EIP1559 transactions.

      • maxPriorityFeePerGas: quantity, integer - (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in EIP1559 transactions.

      • maxFeePerGas: quantity, integer - (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in EIP1559 transactions.

      • hash: data, 32 bytes - Hash of the transaction.

      • input: data - Data sent with the transaction to create or invoke a contract.

      • nonce: quantity - Number of transactions made by the sender before this one.

      • to: data, 20 bytes - Address of the receiver. null if a contract creation transaction.

      • transactionIndex: quantity, integer - Index position of the transaction in the block. null when transaction is pending.

      • transactionType: string - Transaction type.

      • value: quantity - Value transferred, in Wei.

      • v: quantity - ECDSA Recovery ID.

      • r: data, 32 bytes - ECDSA signature r.

      • s: data, 32 bytes - ECDSA signature s.

    • uncles: array - Array of uncle hashes.

    • baseFeePerGas: quantity - The block's base fee per gas. This field is empty for blocks created before EIP-1559.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params": [
      "0x68B3",
      true
    ],
    "id": 1
  }'

eth_getBlockReceipts​

Returns all transaction receipts for a given block. Transaction receipts provide a way to track the success or failure of a transaction (1 if successful and 0 if failed), as well as the amount of gas used and any event logs that might have been produced by a smart contract during the transaction.

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns​

  • List of transaction receipt objects, or null when there is no block.

    • blockHash: data, 32 bytes - Hash of block containing this transaction.

    • blockNumber: quantity - Block number of block containing this transaction.

    • blockTimestamp: quantity - Hex-encoded unix timestamp (in seconds) of the block that includes this transaction.

    • contractAddress: data, 20 bytes - Contract address created, if contract creation transaction, otherwise, null. A failed contract creation transaction still produces a contract address value.

    • cumulativeGasUsed: quantity - Total amount of gas used by previous transactions in the block and this transaction.

    • effectiveGasPrice: quantity - The actual value per gas deducted from the sender's account.

    • from: data, 20 bytes - Address of the sender.

    • gasUsed: quantity - Amount of gas used by this specific transaction.

    • logs: array - Array of log objects generated by this transaction.

      • removed: tag - true if log removed because of a chain reorganization. false if a valid log.

      • logIndex: quantity, integer - Log index position in the block. null when log is pending.

      • transactionIndex: quantity, integer - Index position of the starting transaction for the log. null when log is pending.

      • transactionHash: data, 32 bytes - Hash of the starting transaction for the log. null when log is pending.

      • blockHash: data, 32 bytes - Hash of the block that includes the log. null when log is pending.

      • blockNumber: quantity - Number of block that includes the log. null when log is pending.

      • blockTimestamp: quantity - Hex-encoded unix timestamp (in seconds) of the block that includes the log.

      • address: data, 20 bytes - Address the log originated from.

      • data: data - Non-indexed arguments of the log.

      • topics: array of data, 32 bytes each - Event signature hash and 0 to 3 indexed log arguments.

    • logsBloom: data, 256 bytes - Bloom filter for light clients to quickly retrieve related logs.

    • status: quantity - Either 0x0 (failure), 0x1 (success), or 0x2 (invalid).

    • to: data, 20 bytes - Address of the receiver, if sending ether, otherwise, null.

    • transactionHash: data, 32 bytes - Hash of the transaction.

    • transactionIndex: quantity, integer - Index position of transaction in the block.

    • transactionType: string - Transaction type.

    • revertReason: string - ABI-encoded string that displays the reason for reverting the transaction. Only available if revert reason is enabled.

    • type: quantity - Transaction type, 0x00 for legacy transactions, 0x01 for access list types, 0x02 for dynamic fees, and 0x03 for blob transactions.

    • root: data, 32 bytes - Pre-Byzantium transactions return this field instead of status. Post-transaction state root.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockReceipts",
    "params": [
      "latest"
    ],
    "id": 1
  }'

eth_getBlockTransactionCountByHash​

Returns the number of transactions in the block matching the specified block hash.

Parameters​

  • hash: string - 32-byte block hash.

Returns​

  • Integer representing the number of transactions in the specified block, or null if no matching block hash is found.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockTransactionCountByHash",
    "params": [
      "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
    ],
    "id": 53
  }'

eth_getBlockTransactionCountByNumber​

Returns the number of transactions in a block matching the specified block number.

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns​

  • Integer representing the number of transactions in the specified block, or null if no matching block number is found.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getBlockTransactionCountByNumber",
    "params": [
      "0xe8"
    ],
    "id": 51
  }'

eth_getUncleByBlockHashAndIndex​

Returns uncle specified by block hash and index.

Parameters​

  • block: string - 32-byte block hash.

  • uncleIndex: string - Index of the uncle.

Returns​

  • Block object.

    • number: quantity, integer - Block number. null when block is pending.

    • hash: data, 32 bytes - Hash of the block. null when block is pending.

    • parentHash: data, 32 bytes - Hash of the parent block.

    • nonce: data, 8 bytes - Hash of the generated proof of work. null when block is pending.

    • sha3Uncles: data, 32 bytes - SHA3 of the uncle's data in the block.

    • logsBloom: data, 256 bytes - Bloom filter for the block logs. null when block is pending.

    • transactionsRoot: data, 32 bytes - Root of the transaction trie for the block.

    • stateRoot: data, 32 bytes - Root of the final state trie for the block.

    • receiptsRoot: data, 32 bytes - Root of the receipts trie for the block.

    • miner: data, 20 bytes - Address to pay mining rewards to.

    • difficulty: quantity, integer - Difficulty for this block.

    • totalDifficulty: quantity, integer - Total difficulty of the chain until this block. This field is only returned for pre-merge (Proof of Work) blocks. This value will always be 0 for an uncle block.

    • extraData: data - Extra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option. Stores extra data when used with IBFT.

    • size: quantity, integer - Size of block in bytes.

    • gasLimit: quantity - Maximum gas allowed in this block.

    • gasUsed: quantity - Total gas used by all transactions in this block.

    • timestamp: quantity - Hex-encoded Unix timestamp (in seconds) for block assembly.

    • transactions: array - Array of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.

      • accessList: array - (Optional) List of addresses and storage keys the transaction plans to access. Used in ACCESS_LIST transactions and may be used in EIP1559 transactions.

      • blockHash: data, 32 bytes - Hash of the block containing this transaction. null when transaction is pending.

      • blockNumber: quantity - Block number of the block containing this transaction. null when transaction is pending.

      • blockTimestamp: quantity - Hex-encoded Unix timestamp (in seconds) of the block containing this transaction. null when transaction is pending.

      • chainId: quantity - Chain ID.

      • from: data, 20 bytes - Address of the sender.

      • gas: quantity - Gas provided by the sender.

      • gasPrice: quantity - (Optional) Gas price, in Wei, provided by the sender. Used only in non-EIP1559 transactions.

      • maxPriorityFeePerGas: quantity, integer - (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in EIP1559 transactions.

      • maxFeePerGas: quantity, integer - (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in EIP1559 transactions.

      • hash: data, 32 bytes - Hash of the transaction.

      • input: data - Data sent with the transaction to create or invoke a contract.

      • nonce: quantity - Number of transactions made by the sender before this one.

      • to: data, 20 bytes - Address of the receiver. null if a contract creation transaction.

      • transactionIndex: quantity, integer - Index position of the transaction in the block. null when transaction is pending.

      • transactionType: string - Transaction type.

      • value: quantity - Value transferred, in Wei.

      • v: quantity - ECDSA Recovery ID.

      • r: data, 32 bytes - ECDSA signature r.

      • s: data, 32 bytes - ECDSA signature s.

    • uncles: array - Array of uncle hashes.

    • baseFeePerGas: quantity - The block's base fee per gas. This field is empty for blocks created before EIP-1559.


    note

    Uncles don't contain individual transactions.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getUncleByBlockHashAndIndex",
    "params": [
      "0xc48fb64230a82f65a08e7280bd8745e7fea87bc7c206309dee32209fe9a985f7",
      "0x0"
    ],
    "id": 1
  }'

eth_getUncleByBlockNumberAndIndex​

Returns uncle specified by block number and index.

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

  • uncleIndex: string - Index of the uncle.

Returns​

  • Block object.

    • number: quantity, integer - Block number. null when block is pending.

    • hash: data, 32 bytes - Hash of the block. null when block is pending.

    • parentHash: data, 32 bytes - Hash of the parent block.

    • nonce: data, 8 bytes - Hash of the generated proof of work. null when block is pending.

    • sha3Uncles: data, 32 bytes - SHA3 of the uncle's data in the block.

    • logsBloom: data, 256 bytes - Bloom filter for the block logs. null when block is pending.

    • transactionsRoot: data, 32 bytes - Root of the transaction trie for the block.

    • stateRoot: data, 32 bytes - Root of the final state trie for the block.

    • receiptsRoot: data, 32 bytes - Root of the receipts trie for the block.

    • miner: data, 20 bytes - Address to pay mining rewards to.

    • difficulty: quantity, integer - Difficulty for this block.

    • totalDifficulty: quantity, integer - Total difficulty of the chain until this block. This field is only returned for pre-merge (Proof of Work) blocks. This value will always be 0 for an uncle block.

    • extraData: data - Extra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option. Stores extra data when used with IBFT.

    • size: quantity, integer - Size of block in bytes.

    • gasLimit: quantity - Maximum gas allowed in this block.

    • gasUsed: quantity - Total gas used by all transactions in this block.

    • timestamp: quantity - Hex-encoded Unix timestamp (in seconds) for block assembly.

    • transactions: array - Array of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.

      • accessList: array - (Optional) List of addresses and storage keys the transaction plans to access. Used in ACCESS_LIST transactions and may be used in EIP1559 transactions.

      • blockHash: data, 32 bytes - Hash of the block containing this transaction. null when transaction is pending.

      • blockNumber: quantity - Block number of the block containing this transaction. null when transaction is pending.

      • blockTimestamp: quantity - Hex-encoded Unix timestamp (in seconds) of the block containing this transaction. null when transaction is pending.

      • chainId: quantity - Chain ID.

      • from: data, 20 bytes - Address of the sender.

      • gas: quantity - Gas provided by the sender.

      • gasPrice: quantity - (Optional) Gas price, in Wei, provided by the sender. Used only in non-EIP1559 transactions.

      • maxPriorityFeePerGas: quantity, integer - (Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in EIP1559 transactions.

      • maxFeePerGas: quantity, integer - (Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in EIP1559 transactions.

      • hash: data, 32 bytes - Hash of the transaction.

      • input: data - Data sent with the transaction to create or invoke a contract.

      • nonce: quantity - Number of transactions made by the sender before this one.

      • to: data, 20 bytes - Address of the receiver. null if a contract creation transaction.

      • transactionIndex: quantity, integer - Index position of the transaction in the block. null when transaction is pending.

      • transactionType: string - Transaction type.

      • value: quantity - Value transferred, in Wei.

      • v: quantity - ECDSA Recovery ID.

      • r: data, 32 bytes - ECDSA signature r.

      • s: data, 32 bytes - ECDSA signature s.

    • uncles: array - Array of uncle hashes.

    • baseFeePerGas: quantity - The block's base fee per gas. This field is empty for blocks created before EIP-1559.


    note

    Uncles don't contain individual transactions.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getUncleByBlockNumberAndIndex",
    "params": [
      "0x7689D2",
      "0x0"
    ],
    "id": 1
  }'

eth_getUncleCountByBlockHash​

Returns the number of uncles in a block from a block matching the given block hash.

Parameters​

  • block: string - 32-byte block hash.

Returns​

  • Integer representing the number of uncles in the specified block.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getUncleCountByBlockHash",
    "params": [
      "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
    ],
    "id": 1
  }'

eth_getUncleCountByBlockNumber​

Returns the number of uncles in a block matching the specified block number.

Parameters​

  • blockNumber: string - Hexadecimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter.

    note

    pending returns the same value as latest.

Returns​

  • Integer representing the number of uncles in the specified block.

Example​

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "method": "eth_getUncleCountByBlockNumber",
    "params": [
      "0xe8"
    ],
    "id": 1
  }'