> ## 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 portal stream

> API reference for bitcoinPortalStream().

`bitcoinPortalStream()` reads Bitcoin blocks from SQD Portal and applies one or more query outputs.

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

const stream = bitcoinPortalStream({
  id: 'bitcoin-transactions',
  portal: 'https://portal.sqd.dev/datasets/bitcoin-mainnet',
  outputs: bitcoinQuery()
    .addFields({
      block: { number: true },
      transaction: { txid: true },
      input: { txid: true, vout: true },
      output: { value: true, scriptPubKeyAddress: true },
    })
    .addTransactionRequest({
      range: { from: 'latest' },
      request: { inputs: true, outputs: true },
    }),
})
```

## Options

| Option     | Required | Description                                                                  |
| ---------- | -------- | ---------------------------------------------------------------------------- |
| `id`       | Yes      | Stable, non-empty pipe identifier. Targets use it as the default cursor key. |
| `portal`   | Yes      | Dataset URL or a `PortalClientOptions` object.                               |
| `outputs`  | Yes      | A `BitcoinQueryBuilder`, transformer, or record of named outputs.            |
| `cache`    | No       | Portal response cache.                                                       |
| `logger`   | No       | Pino-compatible logger, log level, `false`, or `null`.                       |
| `metrics`  | No       | Metrics server instance.                                                     |
| `profiler` | No       | `boolean` or profiler span hooks.                                            |
| `progress` | No       | Progress callbacks and reporting interval.                                   |

When `portal` is an object, it accepts `url`, `finalized`, `http`, `maxBytes`, `maxIdleTimeMs`, `maxWaitTimeMs`, and `headPollIntervalMs`.

Use `for await` to consume batches, `.pipe()` to add a whole-stream transformer, or `.pipeTo()` to connect a target.

## RPC latency watcher

`bitcoinRpcLatencyWatcher()` compares the latest Portal block with one or more Bitcoin Core JSON-RPC endpoints. Bitcoin Core does not expose a block WebSocket, so the watcher polls `getbestblockhash` and `getblockheader`.

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

const stream = bitcoinPortalStream({
  id: 'bitcoin-latency',
  portal: 'https://portal.sqd.dev/datasets/bitcoin-mainnet',
  outputs: bitcoinRpcLatencyWatcher({
    rpcUrl: ['https://bitcoin-rpc.publicnode.com'],
    intervalMs: 4_000,
    requestTimeoutMs: 4_000,
  }),
})
```

| Option             | Required | Description                                                                  |
| ------------------ | -------- | ---------------------------------------------------------------------------- |
| `rpcUrl`           | Yes      | Bitcoin Core JSON-RPC endpoint URLs.                                         |
| `intervalMs`       | No       | Poll interval in milliseconds. Defaults to `4_000`.                          |
| `requestTimeoutMs` | No       | Timeout per RPC request. Defaults to the larger of `1_000` and `intervalMs`. |

Each non-null output contains the Portal block `number` and `timestamp`, `portal.receivedAt`, and an `rpc` array with each sanitized `url`, optional block `hash` and `receivedAt`, and `portalDelayMs`.

For an authenticated node, put the credentials in the URL, for example `http://user:pass@127.0.0.1:8332`. The watcher sends them with HTTP Basic authentication and removes them from emitted URLs, logs, and metrics.

See the [query builder reference](./query-builder) for typed fields and filters.


## Related topics

- [Bitcoin quickstart](/en/sdk/pipes-sdk/bitcoin/quickstart.md)
- [Bitcoin Portal API](/en/portal/bitcoin/overview.md)
- [Portal stream](/en/sdk/pipes-sdk/evm/reference/basic-components/source.md)
- [EVM Portal stream](/en/sdk/squid-sdk/evm/reference/evm-stream.md)
- [Tron portal stream](/en/sdk/pipes-sdk/tron/reference/basic-components/source.md)