blocks

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

Search and filter blocks with pagination.

Schema Definition

blocks(
  first: Int = 10
  after: Cursor
  where: BlockFilter
  orderBy: BlockOrderBy
  orderDirection: OrderDirection
): BlockList!

Arguments

Argument	Type	Description
first	Int scalar	Maximum number of results to return (default: 10, max: 100).
after	Cursor scalar	Cursor for pagination. Pass the endCursor from a previous query to get the next page.
where	BlockFilter input	Filter criteria for blocks.
orderBy	BlockOrderBy enum	Field to sort results by.
orderDirection	OrderDirection enum	Sort direction (ascending or descending).

Return Type

Type	Description
BlockList! object	Paginated list of blocks.

Common Use Cases

• Display detailed block information in block explorer applications.
• Conduct historical analysis of block data using filters such as block number ranges (number: { gte, lte }), timestamps (timestamp: { gte, lte }), and transaction counts (transactionCount: { gte, lte }).
• Monitor for unusual or significant on-chain activity such as blocks with high transaction volumes or gas usage.
• Build custom blockchain data pipelines with filtered block ranges.

Example

Query

Get 5 Most Recent Blocks

query Get5MostRecentBlocks($first: Int, $orderBy: BlockOrderBy, $orderDirection: OrderDirection) {
  blocks(first: $first, orderBy: $orderBy, orderDirection: $orderDirection) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    entries {
      number
      timestamp
      size
      gasLimit
      gasUsed
      hash
      transactionCount
      confirmations
    }
  }
}

Variables

{
  "first": 5,
  "orderBy": "NUMBER",
  "orderDirection": "DESC"
}

Response

{
  "data": {
    "blocks": {
      "totalCount": 21473892,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJpZCI6NX0="
      },
      "entries": [
        {
          "number": 142934353,
          "timestamp": "2026-02-10T14:31:23Z",
          "size": 17819,
          "gasLimit": "40000000",
          "gasUsed": "12861377",
          "hash": "0x968ae3cd572c782192b122d7d579672e0237aee0d644a90b591d4f5b7f745b95",
          "transactionCount": 187,
          "confirmations": 12
        },
        {
          "number": 142934352,
          "timestamp": "2026-02-10T14:31:11Z",
          "size": 12601,
          "gasLimit": "40000000",
          "gasUsed": "36751745",
          "hash": "0x513896b1480a75493aebf1c53e65c2c247a14036a49e782a635bcc9bbe3b02fd",
          "transactionCount": 312,
          "confirmations": 13
        },
        {
          "number": 142934351,
          "timestamp": "2026-02-10T14:30:59Z",
          "size": 14156,
          "gasLimit": "40000000",
          "gasUsed": "13804391",
          "hash": "0x68ad70ff88c833981ffed861569e0671b205ec9d63d09426876536564da66048",
          "transactionCount": 145,
          "confirmations": 14
        },
        {
          "number": 142934350,
          "timestamp": "2026-02-10T14:30:47Z",
          "size": 11536,
          "gasLimit": "40000000",
          "gasUsed": "12190918",
          "hash": "0x48c9ac300357d4b0a441a0173a5271cf3512d813f0567765a249d7b457a817c6",
          "transactionCount": 98,
          "confirmations": 15
        },
        {
          "number": 142934349,
          "timestamp": "2026-02-10T14:30:35Z",
          "size": 15769,
          "gasLimit": "40000000",
          "gasUsed": "9269063",
          "hash": "0x79a4c9f0f7d0fa7df0788918e656ada4b7938d127e0a035eac72ca0fcea6d608",
          "transactionCount": 132,
          "confirmations": 16
        }
      ]
    }
  }
}

Implementation Notes

note

• The default first value is 10. OneSource enforces a maximum first value of 100. Adjust based on your needs.
• Use cursor-based pagination with after and pageInfo.endCursor to page through results. Check pageInfo.hasNextPage to determine if more pages exist.
• Range filters use structured input objects with gte and lte fields — e.g., number: { gte: 18000000, lte: 19000000 }, timestamp: { gte: "2025-01-01T00:00:00Z" }, gasUsed: { gte: "10000000" }.
• Use orderBy and orderDirection (ASC for oldest first, DESC for newest first) to ensure consistent ordering when paginating.
• Each Block entry supports a nested transactions() field with its own pagination arguments (first, after, where, orderBy, orderDirection) for fetching transactions within that block.
• Each Block entry also supports a nested contractsCreated() field for listing contracts deployed in that block.
• The gasLimit and gasUsed fields are BigInt strings. The timestamp field is an ISO 8601 formatted string.