> ## 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 Blocks > Stream Bitcoin blockchain data with the SQD Portal API. ## OpenAPI ````yaml /en/api/catalog/bitcoin/openapi.yaml post /stream openapi: 3.1.0 info: title: SQD Portal API - Bitcoin Dataset Endpoints description: >- API endpoints for interacting with Bitcoin datasets under the SQD Portal, specifically for the bitcoin-mainnet dataset. version: 1.0.0 servers: - url: https://portal.sqd.dev/datasets/bitcoin-mainnet description: SQD Portal's endpoint for Bitcoin Mainnet security: [] paths: /stream: post: summary: Stream Blocks description: >- Streams a list of blocks matching the provided data query, potentially including real-time data. 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: taproot-inputs: summary: Query Taproot Inputs value: type: bitcoin fromBlock: 880000 toBlock: 880000 fields: block: number: true timestamp: true input: transactionIndex: true inputIndex: true txid: true vout: true prevoutValue: true prevoutScriptPubKeyType: true prevoutScriptPubKeyAddress: true inputs: - prevoutScriptPubKeyType: - witness_v1_taproot taproot-outputs: summary: Query Taproot Outputs value: type: bitcoin fromBlock: 880000 toBlock: 880000 fields: block: number: true timestamp: true output: transactionIndex: true outputIndex: true value: true scriptPubKeyAddress: true scriptPubKeyType: true outputs: - scriptPubKeyType: - witness_v1_taproot responses: '200': description: >- A stream of blocks in JSON lines format, optionally gzipped. Can be empty if the data query has a bounded range and all blocks in the range have been skipped. May include X-Sqd-Finalized-Head-Number and X-Sqd-Finalized-Head-Hash headers, indicating the latest finalized block that's on the same chain as the returned blocks. headers: X-Sqd-Finalized-Head-Number: schema: type: integer format: int64 description: >- Block number of the latest finalized block. Returned blocks can be above, at, or below this block number. required: false X-Sqd-Finalized-Head-Hash: schema: type: string description: >- Hash of the latest finalized block. All returned blocks are guaranteed to belong to the same (not necessarily final) chain as this block. required: false content: application/json: schema: type: array items: $ref: '#/components/schemas/Block' examples: taproot-inputs: summary: Taproot inputs response value: - header: number: 880000 hash: >- 00000000000000000000a3b049e5e4e16c539c9a0b3c7d8f1e2a4b6c8d0e1f2a parentHash: >- 00000000000000000000b4c150f6f5f27d640a0b1c4d8e9f2f3b5c7d9e1f0a3b timestamp: 1738000000 transactions: [] inputs: - transactionIndex: 1 inputIndex: 0 txid: >- a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2 vout: 0 prevoutValue: 0.0005 prevoutScriptPubKeyType: witness_v1_taproot prevoutScriptPubKeyAddress: >- bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297 - transactionIndex: 2 inputIndex: 0 txid: >- b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3 vout: 1 prevoutValue: 0.00125 prevoutScriptPubKeyType: witness_v1_taproot prevoutScriptPubKeyAddress: >- bc1pxyz0987654321abcdefghijklmnopqrstuvwxyz012345678901234 outputs: [] '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 headers: X-Sqd-Finalized-Head-Number: schema: type: integer format: int64 description: Block number of the latest finalized block. required: false X-Sqd-Finalized-Head-Hash: schema: type: string description: Hash of the latest finalized block. required: false '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`) - the query's parentBlockHash does not match the canonical parent of the first requested block, typically after a chain reorganization. Walk the top-level previousBlocks list to find the most recent block you have already processed, roll back your data to it, then resume the stream from the next block, passing that block's hash as parentBlockHash. If nothing in the list matches your records, restart from an earlier fromBlock, again with parentBlockHash. 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 Taproot Inputs source: > curl --compressed -X POST 'https://portal.sqd.dev/datasets/bitcoin-mainnet/stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "bitcoin", "fromBlock": 880000, "toBlock": 880000, "fields": { "block": { "number": true, "timestamp": true }, "input": { "transactionIndex": true, "inputIndex": true, "txid": true, "vout": true, "prevoutValue": true, "prevoutScriptPubKeyType": true, "prevoutScriptPubKeyAddress": true } }, "inputs": [{ "prevoutScriptPubKeyType": ["witness_v1_taproot"] }] }' - lang: shell label: Query Taproot Outputs source: > curl --compressed -X POST 'https://portal.sqd.dev/datasets/bitcoin-mainnet/stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "bitcoin", "fromBlock": 880000, "toBlock": 880000, "fields": { "block": { "number": true, "timestamp": true }, "output": { "transactionIndex": true, "outputIndex": true, "value": true, "scriptPubKeyAddress": true, "scriptPubKeyType": true } }, "outputs": [{ "scriptPubKeyType": ["witness_v1_taproot"] }] }' - lang: python label: Query Taproot Inputs source: | import requests response = requests.post( "https://portal.sqd.dev/datasets/bitcoin-mainnet/stream", json={ "type": "bitcoin", "fromBlock": 880000, "toBlock": 880000, "fields": { "block": { "number": True, "timestamp": True }, "input": { "transactionIndex": True, "inputIndex": True, "txid": True, "vout": True, "prevoutValue": True, "prevoutScriptPubKeyType": True, "prevoutScriptPubKeyAddress": True } }, "inputs": [{ "prevoutScriptPubKeyType": ["witness_v1_taproot"] }] } ) data = response.json() - lang: javascript label: Query Taproot Inputs source: > const response = await fetch("https://portal.sqd.dev/datasets/bitcoin-mainnet/stream", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "type": "bitcoin", "fromBlock": 880000, "toBlock": 880000, "fields": { "block": { "number": true, "timestamp": true }, "input": { "transactionIndex": true, "inputIndex": true, "txid": true, "vout": true, "prevoutValue": true, "prevoutScriptPubKeyType": true, "prevoutScriptPubKeyAddress": true } }, "inputs": [{ "prevoutScriptPubKeyType": ["witness_v1_taproot"] }] }) }); const data = await response.json(); components: schemas: DataQuery: type: object properties: type: type: string enum: - bitcoin default: bitcoin 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: 880000 toBlock: type: integer format: int64 description: >- The block number to fetch up to (inclusive). Optional; if omitted, streams until dataset height or timeout. default: 880000 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: true 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 height hash: type: boolean description: Block hash parentHash: type: boolean description: Hash of the previous block timestamp: type: boolean description: Block timestamp in seconds since Unix epoch medianTime: type: boolean description: Median time past (BIP 113) version: type: boolean description: Block version field merkleRoot: type: boolean description: Merkle root of all transactions in the block nonce: type: boolean description: Nonce used in proof-of-work target: type: boolean description: Proof-of-work target for this block bits: type: boolean description: Compact representation of the target difficulty: type: boolean chainWork: type: boolean description: Total work in the chain up to and including this block strippedSize: type: boolean description: Block size without witness data size: type: boolean description: Total block size in bytes weight: type: boolean description: Block weight in weight units (BIP 141) transaction: type: object description: Field selector for transactions properties: transactionIndex: type: boolean description: Index of the transaction within the block hex: type: boolean description: Raw transaction hex txid: type: boolean description: >- Transaction ID (double SHA-256 of serialized transaction without witness) hash: type: boolean description: >- Transaction hash (includes witness data, differs from txid for SegWit transactions) size: type: boolean description: Transaction size in bytes vsize: type: boolean description: Virtual size (weight / 4) weight: type: boolean description: Transaction weight in weight units version: type: boolean description: Transaction version number locktime: type: boolean description: >- Block height or timestamp after which the transaction is final input: type: object description: Field selector for transaction inputs properties: transactionIndex: type: boolean description: Index of the parent transaction within the block inputIndex: type: boolean description: Index of this input within the transaction type: type: boolean description: Input type txid: type: boolean description: Transaction ID of the output being spent vout: type: boolean description: >- Index of the output being spent in the referenced transaction scriptSigHex: type: boolean description: ScriptSig in hex encoding scriptSigAsm: type: boolean description: ScriptSig in human-readable ASM format sequence: type: boolean description: Sequence number of the input coinbase: type: boolean description: Coinbase data (only present in coinbase transactions) txInWitness: type: boolean description: Witness data for the input (SegWit) prevoutGenerated: type: boolean description: Whether the spent output was a coinbase output prevoutHeight: type: boolean description: Block height of the spent output prevoutValue: type: boolean description: >- Value of the spent output in BTC (decimal float, not satoshis). null for coinbase inputs. prevoutScriptPubKeyHex: type: boolean description: ScriptPubKey of the spent output in hex encoding prevoutScriptPubKeyAsm: type: boolean description: ScriptPubKey of the spent output in ASM format prevoutScriptPubKeyDesc: type: boolean description: Output descriptor of the spent output script prevoutScriptPubKeyType: type: boolean description: >- Script type of the spent output (e.g. pubkeyhash, witness_v1_taproot) prevoutScriptPubKeyAddress: type: boolean description: Address of the spent output output: type: object description: Field selector for transaction outputs properties: transactionIndex: type: boolean description: Index of the parent transaction within the block outputIndex: type: boolean description: Index of this output within the transaction value: type: boolean description: Output value in BTC (decimal float, not satoshis) scriptPubKeyHex: type: boolean description: ScriptPubKey in hex encoding scriptPubKeyAsm: type: boolean description: ScriptPubKey in human-readable ASM format scriptPubKeyDesc: type: boolean description: Output descriptor of the script scriptPubKeyType: type: boolean description: >- Output type (e.g. pubkeyhash, scripthash, witness_v0_keyhash, witness_v1_taproot, nulldata) scriptPubKeyAddress: type: boolean description: Output address default: block: number: true hash: true timestamp: true transaction: transactionIndex: true txid: true size: true weight: true input: transactionIndex: true inputIndex: true prevoutValue: true prevoutScriptPubKeyAddress: true output: transactionIndex: true outputIndex: true value: true scriptPubKeyAddress: true transactions: type: array description: Transaction data requests. An empty object matches all transactions default: - inputs: true outputs: true items: type: object properties: inputs: description: Fetch all inputs for matching transactions type: boolean outputs: description: Fetch all outputs for matching transactions type: boolean inputs: type: array description: >- Input data requests. Filter by prevout address, type, or coinbase status items: type: object properties: type: description: Filter by input type type: array items: type: string prevoutScriptPubKeyAddress: description: Filter by the address of the spent output type: array items: type: string prevoutScriptPubKeyType: description: Filter by the type of the spent output script type: array items: type: string prevoutGenerated: description: Filter by whether the spent output was a coinbase output type: boolean transaction: description: Fetch parent transactions for all matching inputs type: boolean transactionInputs: description: >- Fetch all sibling inputs of matching inputs' parent transactions type: boolean transactionOutputs: description: Fetch all outputs of matching inputs' parent transactions type: boolean outputs: type: array description: Output data requests. Filter by address or script type items: type: object properties: scriptPubKeyAddress: description: Filter by output address type: array items: type: string scriptPubKeyType: description: Filter by output script type type: array items: type: string transaction: description: Fetch parent transactions for all matching outputs type: boolean transactionInputs: description: Fetch all inputs of matching outputs' parent transactions type: boolean transactionOutputs: description: >- Fetch all sibling outputs of matching outputs' parent transactions type: boolean required: - fromBlock Block: type: object properties: header: type: object properties: number: type: integer format: uint64 hash: type: string parentHash: type: string timestamp: type: integer format: uint64 description: Block timestamp in seconds since Unix epoch medianTime: type: integer format: uint64 description: Median time past (BIP 113) version: type: integer merkleRoot: type: string nonce: type: integer format: uint64 target: type: string bits: type: string difficulty: type: number format: double chainWork: type: string strippedSize: type: integer size: type: integer weight: type: integer transactions: type: array items: type: object properties: transactionIndex: type: integer hex: type: string description: Raw transaction hex txid: type: string description: Transaction ID hash: type: string description: Transaction hash (includes witness data) size: type: integer vsize: type: integer description: Virtual size (weight / 4) weight: type: integer version: type: integer locktime: type: integer inputs: type: array items: type: object properties: transactionIndex: type: integer inputIndex: type: integer type: type: string txid: type: string description: Transaction ID of the output being spent vout: type: integer description: Index of the output being spent scriptSigHex: type: string scriptSigAsm: type: string sequence: type: integer format: uint64 coinbase: type: string description: Coinbase data (only present in coinbase transactions) txInWitness: type: array items: type: string prevoutGenerated: type: boolean description: Whether the spent output was a coinbase output prevoutHeight: type: integer prevoutValue: type: number nullable: true description: >- Value of the spent output in BTC (decimal float, not satoshis). null for coinbase inputs. prevoutScriptPubKeyHex: type: string prevoutScriptPubKeyAsm: type: string prevoutScriptPubKeyDesc: type: string prevoutScriptPubKeyType: type: string prevoutScriptPubKeyAddress: type: string nullable: true description: Address of the spent output. null for coinbase inputs. outputs: type: array items: type: object properties: transactionIndex: type: integer outputIndex: type: integer value: type: number description: Output value in BTC (decimal float, not satoshis) scriptPubKeyHex: type: string scriptPubKeyAsm: type: string scriptPubKeyDesc: type: string scriptPubKeyType: type: string description: >- Output type (e.g. pubkeyhash, scripthash, witness_v0_keyhash, witness_v1_taproot, nulldata) scriptPubKeyAddress: type: string description: Output address 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 Blocks](/en/api/substrate/stream.md) - [Stream Finalized Blocks](/en/api/substrate/finalized-stream.md)