block

The block query retrieves a single blockchain block by either its block number or block hash.

It returns a block object containing all block details including number, hash, confirmations, timestamp, transaction count, gas usage, difficulty, and a paginated list of transactions.

Schema Definition

block(
  number: UInt64
  hash: String
): Block

Arguments

Argument	Type	Description
number	UInt64 scalar	The block number to retrieve. Provide either number or hash, not both.
hash	String scalar	The block hash to retrieve. Provide either number or hash, not both.

Return Type

Block object

Common Use Cases

• Display detailed block information in block explorer applications.
• Verify that a specific transaction was included in a block and retrieve its confirmation count for payment validation.
• Analyze gas usage patterns across blocks to help users optimize their transaction timing and gas price strategies.
• Monitor blocks for specific criteria such as high gas usage, large transaction volumes, or particular transaction patterns.

Example

Query

Identify Wrapped Ether (WETH) Transactions in a Specific Block

query WrappedEtherBlockTransactions($number: UInt64, $first: Int, $where: TransactionFilter) {
  block(number: $number) {
    transactionCount
    size
    gasUsed
    gasLimit
    confirmations
    transactions(first: $first, where: $where) {
      entries {
        from
        to
        gasPrice
        gas
      }
    }
  }
}

Variables

{
  "number": 22530116,
  "first": 5,
  "where": {
    "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
  }
}

Response

{
  "data": {
    "block": {
      "transactionCount": 312,
      "size": 170635,
      "gasUsed": 35980169,
      "gasLimit": 36000000,
      "confirmations": 1149727,
      "transactions": {
        "entries": [
          {
            "from": "0x32f5ae3af145dbd51f5a84b0004b7588a87c9790",
            "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "gasPrice": "1250655772",
            "gas": 54244
          }
        ]
      }
    }
  }
}

Implementation Notes

note

• Using number to query by block height is generally most efficient and the most common approach.
• Use hash when you have a specific block hash from a transaction receipt or block header.
• The query returns a nullable block object which includes a nested transactions field that accepts pagination arguments for paginating through the block's transactions.
• Use the confirmations field to assess finality. Higher confirmation counts indicate lower risk of chain reorganization.
• Values for timestamp are Unix timestamps in seconds. Convert to local time for user-facing applications.