block

API Context — Endpoint: https://api.onesource.io/federation/{'{'}chain{'}'}/graphql | Auth Header: x-bp-token: BP-{YOUR_API_KEY} | Method: POST | Content-Type: application/json

Look up a block by number or hash. Provide either number or hash, not both. Returns null if the block doesn't exist.

Schema Definition

block(
  number: BlockNumber
  hash: BlockHash
): Block

Arguments

Argument	Type	Description
number	BlockNumber scalar	Block number (height) to look up.
hash	BlockHash scalar	Block hash to look up.

Return Type

Type	Description
Block object	A block containing transactions and metadata. Blocks are the fundamental unit of the blockchain, each building on the previous one.

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.
• List contracts deployed within a specific block using the nested contractsCreated field.

Example

Query

Identify Wrapped Ether (WETH) Transactions in a Specific Block

query WrappedEtherBlockTransactions(
  $number: BlockNumber
  $first: Int
  $where: BlockTransactionFilter
) {
  block(number: $number) {
    number
    hash
    timestamp
    transactionCount
    size
    gasUsed
    gasLimit
    confirmations
    transactions(first: $first, where: $where) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      entries {
        hash
        from {
          address
        }
        to {
          address
        }
        value {
          raw
          formatted
        }
        gas {
          limit
          price
          used
        }
        timestamp
        status
      }
    }
  }
}

Variables

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

Response

{
  "data": {
    "block": {
      "number": 22530116,
      "hash": "0x968ae3cd572c782192b122d7d579672e0237aee0d644a90b591d4f5b7f745b95",
      "timestamp": "2025-09-14T18:22:35Z",
      "transactionCount": 312,
      "size": 170635,
      "gasUsed": "35980169",
      "gasLimit": "36000000",
      "confirmations": 1149727,
      "transactions": {
        "totalCount": 8,
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "eyJpZCI6NX0="
        },
        "entries": [
          {
            "hash": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
            "from": {
              "address": "0x32f5ae3af145dbd51f5a84b0004b7588a87c9790"
            },
            "to": {
              "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
            },
            "value": {
              "raw": "1000000000000000000",
              "formatted": "1.0"
            },
            "gas": {
              "limit": 54244,
              "price": "1250655772",
              "used": 46109
            },
            "timestamp": "2025-09-14T18:22:35Z",
            "status": "SUCCESS"
          }
        ]
      }
    }
  }
}

Implementation Notes

note

• The block query returns null if the block doesn't exist. Always handle the null case in your application.
• Provide either number or hash to look up a block, not both. The number argument is of type BlockNumber (a positive integer representing block height). The hash argument is of type BlockHash (a 0x-prefixed, 66-character hex string).
• 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 gasUsed and gasLimit fields are BigInt strings (not integers), since gas values can exceed JavaScript's safe integer range.
• The timestamp field returns an ISO 8601 formatted string (e.g., "2025-09-14T18:22:35Z"), not a Unix integer.
• The confirmations field updates dynamically as new blocks are mined. Higher confirmation counts indicate lower risk of chain reorganization.
• The nested transactions field returns a BlockTransactionList and accepts its own pagination arguments (first, after) and filter/sort arguments. The filter type is BlockTransactionFilter (not TransactionFilter), which supports filtering by from, to, value, gasPrice, gasUsed, and status.
• Transactions within a block are returned as BlockTransaction objects — a lighter-weight representation than the full Transaction type. Fields like from and to return Address objects (use from { address } to get the hex string), value returns a TokenAmount object, and gas returns a GasInfo object.
• The nested contractsCreated field returns a ContractList of contracts deployed in that block, with its own pagination and filter/sort arguments using ContractFilter and ContractOrderBy.
• To search and filter across multiple blocks, use the blocks query with pagination and filtering support.