> ## 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. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback: POST https://docs.sqd.dev/feedback ```json { "path": "/en/api/bitcoin/stream", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # Stream Blocks > Returns blocks matching the query. May include unfinalized blocks. Response is a JSON array of blocks containing the requested fields. Set toBlock to limit the range, or omit it to stream up to the dataset height. Supports gzip compression via Accept-Encoding and Content-Encoding headers. ## 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: > Returns blocks matching the query. May include unfinalized blocks. Response is a JSON array of blocks containing the requested fields. Set toBlock to limit the range, or omit it to stream up to the dataset height. Supports gzip compression via Accept-Encoding and Content-Encoding headers. requestBody: description: Data query to filter and retrieve blocks 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: 50000 prevoutScriptPubKeyType: witness_v1_taproot prevoutScriptPubKeyAddress: >- bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3297 - transactionIndex: 2 inputIndex: 0 txid: >- b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3 vout: 1 prevoutValue: 125000 prevoutScriptPubKeyType: witness_v1_taproot prevoutScriptPubKeyAddress: >- bc1pxyz0987654321abcdefghijklmnopqrstuvwxyz012345678901234 outputs: [] '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 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: > 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 '409': description: >- Conflict due to a mismatched parent block hash. This will happen when the client requests a range starting with an orphaned block in the real-time setting. The response contains a list of previous blocks belonging to the current chain; the client should find a block matching one of these (by both hash and block number) in its records and restart the stream and its business logic from that block. content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' '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 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 number of the last block to fetch (inclusive) 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 satoshis 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 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: integer format: int64 description: Value of the spent output in satoshis prevoutScriptPubKeyHex: type: string prevoutScriptPubKeyAsm: type: string prevoutScriptPubKeyDesc: type: string prevoutScriptPubKeyType: type: string prevoutScriptPubKeyAddress: type: string description: Address of the spent output outputs: type: array items: type: object properties: transactionIndex: type: integer outputIndex: type: integer value: type: integer format: int64 description: Output value in 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 ConflictResponse: type: object properties: previousBlocks: type: array items: type: object properties: number: type: integer format: int64 hash: type: string required: - number - hash required: - previousBlocks ````