Bitcoin query builder - SQD Documentation

bitcoinQuery() returns a typed BitcoinQueryBuilder. Add the fields you need, then add one or more range-scoped requests.

import { bitcoinQuery } from '@subsquid/pipes/bitcoin'

const query = bitcoinQuery()
  .addFields({
    block: { number: true, timestamp: true },
    output: { value: true, scriptPubKeyType: true, scriptPubKeyAddress: true },
  })
  .addOutputRequest({
    range: { from: 880_000, to: 880_000 },
    request: { scriptPubKeyType: ['witness_v1_taproot'] },
  })

Methods

class BitcoinQueryBuilder<F extends FieldSelection = {}> {
  addFields<T>(fields: T): BitcoinQueryBuilder<F & T>
  addTransactionRequest(options: RequestOptions<TransactionRequest>): this
  addInputRequest(options: RequestOptions<InputRequest>): this
  addOutputRequest(options: RequestOptions<OutputRequest>): this
  includeAllBlocks(range?: Range): this
  addRange(range: PortalRange): this
  merge(query?: BitcoinQueryBuilder<F>): this
  build(options?: { setupQuery?: SetupQueryFn<BitcoinQueryBuilder<F>> }): QueryAwareTransformer
}

addFields() narrows both the TypeScript output and the fields requested from Portal. The stream always adds block.number and block.hash for cursor handling.

Field groups

Group	Fields
`block`	`number`, `hash`, `parentHash`, `timestamp`, `medianTime`, `version`, `merkleRoot`, `nonce`, `target`, `bits`, `difficulty`, `chainWork`, `strippedSize`, `size`, `weight`
`transaction`	`transactionIndex`, `hex`, `txid`, `hash`, `size`, `vsize`, `weight`, `version`, `locktime`
`input`	`transactionIndex`, `inputIndex`, `type`, `txid`, `vout`, `scriptSigHex`, `scriptSigAsm`, `sequence`, `coinbase`, `txInWitness`, `prevoutGenerated`, `prevoutHeight`, `prevoutValue`, `prevoutScriptPubKeyHex`, `prevoutScriptPubKeyAsm`, `prevoutScriptPubKeyDesc`, `prevoutScriptPubKeyType`, `prevoutScriptPubKeyAddress`
`output`	`transactionIndex`, `outputIndex`, `value`, `scriptPubKeyHex`, `scriptPubKeyAsm`, `scriptPubKeyDesc`, `scriptPubKeyType`, `scriptPubKeyAddress`

Request filters

Method	Filters and relations
`addTransactionRequest()`	`inputs`, `outputs`
`addInputRequest()`	`type`, `prevoutScriptPubKeyAddress`, `prevoutScriptPubKeyType`, `prevoutGenerated`, `transaction`, `transactionInputs`, `transactionOutputs`
`addOutputRequest()`	`scriptPubKeyAddress`, `scriptPubKeyType`, `transaction`, `transactionInputs`, `transactionOutputs`

Values inside a filter list are ORed. Different fields in one request are ANDed. Separate request clauses are combined across their ranges.

Ranges

Request ranges accept block numbers, formatted block-number strings, ISO dates, Date objects, and 'latest' for from.

type PortalRange = {
  from?: number | string | 'latest' | Date
  to?: number | string | Date
}

Dates are resolved through the dataset’s timestamp endpoint before streaming. Resolution is at Portal chunk granularity, so a date is a coarse starting point rather than an exact timestamp boundary. Use numeric block bounds when the range must be precise. If from is 'latest', to must be a block number.

Bitcoin-specific formats

Hashes, scripts, and witness items are bare hex without 0x.
Output and previous-output values are BTC numbers, not satoshis.
Block timestamps are Unix seconds.
Address fields are optional because not every script has a standard address.

See Handling Bitcoin data for join and value-conversion examples.

​Methods

​Field groups

​Request filters

​Ranges

​Bitcoin-specific formats

Methods

Field groups

Request filters

Ranges

Bitcoin-specific formats