> ## 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.

# Bitcoin query builder

> Fields, filters, and ranges supported by BitcoinQueryBuilder.

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

```ts theme={"system"}
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

```ts theme={"system"}
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`.

```ts theme={"system"}
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](../../guides/basic-development/handling-bitcoin-data) for join and value-conversion examples.


## Related topics

- [Handling Bitcoin data](/en/sdk/pipes-sdk/bitcoin/guides/basic-development/handling-bitcoin-data.md)
- [Bitcoin portal stream](/en/sdk/pipes-sdk/bitcoin/reference/basic-components/source.md)
- [Query Bitcoin Transactions](/en/portal/bitcoin/examples/query-transactions.md)
- [Query builder](/en/sdk/pipes-sdk/evm/reference/basic-components/query-builder.md)
- [Tron query builder](/en/sdk/pipes-sdk/tron/reference/basic-components/query-builder.md)