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

# Wait for Receipt \[transaction.waitForReceipt]

Waits for a transaction to be included on a block (one confirmation by default), returning a watcher handle whose `receipt` promise resolves with the transaction receipt.

Additionally supports replacement detection (for example, sped-up or cancelled transactions). A transaction is replaced when another transaction is sent from the same `from` and `nonce`:

* `repriced`: the gas price was modified (for example, different `maxFeePerGas`).
* `cancelled`: the transaction was cancelled (for example, self-send with `value` of `0`).
* `replaced`: the transaction payload was changed (for example, different `value` or `data`).

## Usage

This example waits for a transaction to be included in a block.

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

const { receipt } = client.transaction.waitForReceipt({
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

const result = await receipt
// @log: {
// @log:   blockHash: '0xaf1dadb8a98f1282e8f7b42cc3da8847bfa2cf4e227b8220403ae642e1173088',
// @log:   blockNumber: 19868020n,
// @log:   ...
// @log:   status: 'success',
// @log: }
```

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

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

### Standalone Action

Call `Actions.transaction.waitForReceipt` directly by passing the Client as the first argument.

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

const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

const result = await receipt
// @log: {
// @log:   blockHash: '0xaf1dadb8a98f1282e8f7b42cc3da8847bfa2cf4e227b8220403ae642e1173088',
// @log:   blockNumber: 19868020n,
// @log:   ...
// @log:   status: 'success',
// @log: }
```

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

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

## Recipes

### Wait for Confirmations

Set `confirmations` and polling options when downstream work requires a deeper confirmation threshold.

```ts twoslash
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

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

const watch = client.transaction.waitForReceipt({
  confirmations: 3, // [!code focus]
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  pollingInterval: 2_000, // [!code focus]
  timeout: 120_000, // [!code focus]
})

const receipt = await watch.receipt
```

### Handle a Replacement Transaction

Register `onReplaced` to handle a repriced, cancelled, or otherwise replaced transaction.

```ts twoslash
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

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

const watch = client.transaction.waitForReceipt({
  checkReplacement: true, // [!code focus]
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

watch.onReplaced(({ reason, replacedTransaction, transaction }) => { // [!code focus]
  console.log(reason, replacedTransaction.hash, transaction.hash) // [!code focus]
}) // [!code focus]
```

## Return Value

`Watcher`

A watcher handle with the following members:

#### receipt

* **Type:** `Promise<TransactionReceipt>`

Resolves with the transaction receipt after confirmation. The promise rejects when an error occurs or the timeout elapses.

The promise remains pending if [`off`](#off) stops the watcher before the receipt resolves.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

const result = await receipt // [!code focus]
```

#### onReceipt

* **Type:** `(fn: (receipt: TransactionReceipt) => void) => () => void`

Registers a listener invoked with the transaction receipt once confirmed. Fires immediately if the receipt has already resolved. Returns a function that unregisters the listener.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const watch = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

const off = watch.onReceipt((receipt) => console.log(receipt.status)) // [!code focus]

// later: unregister just this listener
off()
```

#### onReplaced

* **Type:** `(fn: (response: { reason: 'cancelled' | 'replaced' | 'repriced'; replacedTransaction: Transaction; transaction: Transaction; transactionReceipt: TransactionReceipt }) => void) => () => void`

Registers a listener invoked when the transaction is replaced (repriced, cancelled, or replaced). Returns a function that unregisters the listener.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const watch = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

watch.onReplaced((replacement) => console.log(replacement.reason)) // [!code focus]
```

#### onError

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

Registers a listener invoked when waiting for the receipt fails. Fires immediately if the watcher has already errored. Returns a function that unregisters the listener.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const watch = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})

watch.onError((error) => console.error(error)) // [!code focus]
```

#### off

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

Tears down the watcher: removes all listeners and stops the underlying poll. Idempotent and terminal. If the receipt has not yet resolved, [`receipt`](#receipt) remains pending.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const watch = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
})
watch.onReceipt((receipt) => console.log(receipt.status))

watch.off() // [!code focus]
```

## Parameters

### checkReplacement

* **Type:** `boolean`
* **Default:** `client.chain?.supportsTransactionReplacementDetection ?? true`

Whether to check for transaction replacements (repriced, cancelled, or replaced transactions).

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  checkReplacement: false, // [!code focus]
})
```

### confirmations

* **Type:** `number`
* **Default:** `1`

The number of confirmations (blocks passed) to wait for before resolving.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  confirmations: 5, // [!code focus]
})
```

### hash

* **Type:** `Hex`

Hash of the transaction to wait for.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d', // [!code focus]
})
```

### pollingInterval

* **Type:** `number`
* **Default:** `client.chain?.preconfirmationTime ?? client.pollingInterval`

Polling frequency (in milliseconds).

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  pollingInterval: 1_000, // [!code focus]
})
```

### retryCount

* **Type:** `number`
* **Default:** `6`

The number of times to retry if the transaction or block is not found.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  retryCount: 3, // [!code focus]
})
```

### retryDelay

* **Type:** `number | (({ count, error }: { count: number; error: Error }) => number)`
* **Default:** exponential backoff

The time (in milliseconds) to wait between retries.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  retryDelay: 1_000, // [!code focus]
})
```

### timeout

* **Type:** `number`
* **Default:** `180_000`

Optional timeout (in milliseconds) to wait before giving up.

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

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const { receipt } = Actions.transaction.waitForReceipt(client, {
  hash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  timeout: 60_000, // [!code focus]
})
```

## Errors

| Error | Description |
| --- | --- |
| `Actions.block.Errors.BlockNotFoundError` | A block required while waiting for the receipt could not be found. |
| `Actions.transaction.Errors.TransactionReceiptNotFoundError` | The transaction receipt could not be found. |
| `Actions.transaction.Errors.WaitForReceiptTimeoutError` | The receipt was not confirmed before `timeout` elapsed. |