createEventFilter
Creates a Filter to listen for new events that can be used with getFilterChanges.
Usage
By default, an Event Filter with no arguments will query for/listen to all events.
import { publicClient } from './client'
const filter = await publicClient.createEventFilter()
// { id: "0x345a6572337856574a76364e457a4366", type: 'event' }
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
export const publicClient = createPublicClient({
chain: mainnet,
transport: http()
})
Scoping
You can also scope a Filter to a set of given attributes (listed below).
Address
A Filter can be scoped to an address:
import { publicClient } from './client'
const filter = await publicClient.createEventFilter({
address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2'
})
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
export const publicClient = createPublicClient({
chain: mainnet,
transport: http()
})
Event
A Filter can be scoped to an event.
The event argument takes in an event in ABI format – we have a parseAbiItem utility that you can use to convert from a human-readable event signature → ABI.
import { parseAbiItem } from 'viem'
import { publicClient } from './client'
const filter = await publicClient.createEventFilter({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
})
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
export const publicClient = createPublicClient({
chain: mainnet,
transport: http()
})
By default, event accepts the AbiEvent type:
import { publicClient } from './client'
const filter = await publicClient.createEventFilter(publicClient, {
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: {
name: 'Transfer',
inputs: [
{ type: 'address', indexed: true, name: 'from' },
{ type: 'address', indexed: true, name: 'to' },
{ type: 'uint256', indexed: false, name: 'value' }
]
}
})
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'
export const publicClient = createPublicClient({
chain: mainnet,
transport: http()
})
Arguments
A Filter can be scoped to given indexed arguments:
const filter = await publicClient.createEventFilter({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
args: {
from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
}
})
Only indexed arguments in event are candidates for args.
A Filter Argument can also be an array to indicate that other values can exist in the position:
const filter = await publicClient.createEventFilter({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
args: {
// '0xd8da...' OR '0xa5cc...' OR '0xa152...'
from: [
'0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
'0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
'0xa152f8bb749c55e9943a3a0a3111d18ee2b3f94e',
],
}
})
Block Range
A Filter can be scoped to a block range:
const filter = await publicClient.createEventFilter({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
fromBlock: 16330000n,
toBlock: 16330050n
})
Returns
Parameters
address (optional)
- Type:
Address | Address[]
The contract address or a list of addresses from which Logs should originate.
const filter = await publicClient.createEventFilter({
address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2'
})
event (optional)
- Type:
AbiEvent
The event in ABI format.
A parseAbiItem utility is exported from viem that converts from a human-readable event signature → ABI.
import { parseAbiItem } from 'viem'
const filter = await publicClient.createEventFilter({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
})
args (optional)
- Type: Inferred.
A list of indexed event arguments.
const filter = await publicClient.createEventFilter({
address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
args: {
from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
}
})
fromBlock (optional)
- Type:
bigint
Block to start querying/listening from.
const filter = await publicClient.createEventFilter({
fromBlock: 69420n
})
toBlock (optional)
- Type:
bigint
Block to query/listen until.
const filter = await publicClient.createEventFilter({
fromBlock: 70120n
})