watchContractEvent ​

Watches and returns emitted contract event logs.

This Action will batch up all the event logs found within the pollingInterval, and invoke them via onLogs.

watchContractEvent will attempt to create an Event Filter and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (ie. eth_newFilter), then watchContractEvent will fall back to using getLogs instead.

Usage ​

import { publicClient } from './client'
import { wagmiAbi } from './abi'

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  onLogs: logs => console.log(logs)
})
// > [{ ... }, { ... }, { ... }]
// > [{ ... }, { ... }]
// > [{ ... }, { ... }, { ... }, { ... }]

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})

Scoping to an Event Name ​

You can scope to an event on the given ABI.

import { publicClient } from './client'
import { wagmiAbi } from './abi'

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer',
  onLogs: logs => console.log(logs)
})
// > [{ ... }, { ... }, { ... }]
// > [{ ... }, { ... }]
// > [{ ... }, { ... }, { ... }, { ... }]

export const wagmiAbi = [
  ...
  {
    inputs: [
      {
        indexed: true,
        name: "from",
        type: "address",
      },
      { indexed: true, name: "to", type: "address" },
      {
        indexed: true,
        name: "tokenId",
        type: "uint256",
      },
    ],
    name: "Transfer",
    type: "event",
  },
  ...
] as const;

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})

Scoping to Event Arguments ​

You can scope to given indexed event arguments.

In the example below, we want to filter out Transfers that were sent by the address "0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b".

Only indexed arguments on the event ABI are candidates for args (see abi.ts).

import { publicClient } from './client'
import { wagmiAbi } from './abi'

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer',
  args: { from: '0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b' },
  onLogs: logs => console.log(logs)
})
// > [{ ... }, { ... }, { ... }]
// > [{ ... }, { ... }]
// > [{ ... }, { ... }, { ... }, { ... }]

export const wagmiAbi = [
  ...
  {
    inputs: [
      {
        indexed: true,
        name: "from",
        type: "address",
      },
      { 
        indexed: true, 
        name: "to", 
        type: "address" 
      },
      {
        indexed: false,
        name: "tokenId",
        type: "uint256",
      },
    ],
    name: "Transfer",
    type: "event",
  },
  ...
] as const;

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})

Returns ​

UnwatchFn

A function that can be invoked to stop watching for new event logs.

Arguments ​

abi ​

• Type: Abi

The contract's ABI.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi, 
  onLogs: logs => console.log(logs)
})

onLogs ​

• Type: (Log[]) => void

The new event logs.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  onLogs: logs => console.log(logs) 
})

address (optional) ​

• Type: Address

The contract address. If no address is provided, then it will emit all events matching the event signatures on the ABI.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', 
  abi: wagmiAbi,
  onLogs: logs => console.log(logs)
})

args (optional) ​

• Type: Inferred from ABI.

Event arguments to filter logs.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer', 
  args: ['0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b'], 
  onLogs: logs => console.log(logs)
})

eventName (optional) ​

• Type: string

An event name to filter logs.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  eventName: 'Transfer', 
  onLogs: logs => console.log(logs)
})

batch (optional) ​

• Type: boolean
• Default: true

Whether or not to batch logs between polling intervals.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  batch: false, 
  onLogs: logs => console.log(logs)
})

onError (optional) ​

• Type: (error: Error) => void

Error thrown from listening for new event logs.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  onError: error => console.log(error), 
  onLogs: logs => console.log(logs)
})

poll (optional) ​

• Type: boolean
• Default: false for WebSocket Clients, true for non-WebSocket Clients

Whether or not to use a polling mechanism to check for new logs instead of a WebSocket subscription.

This option is only configurable for Clients with a WebSocket Transport.

import { createPublicClient, webSocket } from 'viem'
import { mainnet } from 'viem/chains'

const publicClient = createPublicClient({
  chain: mainnet,
  transport: webSocket()
})

const unwatch = publicClient.watchContractEvent(
  { 
    address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
    abi: wagmiAbi,
    poll: true, 
  }
)

pollingInterval (optional) ​

• Type: number

Polling frequency (in ms). Defaults to the Client's pollingInterval config.

const unwatch = publicClient.watchContractEvent({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  pollingInterval: 1_000, 
  onLogs: logs => console.log(logs)
})

JSON-RPC Methods ​

When poll true and RPC Provider supports eth_newFilter:

• Calls eth_newFilter to create a filter (called on initialize).
• On a polling interval, it will call eth_getFilterChanges.

When poll true RPC Provider does not support eth_newFilter:

• Calls eth_getLogs for each block between the polling interval.

When poll false and WebSocket Transport:

• Uses a WebSocket subscription via eth_subscribe and the "logs" event.