--- title: "Stream Finalized Blocks" method: POST path: "/finalized-stream" --- # Stream Finalized Blocks `POST /finalized-stream` ## Request - Base URL: `https://portal.sqd.dev/datasets/bitcoin-mainnet` - URL: `https://portal.sqd.dev/datasets/bitcoin-mainnet/finalized-stream` - Auth: none required - TypeScript: (a function with typed inputs; its response is checked against the schema) Streams only finalized blocks matching the provided data query (never returns a 409 response). 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`. ## Request body - DataQuery - `type` 'tron', required: The type of blockchain data (fixed to Tron for this API). - `fromBlock` integer, required: The block number to start fetching from (inclusive). - `toBlock` integer: The block number to fetch up to (inclusive). Optional; if omitted, streams until dataset height or timeout. - `parentBlockHash` string: Expected hash of the parent of the first requested block. - `includeAllBlocks` boolean: If true, includes blocks with no matching data in the response. - `fields` object: Field selector for data items to retrieve. - `block` object: Field selector for block headers. - `number` boolean: Block number. - `hash` boolean: Block ID (hash). The first 8 bytes encode the block number. - `parentHash` boolean: ID (hash) of the parent block. - `txTrieRoot` boolean: Root hash of the block's transaction Merkle trie. - `version` boolean: Block version number. - `timestamp` boolean: Block timestamp in Unix milliseconds. - `witnessAddress` boolean: Address of the Super Representative (witness) that produced the block (41-prefixed hex). - `witnessSignature` boolean: Signature of the producing witness over the block header. - `transaction` object: Field selector for transactions. - `transactionIndex` boolean: Index of the transaction in the block. - `hash` boolean: Transaction hash (txID). - `type` boolean: Contract type of the transaction, e.g. TransferContract, TransferAssetContract, TriggerSmartContract. - `ret` boolean: Transaction result array; each entry carries fields such as contractRet (e.g. SUCCESS, REVERT). - `signature` boolean: List of signatures authorizing the transaction. - `parameter` boolean: Decoded contract payload (type_url plus a value object holding the contract-specific fields). - `permissionId` boolean: Permission id used for multi-signature accounts. - `refBlockBytes` boolean: Reference block bytes used for transaction expiration. - `refBlockHash` boolean: Reference block hash used for transaction expiration. - `feeLimit` boolean: Maximum fee (in SUN) the sender is willing to pay for smart-contract execution. - `expiration` boolean: Expiration time of the transaction in Unix milliseconds. - `timestamp` boolean: Transaction timestamp in Unix milliseconds. - `rawDataHex` boolean: Hex-encoded raw transaction data. - `fee` boolean: Total fee charged for the transaction, in SUN. - `contractResult` boolean: Hex-encoded return value of the executed smart contract. - `contractAddress` boolean: Address of the contract invoked or created (41-prefixed hex). - `resMessage` boolean: Result message returned by the virtual machine, if any. - `withdrawAmount` boolean: Amount withdrawn (e.g. staking rewards), in SUN. - `unfreezeAmount` boolean: Amount unfrozen by the transaction, in SUN. - `withdrawExpireAmount` boolean: Amount of expired unfreeze withdrawn, in SUN. - `cancelUnfreezeV2Amount` boolean: Map of amounts re-frozen when cancelling pending Stake 2.0 unfreezes. - `result` boolean: Execution result of the transaction receipt (e.g. SUCCESS). - `energyFee` boolean: Fee paid for energy consumed, in SUN. - `energyUsage` boolean: Energy consumed from the caller's own resources. - `energyUsageTotal` boolean: Total energy consumed by the transaction. - `netUsage` boolean: Bandwidth (net) consumed from the caller's own resources. - `netFee` boolean: Fee paid for bandwidth consumed, in SUN. - `originEnergyUsage` boolean: Energy paid by the contract owner (origin) under an energy-sharing policy. - `energyPenaltyTotal` boolean: Additional energy penalty applied to the transaction. - `log` object: Field selector for logs (TVM event logs). - `transactionIndex` boolean: Index of the parent transaction in the block. - `logIndex` boolean: Index of the log in the block. - `address` boolean: Contract address that emitted the log (20-byte EVM-style hex, no 41 prefix). - `data` boolean: Non-indexed log data. - `topics` boolean: Indexed log topics (topic0 is the event signature). - `internalTransaction` object: Field selector for internal transactions. - `transactionIndex` boolean: Index of the parent transaction in the block. - `internalTransactionIndex` boolean: Index of the internal transaction within its parent transaction. - `hash` boolean: Hash of the internal transaction. - `callerAddress` boolean: Address that initiated the internal transaction (41-prefixed hex). - `transferToAddress` boolean: Recipient address of the internal transaction (41-prefixed hex). - `callValueInfo` boolean: List of transferred values, each with callValue (amount in SUN) and tokenId (null for TRX, a TRC-10 asset id otherwise). - `note` boolean: Hex-encoded note describing the internal call (e.g. 63616c6c for "call"). - `rejected` boolean: Whether the internal transaction was rejected. - `extra` boolean: Optional extra data attached to the internal transaction. - `transactions` object[]: Transaction data requests. Matches transactions by contract type. - `type` string[]: Contract types to match, e.g. ["TransferContract", "TriggerSmartContract"]. - `logs` boolean: Fetch all event logs emitted by matching transactions. - `internalTransactions` boolean: Fetch all internal transactions of matching transactions. - `transferTransactions` object[]: Native TRX transfer requests (TransferContract). Addresses are 41-prefixed lowercase hex. - `owner` string[]: Sender (owner) addresses (41-prefixed hex). - `to` string[]: Recipient addresses (41-prefixed hex). - `logs` boolean: Fetch all event logs emitted by matching transactions. - `internalTransactions` boolean: Fetch all internal transactions of matching transactions. - `transferAssetTransactions` object[]: TRC-10 asset transfer requests (TransferAssetContract). - `owner` string[]: Sender (owner) addresses (41-prefixed hex). - `to` string[]: Recipient addresses (41-prefixed hex). - `asset` string[]: TRC-10 asset ids to match. - `logs` boolean: Fetch all event logs emitted by matching transactions. - `internalTransactions` boolean: Fetch all internal transactions of matching transactions. - `triggerSmartContractTransactions` object[]: Smart-contract call requests (TriggerSmartContract). Covers TRC-20 and all other contract interactions. - `owner` string[]: Caller (owner) addresses (41-prefixed hex). - `contract` string[]: Target contract addresses (41-prefixed hex), e.g. the USDT contract 41a614f803b6fd780986a42c78ec9c7f77e6ded13c. - `sighash` string[]: Function selectors (first 4 bytes of calldata), e.g. a9059cbb for transfer(address,uint256). - `logs` boolean: Fetch all event logs emitted by matching transactions. - `internalTransactions` boolean: Fetch all internal transactions of matching transactions. - `logs` object[]: Log data requests (TVM event logs). - `address` string[]: Contract addresses emitting the logs (20-byte EVM-style hex, no 41 prefix, lowercase). - `topic0` string[]: First topic of the log (e.g., event signature). - `topic1` string[] - `topic2` string[] - `topic3` string[] - `transaction` boolean: Fetch the parent transaction for matching logs. - `internalTransactions` object[]: Internal transaction data requests. - `caller` string[]: Caller addresses (41-prefixed hex). - `transferTo` string[]: Recipient addresses (41-prefixed hex). - `transaction` boolean: Fetch the parent transaction for matching internal transactions. ## Response `200` A stream of finalized 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. - Block[] - `header` object: Block header data. Fields are conditionally returned based on the `fields.block` parameter in the request. Only requested fields will be included in the response. - `number` integer: Block number. - `hash` string: Block ID (hash). - `parentHash` string: Parent block ID (hash). - `txTrieRoot` string: Root hash of the block's transaction Merkle trie. - `version` integer: Block version number. - `timestamp` integer: Block timestamp in Unix milliseconds. - `witnessAddress` string: Address of the producing witness (41-prefixed hex). - `witnessSignature` string: Signature of the producing witness over the block header. - `transactions` object[] - `transactionIndex` integer: Index of the transaction in the block. - `hash` string: Transaction hash (txID). - `type` string: Contract type of the transaction, e.g. TransferContract, TriggerSmartContract. - `ret` object[]: Transaction result entries. - `contractRet` string: Contract execution result, e.g. SUCCESS or REVERT. - `signature` string[]: Signatures authorizing the transaction. - `parameter` object: Decoded contract payload (type_url plus a contract-specific value object). Address fields inside value are 41-prefixed hex. - `type_url` string: Protobuf type URL of the contract, e.g. type.googleapis.com/protocol.TriggerSmartContract. - `value` object: Contract-specific fields (e.g. owner_address, to_address, amount, contract_address, data, asset_name). - `permissionId` integer, nullable: Permission id used for multi-signature accounts. Null when not set. - `refBlockBytes` string: Reference block bytes used for transaction expiration. - `refBlockHash` string: Reference block hash used for transaction expiration. - `feeLimit` string, nullable: Maximum fee (in SUN) the sender is willing to pay, as a decimal string. May be null. - `expiration` integer: Expiration time of the transaction in Unix milliseconds. - `timestamp` integer, nullable: Transaction timestamp in Unix milliseconds. May be null. - `rawDataHex` string: Hex-encoded raw transaction data. - `fee` string, nullable: Total fee charged, in SUN, as a decimal string. May be null. - `contractResult` string: Hex-encoded smart-contract return value. - `contractAddress` string, nullable: Address of the contract invoked or created (41-prefixed hex). Null for transactions that do not target a contract. - `resMessage` string, nullable: Result message returned by the virtual machine, if any. May be null. - `withdrawAmount` string, nullable: Amount withdrawn, in SUN, as a decimal string. May be null. - `unfreezeAmount` string, nullable: Amount unfrozen, in SUN, as a decimal string. May be null. - `withdrawExpireAmount` string, nullable: Amount of expired unfreeze withdrawn, in SUN, as a decimal string. May be null. - `cancelUnfreezeV2Amount` object, nullable: Map of amounts re-frozen when cancelling pending Stake 2.0 unfreezes. May be null. - `result` string, nullable: Execution result of the transaction receipt, e.g. SUCCESS. May be null. - `energyFee` string, nullable: Fee paid for energy consumed, in SUN, as a decimal string. May be null. - `energyUsage` string, nullable: Energy consumed from the caller's own resources, as a decimal string. May be null. - `energyUsageTotal` string, nullable: Total energy consumed by the transaction, as a decimal string. May be null. - `netUsage` string, nullable: Bandwidth (net) consumed from the caller's own resources, as a decimal string. May be null. - `netFee` string, nullable: Fee paid for bandwidth consumed, in SUN, as a decimal string. May be null. - `originEnergyUsage` string, nullable: Energy paid by the contract owner (origin), as a decimal string. May be null. - `energyPenaltyTotal` string, nullable: Additional energy penalty applied, as a decimal string. May be null. - `logs` object[] - `transactionIndex` integer: Index of the parent transaction. - `logIndex` integer: Index of the log in the block. - `address` string: Contract address emitting the log (20-byte EVM-style hex, no 41 prefix). - `data` string, nullable: Non-indexed log data. Null when the event has no non-indexed data. - `topics` string[]: Indexed log topics (topic0 is the event signature). - `internalTransactions` object[] - `transactionIndex` integer: Index of the parent transaction. - `internalTransactionIndex` integer: Index of the internal transaction within its parent. - `hash` string: Hash of the internal transaction. - `callerAddress` string: Address that initiated the internal transaction (41-prefixed hex). - `transferToAddress` string: Recipient address (41-prefixed hex). - `callValueInfo` object[]: Transferred values for the internal transaction. - `callValue` integer, nullable: Transferred amount in SUN. May be null. - `tokenId` string, nullable: TRC-10 asset id, or null for TRX transfers. - `note` string: Hex-encoded note describing the internal call (e.g. 63616c6c for "call"). - `rejected` boolean, nullable: Whether the internal transaction was rejected. May be null. - `extra` string, nullable: Optional extra data attached to the internal transaction. Null when absent. ## Other responses - `204`: 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. - `400`: 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). - `404`: Dataset not found - `409`: Conflict due to a mismatched parent block hash. - `429`: Too many requests; rate limit exceeded. May include a Retry-After header indicating the number of seconds to wait before retrying the request. - `500`: Internal server error. Do not retry requests causing these. - `503`: 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. --- [API](https://skmtc.dev/sqd/apis/sqd-portal-api-bitcoin-dataset-endpoints.md) - [All operations](https://skmtc.dev/sqd/apis/sqd-portal-api-bitcoin-dataset-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/sqd/apis/sqd-portal-api-bitcoin-dataset-endpoints/revisions/cf9d60e495b1?raw)