> ## 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 > Stream finalized Substrate blockchain data from SQD Portal. **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). ## 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: >- Streams only finalized blocks matching the provided data query (finalized data does not reorganize; a 409 here only means the provided parentBlockHash is stale). Query structure is identical to that of the /stream endpoint. Required request headers: `Content-Type: application/json`; optional request headers: `Accept-Encoding: gzip`, `Content-Encoding: gzip`. 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: >- No new blocks available in the requested range - the range is entirely above the current dataset head. Not an error and the response has no body; wait and retry to keep following the chain head. The portal may wait for up to 5s before returning this. content: text/plain: schema: type: string example: No new blocks available in the requested range '400': description: > Invalid request or query (`error.code` is `malformed_request`; `error.param` names the request field at fault when one is). Possible causes: (1) request headers or body encoding are incorrect; (2) the query is invalid - `error.message` includes an explanation; (3) fromBlock is below the dataset's start_block (see /metadata). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: invalid_request_error code: malformed_request message: 'Bad request: fromBlock must be a non-negative integer' param: fromBlock '404': description: Dataset not found (`error.code` is `unknown_dataset`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: invalid_request_error code: unknown_dataset message: 'Unknown dataset: no-such-chain' '409': description: >- Parent block hash mismatch (`error.code` is `base_block_mismatch`). Finalized data does not reorganize, so the provided parentBlockHash is stale or was carried over from an unfinalized block. Recover as for /stream by walking the top-level previousBlocks list. content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' '429': description: >- Rate limited (`error.type` is `rate_limit_error`). Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) '500': description: >- Internal server error (`error.type` is `api_error`). Do not retry; report the error together with its request_id content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: api_error code: internal_error message: Internal server error request_id: 0198c3f1-... '502': description: >- A data source the Portal depends on is unavailable (`error.code` is `upstream_unavailable`) - retry later. A proxied upstream failure keeps the upstream's own 5xx status content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: availability_error code: upstream_unavailable message: Upstream data source is unavailable, please try again later request_id: 0198c3f1-... '503': description: >- Service temporarily unavailable (`error.type` is `availability_error`, typically `no_workers` or `retries_exhausted`) - retry later. May carry Retry-After; honor it when present content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: availability_error code: no_workers message: No workers available for dataset request_id: 0198c3f1-... headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) '529': description: >- Overloaded (`error.code` is `overloaded`) - the Portal or a data source is at capacity. Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later request_id: 0198c3f1-... headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) 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 ErrorResponse: type: object description: Error body shared by every failing response. properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error example: error: type: invalid_request_error code: unknown_dataset message: 'Unknown dataset: no-such-chain' ConflictResponse: type: object description: >- The 409 body carries the standard error envelope plus a top-level `previousBlocks` list - a slice of the current canonical chain at and below the conflict point, in ascending block-number order. properties: error: $ref: '#/components/schemas/ErrorDetail' previousBlocks: type: array description: >- `{ number, hash }` pairs from the current canonical chain in ascending order; the last entry is the most recent block at or below the conflict point. Guaranteed to contain at least the parent of the requested fromBlock. items: type: object properties: number: type: integer format: int64 hash: type: string required: - number - hash required: - error - previousBlocks example: error: type: invalid_request_error code: base_block_mismatch message: Base block mismatch previousBlocks: - number: 21780871 hash: 0xab12cd... - number: 21780872 hash: 0xf6a96a29... ErrorDetail: type: object description: >- Machine-readable error detail. Branch on `type`; match on `code` for one specific case. properties: type: type: string description: >- Coarse category to branch on. One of `invalid_request_error`, `rate_limit_error`, `availability_error`, or `api_error`. Treat an unknown `code` according to its `type`. example: invalid_request_error code: type: string description: >- Specific cause, stable across releases. Match on this rather than on `message`. example: base_block_mismatch message: type: string description: >- Human-readable detail. Prose, not stable; do not parse or match on it. param: type: string description: The request parameter at fault, when the error is about one. request_id: type: string description: >- Echo of the `x-request-id` response header, included in the body on 5xx errors. Quote it when reporting a problem. required: - type - code - message ```` ## Related topics - [Stream Finalized Blocks](/en/api/tron/finalized-stream.md) - [Finalized and recent data](/en/portal/introduction/finalized-and-recent-data.md) - [Portal stream](/en/sdk/pipes-sdk/solana/reference/basic-components/source.md)