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

# Handling Bitcoin data

> Work with Bitcoin transactions, inputs, outputs, and UTXO values.

The Bitcoin query builder exposes blocks, transactions, inputs with previous-output data, and outputs. Portal returns these as separate arrays within each block.

## Join records within a block

`transactionIndex` joins inputs and outputs to their parent transaction. `inputIndex` and `outputIndex` identify a record within that transaction.

```ts theme={"system"}
import { bitcoinQuery } from '@subsquid/pipes/bitcoin'

export const taprootSpends = bitcoinQuery()
  .addFields({
    block: { number: true, timestamp: true },
    transaction: { transactionIndex: true, txid: true },
    input: {
      transactionIndex: true,
      inputIndex: true,
      prevoutValue: true,
      prevoutScriptPubKeyAddress: true,
      prevoutScriptPubKeyType: true,
    },
  })
  .addInputRequest({
    range: { from: 880_000, to: 880_000 },
    request: {
      prevoutScriptPubKeyType: ['witness_v1_taproot'],
      transaction: true,
    },
  })
  .build()
  .pipe((blocks) =>
    blocks.flatMap((block) => {
      const transactions = new Map(
        block.transactions.map((tx) => [tx.transactionIndex, tx]),
      )

      return block.inputs.map((input) => ({
        block: block.header.number,
        spendingTxid: transactions.get(input.transactionIndex)?.txid,
        inputIndex: input.inputIndex,
        spentAddress: input.prevoutScriptPubKeyAddress,
        spentValueBtc: input.prevoutValue,
      }))
    }),
  )
```

Input and output requests also accept `transactionInputs: true` and `transactionOutputs: true` to include every sibling input or output from the same transaction.

## Values

`output.value` and `input.prevoutValue` are JavaScript `number` values denominated in BTC, following Bitcoin Core's JSON convention. Convert to a safe integer number of satoshis before storing or aggregating:

```ts theme={"system"}
function btcToSatoshis(value: number): bigint {
  return BigInt(Math.round(value * 100_000_000))
}
```

## Identifiers and optional fields

* `txid` identifies a transaction without witness data; `hash` is witness-aware.
* Block hashes, transaction hashes, scripts, and witness items are bare hex without `0x`.
* Coinbase inputs have `coinbase` data instead of a previous `txid` and `vout`.
* `scriptPubKeyAddress` and previous-output fields are optional. For example, a `nulldata` output has no spendable address.
* Block timestamps and median times are Unix seconds.

See the [query builder reference](../../reference/basic-components/query-builder) for every field, relation flag, and filter.


## Related topics

- [Bitcoin query builder](/en/sdk/pipes-sdk/bitcoin/reference/basic-components/query-builder.md)
- [Handling Tron data](/en/sdk/pipes-sdk/tron/guides/basic-development/handling-tron-data.md)
- [Bitcoin](/en/data/bitcoin/bitcoin-mainnet.md)
- [Bitcoin quickstart](/en/sdk/pipes-sdk/bitcoin/quickstart.md)
- [Bitcoin Portal API](/en/portal/bitcoin/overview.md)