> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream Finalized Blocks

> Returns only finalized blocks matching the query. Same request format as /stream.

<Warning>**Real-time streaming is not supported for Substrate chains.** Only finalized historical data is available. If you need real-time Substrate data, [schedule a call with our team](https://calendly.com/t-tyrie-subsquid/30min).</Warning>


## OpenAPI

````yaml en/api/catalog/substrate/openapi.yaml POST /finalized-stream
openapi: 3.1.0
info:
  title: SQD Portal API - Substrate Dataset Endpoints
  description: >-
    API endpoints for interacting with Substrate datasets under the SQD Portal,
    specifically for the Polkadot dataset.
  version: 1.0.0
servers:
  - url: https://portal.sqd.dev/datasets/polkadot
    description: SQD Portal's endpoint for Polkadot
security: []
paths:
  /finalized-stream:
    post:
      summary: Stream Finalized Blocks
      description: >-
        Returns only finalized blocks matching the query. Same request format as
        /stream.
      requestBody:
        description: >-
          Data query to filter and retrieve blocks. Request body may be gzipped
          (Content-Encoding: gzip).
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataQuery'
            examples:
              balances-transfer:
                summary: Query Balances.Transfer Events
                value:
                  type: substrate
                  fromBlock: 20000000
                  toBlock: 20000100
                  fields:
                    block:
                      number: true
                      timestamp: true
                    event:
                      name: true
                      args: true
                  events:
                    - name:
                        - Balances.Transfer
              calls-with-extrinsics:
                summary: Query Calls with Extrinsics
                value:
                  type: substrate
                  fromBlock: 20000000
                  toBlock: 20000100
                  fields:
                    block:
                      number: true
                      timestamp: true
                    call:
                      name: true
                      args: true
                      success: true
                    extrinsic:
                      hash: true
                      fee: true
                      success: true
                  calls:
                    - name:
                        - Balances.transfer_keep_alive
                      extrinsic: true
      responses:
        '200':
          description: >-
            A stream of finalized blocks in JSON lines format, optionally
            gzipped. Never returns blocks above the finalized head.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Block'
              examples:
                balances-transfer-response:
                  summary: Balances.Transfer finalized events response
                  value:
                    - header:
                        number: 20000050
                        hash: >-
                          0xabc123def456789abc123def456789abc123def456789abc123def456789abcd
                        parentHash: >-
                          0x789012abc345678901234567890123456789012345678901234567890123abcd
                        timestamp: 1700000000000
                      events:
                        - index: 3
                          extrinsicIndex: 1
                          name: Balances.Transfer
                          phase: ApplyExtrinsic
                          args:
                            from: 15oF4uVJwmo4TdGW7VfQxNLavjCXviqWrztPu9BFKHEtaqry
                            to: 14E5nqKAp3oAJcg4aM6hEYyLT2JAPi6ixST1VRkNg8wAKPe
                            amount: '10000000000'
        '204':
          description: >-
            Indicates that the requested block range is entirely above the range
            of blocks available in the dataset. The portal may wait for up to 5s
            before returning this.
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: >
            Possible causes: (1) request headers or body encoding are incorrect;
            (2) the query is invalid - the response will include an explanation;
            (3) fromBlock is below the dataset's start_block (see /metadata).
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: Dataset not found
          content:
            text/plain:
              schema:
                type: string
        '429':
          description: >-
            Too many requests; rate limit exceeded. May include a Retry-After
            header indicating the number of seconds to wait before retrying the
            request.
          content:
            text/plain:
              schema:
                type: string
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying
        '500':
          description: Internal server error. Do not retry requests causing these.
          content:
            text/plain:
              schema:
                type: string
        '503':
          description: >-
            The server could not process the request at the moment. The client
            should retry the request later. May include a Retry-After header
            indicating the number of seconds to wait before retrying the
            request.
          content:
            text/plain:
              schema:
                type: string
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying
      x-codeSamples:
        - lang: shell
          label: Query Balances.Transfer Events
          source: >
            curl --compressed -X POST
            'https://portal.sqd.dev/datasets/polkadot/finalized-stream' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "substrate",
                "fromBlock": 20000000,
                "toBlock": 20000100,
                "fields": {
                  "block": {
                    "number": true,
                    "timestamp": true
                  },
                  "event": {
                    "name": true,
                    "args": true
                  }
                },
                "events": [{
                  "name": ["Balances.Transfer"]
                }]
              }'
        - lang: shell
          label: Query Calls with Extrinsics
          source: >
            curl --compressed -X POST
            'https://portal.sqd.dev/datasets/polkadot/finalized-stream' \
              -H 'Content-Type: application/json' \
              -d '{
                "type": "substrate",
                "fromBlock": 20000000,
                "toBlock": 20000100,
                "fields": {
                  "block": {
                    "number": true,
                    "timestamp": true
                  },
                  "call": {
                    "name": true,
                    "args": true,
                    "success": true
                  },
                  "extrinsic": {
                    "hash": true,
                    "fee": true,
                    "success": true
                  }
                },
                "calls": [{
                  "name": ["Balances.transfer_keep_alive"],
                  "extrinsic": true
                }]
              }'
        - lang: python
          label: Query Balances.Transfer Events
          source: |
            import requests

            response = requests.post(
                "https://portal.sqd.dev/datasets/polkadot/finalized-stream",
                json={
                    "type": "substrate",
                    "fromBlock": 20000000,
                    "toBlock": 20000100,
                    "fields": {
                        "block": {
                            "number": True,
                            "timestamp": True
                        },
                        "event": {
                            "name": True,
                            "args": True
                        }
                    },
                    "events": [{
                        "name": ["Balances.Transfer"]
                    }]
                }
            )
            data = response.json()
        - lang: javascript
          label: Query Balances.Transfer Events
          source: >
            const response = await
            fetch("https://portal.sqd.dev/datasets/polkadot/finalized-stream", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    type: "substrate",
                    fromBlock: 20000000,
                    toBlock: 20000100,
                    fields: {
                        block: {
                            number: true,
                            timestamp: true
                        },
                        event: {
                            name: true,
                            args: true
                        }
                    },
                    events: [{
                        name: ["Balances.Transfer"]
                    }]
                })
            });

            const data = await response.json();
components:
  schemas:
    DataQuery:
      type: object
      properties:
        type:
          type: string
          enum:
            - substrate
          default: substrate
        fromBlock:
          type: integer
          format: int64
          description: >-
            The number of the first block to fetch. If unsure how far into the
            past this can go consult /metadata
          default: 20000000
        toBlock:
          type: integer
          format: int64
          description: >-
            The block number to fetch up to (inclusive). Optional; if omitted,
            streams until dataset height or timeout.
          default: 20000100
        parentBlockHash:
          type: string
          description: Expected hash of the parent of the first requested block
        includeAllBlocks:
          type: boolean
          description: If true, includes blocks with no matching data
          default: false
        fields:
          type: object
          description: >-
            Field selector. See the HTTP 200 response description for details on
            fields that aren't self-explanatory
          properties:
            block:
              type: object
              description: >-
                Field selector for block headers (the .header objects of JSON
                block records)
              properties:
                number:
                  type: boolean
                  description: Block number
                hash:
                  type: boolean
                  description: Block hash
                parentHash:
                  type: boolean
                  description: Hash of the parent block
                stateRoot:
                  type: boolean
                  description: Root hash of the state trie after this block
                extrinsicsRoot:
                  type: boolean
                  description: Root hash of the extrinsics trie for this block
                digest:
                  type: boolean
                  description: Block digest as JSON object
                specName:
                  type: boolean
                  description: Runtime spec name
                specVersion:
                  type: boolean
                  description: Runtime spec version
                implName:
                  type: boolean
                  description: Runtime implementation name
                implVersion:
                  type: boolean
                  description: Runtime implementation version
                validator:
                  type: boolean
                  description: Block validator/author address
                timestamp:
                  type: boolean
                  description: Block timestamp in milliseconds since Unix epoch
            extrinsic:
              type: object
              description: Field selector for extrinsics
              properties:
                index:
                  type: boolean
                  description: Index of the extrinsic in the block
                version:
                  type: boolean
                  description: Extrinsic format version
                success:
                  type: boolean
                  description: Whether the extrinsic executed successfully
                hash:
                  type: boolean
                  description: Extrinsic hash
                fee:
                  type: boolean
                  description: Extrinsic fee as a decimal string
                tip:
                  type: boolean
                  description: Extrinsic tip as a decimal string
                signature:
                  type: boolean
                  description: Extrinsic signature as JSON object
                error:
                  type: boolean
                  description: Extrinsic error as JSON object (if failed)
            call:
              type: object
              description: Field selector for calls
              properties:
                extrinsicIndex:
                  type: boolean
                  description: Index of the parent extrinsic in the block
                address:
                  type: boolean
                  description: >-
                    Call address within the extrinsic call tree (array of
                    integers)
                name:
                  type: boolean
                  description: Qualified call name (e.g. Balances.transfer_keep_alive)
                success:
                  type: boolean
                  description: Whether the call executed successfully
                args:
                  type: boolean
                  description: Call arguments as JSON
                origin:
                  type: boolean
                  description: Call origin as JSON
                error:
                  type: boolean
                  description: Call error as JSON (if failed)
            event:
              type: object
              description: Field selector for events
              properties:
                index:
                  type: boolean
                  description: Index of the event in the block
                extrinsicIndex:
                  type: boolean
                  description: Index of the parent extrinsic in the block
                name:
                  type: boolean
                  description: Qualified event name (e.g. Balances.Transfer)
                phase:
                  type: boolean
                  description: Event phase (ApplyExtrinsic, Finalization, Initialization)
                callAddress:
                  type: boolean
                  description: Address of the call that emitted this event
                topics:
                  type: boolean
                  description: Event topics as an array of hex strings
                args:
                  type: boolean
                  description: Event arguments as JSON
          default:
            block:
              number: true
              hash: true
              parentHash: true
            event:
              name: true
            call:
              name: true
        events:
          type: array
          description: >-
            Event data requests. An empty object matches all events; an empty
            array matches no events
          items:
            type: object
            properties:
              name:
                description: Filter by qualified event name (e.g. Balances.Transfer)
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: >-
                  Fetch the full call stack (all parent calls) for matching
                  events
                type: boolean
        calls:
          type: array
          description: >-
            Call data requests. An empty object matches all calls; an empty
            array matches no calls
          items:
            type: object
            properties:
              name:
                description: >-
                  Filter by qualified call name (e.g.
                  Balances.transfer_keep_alive)
                type: array
                items:
                  type: string
              subcalls:
                description: Fetch all child calls (subcalls) for matching calls
                type: boolean
              extrinsic:
                description: Fetch parent extrinsics for matching calls
                type: boolean
              stack:
                description: Fetch all parent calls in the call tree
                type: boolean
              events:
                description: Fetch all events emitted by matching calls
                type: boolean
        evmLogs:
          type: array
          description: >-
            EVM.Log event requests for Frontier EVM parachains (e.g. Moonbeam,
            Astar). Filters on EVM.Log events specifically
          items:
            type: object
            properties:
              address:
                description: Filter by EVM contract address (lowercase hex)
                type: array
                items:
                  type: string
              topic0:
                description: Filter by first topic (event signature hash)
                type: array
                items:
                  type: string
              topic1:
                description: Filter by second topic
                type: array
                items:
                  type: string
              topic2:
                description: Filter by third topic
                type: array
                items:
                  type: string
              topic3:
                description: Filter by fourth topic
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        ethereumTransactions:
          type: array
          description: >-
            Ethereum.transact call requests for Frontier EVM parachains. Filters
            on Ethereum.transact calls specifically
          items:
            type: object
            properties:
              to:
                description: Filter by destination EVM contract address (lowercase hex)
                type: array
                items:
                  type: string
              sighash:
                description: Filter by function signature hash (4-byte hex)
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching calls
                type: boolean
              stack:
                description: Fetch all parent calls in the call tree
                type: boolean
              events:
                description: Fetch all events emitted by matching calls
                type: boolean
        contractsEvents:
          type: array
          description: >-
            Contracts.ContractEmitted event requests for ink! smart contracts.
            Contract addresses must be hexadecimal (decoded from SS58) and
            lowercase
          items:
            type: object
            properties:
              contractAddress:
                description: Filter by contract address (hexadecimal, lowercase)
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        gearMessagesEnqueued:
          type: array
          description: Gear.UserMessageEnqueued event requests for Gear/Vara networks
          items:
            type: object
            properties:
              programId:
                description: Filter by Gear program ID
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        gearUserMessagesSent:
          type: array
          description: Gear.UserMessageSent event requests for Gear/Vara networks
          items:
            type: object
            properties:
              programId:
                description: Filter by Gear program ID
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
        reviveContractEmitted:
          type: array
          description: Revive.ContractEmitted event requests for Revive smart contracts
          items:
            type: object
            properties:
              contract:
                description: Filter by contract address
                type: array
                items:
                  type: string
              topic0:
                description: Filter by first topic
                type: array
                items:
                  type: string
              topic1:
                description: Filter by second topic
                type: array
                items:
                  type: string
              topic2:
                description: Filter by third topic
                type: array
                items:
                  type: string
              topic3:
                description: Filter by fourth topic
                type: array
                items:
                  type: string
              extrinsic:
                description: Fetch parent extrinsics for matching events
                type: boolean
              call:
                description: Fetch the call that emitted each matching event
                type: boolean
              stack:
                description: Fetch the full call stack for matching events
                type: boolean
      required:
        - fromBlock
    Block:
      type: object
      properties:
        header:
          type: object
          properties:
            number:
              type: integer
              format: uint64
            hash:
              type: string
            parentHash:
              type: string
            stateRoot:
              type: string
            extrinsicsRoot:
              type: string
            digest:
              type: object
              description: Block digest containing consensus engine data
            specName:
              type: string
              description: Runtime spec name
            specVersion:
              type: integer
              description: Runtime spec version
            implName:
              type: string
              description: Runtime implementation name
            implVersion:
              type: integer
              description: Runtime implementation version
            validator:
              type: string
              description: Block validator/author address
            timestamp:
              type: integer
              format: uint64
              description: Block timestamp in milliseconds since Unix epoch
        extrinsics:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Index of the extrinsic in the block
              version:
                type: integer
              success:
                type: boolean
              hash:
                type: string
                description: Extrinsic hash
              fee:
                type: string
                description: Extrinsic fee as a decimal string
              tip:
                type: string
                description: Extrinsic tip as a decimal string
              signature:
                type: object
                description: Extrinsic signature data
              error:
                type: object
                description: Error data if the extrinsic failed
        calls:
          type: array
          items:
            type: object
            properties:
              extrinsicIndex:
                type: integer
                description: Index of the parent extrinsic
              address:
                type: array
                items:
                  type: integer
                description: Call address within the extrinsic call tree
              name:
                type: string
                description: Qualified call name (e.g. Balances.transfer_keep_alive)
              success:
                type: boolean
              args:
                type: object
                description: Call arguments
              origin:
                type: object
                description: Call origin
              error:
                type: object
                description: Error data if the call failed
        events:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Index of the event in the block
              extrinsicIndex:
                type: integer
                description: Index of the parent extrinsic
              callAddress:
                type: array
                items:
                  type: integer
                description: Address of the call that emitted this event
              name:
                type: string
                description: Qualified event name (e.g. Balances.Transfer)
              phase:
                type: string
                description: Event phase (ApplyExtrinsic, Finalization, Initialization)
              topics:
                type: array
                items:
                  type: string
              args:
                type: object
                description: Event arguments
      required:
        - header

````