> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# Watch Block Headers \[block.watchHeaders]

Watches incoming block headers without fetching full blocks.

The watcher uses a `newHeads` subscription through a WebSocket or IPC transport. The source starts when the first listener or iterator attaches.

## Usage

:::code-group
```ts twoslash [example.ts]
import { client } from './viem.config'

const watch = client.block.watchHeaders()

watch.onBlockHeader((header) => console.log(header.number))
// @log: 19868020n

// later: stop watching
watch.off()
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, publicActions, webSocket } from 'viem'
import { mainnet } from 'viem/chains'

export const client = Client.create({
  chain: mainnet,
  transport: webSocket(),
}).extend(publicActions())
```
:::

### Standalone Action

Call `Actions.block.watchHeaders` directly by passing the Client as the first argument.

```ts twoslash
import { Actions, Client, webSocket } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({
  chain: mainnet,
  transport: webSocket(),
})

const watch = Actions.block.watchHeaders(client)
watch.onBlockHeader((header) => console.log(header.number))
```

## Return Value

`Watcher`

A watcher handle with the following members:

### onBlockHeader

* **Type:** `(fn: (header: BlockHeader, prevHeader: BlockHeader | undefined) => void) => () => void`

Registers a listener for each new block header. The returned function unregisters the listener.

Block headers omit the full-block `size`, `totalDifficulty`, `transactions`, `uncles`, and `withdrawals` fields.

### onError

* **Type:** `(fn: (error: Error) => void) => () => void`

Registers a listener that runs when the subscription fails.

### off

* **Type:** `() => void`

Stops the subscription, removes all listeners, and ends all iterators. The method is idempotent and terminal.

### `[Symbol.asyncIterator]`

* **Type:** `() => AsyncIterableIterator<{ blockHeader: BlockHeader; prevBlockHeader: BlockHeader | undefined }>`

Async-iterates incoming block headers as a latest-only state stream.