> **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 Quote Token Updates \[token.watchUpdateQuoteToken]

Watches TIP-20 quote token update events for a token. Emits `NextQuoteTokenSet` when a quote token update is staged, and `QuoteTokenUpdate` when it is applied.

## Usage

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

const watcher = client.token.watchUpdateQuoteToken({
  token: '0x20c0000000000000000000000000000000000000',
})

watcher.onLogs((logs) => {
  for (const log of logs) console.log(log.eventName, log.args)
  // @log: NextQuoteTokenSet {
  // @log:   updater: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
  // @log:   nextQuoteToken: '0x20C0000000000000000000000000000000000001'
  // @log: }
})

// Later, tear down the watcher.
watcher.off()
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
// [!include ~/snippets/tempo/viem.config.ts:setup]
```
:::

Also callable standalone: `Actions.token.watchUpdateQuoteToken(client, options)`, with `Actions` imported from `'viem/tempo'`.

## Recipes

### Review Staged Quote Token Changes Before They Apply

Branch on `eventName` to flag a staged change for risk review while it is pending, then refresh pricing configuration once the update lands.

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

const watcher = client.token.watchUpdateQuoteToken({
  token: '0x20c0000000000000000000000000000000000000',
})

watcher.onLogs((logs) => {
  for (const log of logs) {
    if (log.eventName === 'NextQuoteTokenSet') // [!code focus]
      console.log('Review staged quote token:', log.args.nextQuoteToken) // [!code focus]
    if (log.eventName === 'QuoteTokenUpdate') // [!code focus]
      console.log('Quote token applied:', log.args.newQuoteToken) // [!code focus]
    // @log: Review staged quote token: 0x20C0000000000000000000000000000000000001
  }
})
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
// [!include ~/snippets/tempo/viem.config.ts:setup]
```
:::

## Return Value

Returns a watcher handle. Watching starts when the first listener (or async iterator) attaches, and stops when `off` is called.

```ts
type ReturnType = {
  /** Registers a log listener. Starts the watcher on first registration. Returns an unregister function. */
  onLogs: (fn: (logs: readonly Log[]) => void) => () => void
  /** Registers an error listener. Returns an unregister function. */
  onError: (fn: (error: Error) => void) => () => void
  /** Tears down the watcher: removes listeners, ends iterators, stops the poll or subscription. */
  off: () => void
  /** Async-iterates emitted log batches (latest-only stream). */
  [Symbol.asyncIterator]: () => AsyncIterableIterator<{ logs: readonly Log[] }>
}
```

Each log is decoded, with the event arguments on `args`. Discriminate the two events with `eventName`:

```ts
type Log =
  | {
      /** Decoded `NextQuoteTokenSet` event arguments. */
      args: {
        /** Address that staged the update. */
        updater: Address
        /** Quote token staged to apply. */
        nextQuoteToken: Address
      }
      /** Name of the emitted event. */
      eventName: 'NextQuoteTokenSet'
      // ...standard log fields (address, blockHash, blockNumber, logIndex, transactionHash, ...)
    }
  | {
      /** Decoded `QuoteTokenUpdate` event arguments. */
      args: {
        /** Address that applied the update. */
        updater: Address
        /** New quote token. */
        newQuoteToken: Address
      }
      /** Name of the emitted event. */
      eventName: 'QuoteTokenUpdate'
      // ...standard log fields (address, blockHash, blockNumber, logIndex, transactionHash, ...)
    }
```

## Parameters

### args

* **Type:** `object`

```ts
type Args =
  | {
      /** Filter by updating address. */
      updater?: Address | Address[] | null
      /** Filter by staged quote token (`NextQuoteTokenSet`). */
      nextQuoteToken?: Address | Address[] | null
    }
  | {
      /** Filter by updating address. */
      updater?: Address | Address[] | null
      /** Filter by applied quote token (`QuoteTokenUpdate`). */
      newQuoteToken?: Address | Address[] | null
    }
```

Indexed argument values to filter logs by.

### batch

* **Type:** `boolean`
* **Default:** `true`

Whether to batch the logs found within a poll interval into a single emission. When `false`, each log is emitted on its own.

### fromBlock

* **Type:** `bigint`

Block number from which to start watching for logs.

### poll

* **Type:** `boolean`

Whether to poll for new logs instead of using a subscription. Defaults to `true` when the transport cannot subscribe or `fromBlock` is provided.

### pollingInterval

* **Type:** `number`
* **Default:** `client.pollingInterval`

Polling frequency (in ms).

### token

* **Type:** `Address | bigint`

Token to operate on: a TIP-20 token id or a contract address.