--- title: "Stream Finalized Blocks" method: POST path: "/finalized-stream" --- # Stream Finalized Blocks `POST /finalized-stream` 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.net/sqd/apis/sqd-portal-api-bitcoin-dataset-endpoints.md) · [All operations](https://skmtc.net/sqd/apis/sqd-portal-api-bitcoin-dataset-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sqd/sqd-portal-api-bitcoin-dataset-endpoints/versions/cf9d60e495b1/schema)