getContractEvents

Returns a list of contract event logs matching the provided parameters.

Usage

By default, getContractEvents returns all matched events on the ABI. In practice, you must use scoping to filter for specific events.

example.ts

import { publicClient } from './client'
import { erc20Abi } from './abi'
 
// Fetch event logs for every event on every ERC-20 contract.
const logs = await publicClient.getContractEvents({ 
  abi: erc20Abi 
})
// [{ ... }, { ... }, { ... }]

Scoping

You can also scope to a set of given attributes.

example.ts

import { parseAbiItem } from 'viem'
import { publicClient } from './client'
import { erc20Abi } from './abi'
 
const usdcContractAddress = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
 
const logs = await publicClient.getContractEvents({ 
  address: usdcContractAddress,
  abi: erc20Abi,
  eventName: 'Transfer',
  args: {
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  },
  fromBlock: 16330000n,
  toBlock: 16330050n
})

Address

Logs can be scoped to an address:

example.ts

import { publicClient } from './client'
import { erc20Abi } from './abi'
 
const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2', 
})

Event

Logs can be scoped to an event.

example.ts

import { parseAbiItem } from 'viem'
import { publicClient } from './client'
import { erc20Abi } from './abi'
 
const logs = await publicClient.getContractEvents({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  abi: erc20Abi,
  eventName: 'Transfer', 
})

Arguments

Logs can be scoped to given indexed arguments:

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  eventName: 'Transfer',
  args: { 
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  }
})

Only indexed arguments in event are candidates for args.

An argument can also be an array to indicate that other values can exist in the position:

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  eventName: 'Transfer',
  args: { 
    // '0xd8da...' OR '0xa5cc...' OR '0xa152...'
    from: [
      '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', 
      '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
      '0xa152f8bb749c55e9943a3a0a3111d18ee2b3f94e',
    ],
  }
})

Block Range

Logs can be scoped to a block range:

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  eventName: 'Transfer',
  fromBlock: 16330000n, 
  toBlock: 16330050n
})

Strict Mode

By default, getContractEvents will include logs that do not conform to the indexed & non-indexed arguments on the event. viem will not return a value for arguments that do not conform to the ABI, thus, some arguments on args may be undefined.

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  eventName: 'Transfer',
})
 
logs[0].args 
//      ^? { address?: Address, to?: Address, value?: bigint }

You can turn on strict mode to only return logs that conform to the indexed & non-indexed arguments on the event, meaning that args will always be defined. The trade-off is that non-conforming logs will be filtered out.

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  eventName: 'Transfer',
  strict: true
})
 
logs[0].args 
//      ^? { address: Address, to: Address, value: bigint }

Returns

Log[]

A list of event logs.

Parameters

abi

Type: Abi

The contract's ABI.

const logs = await publicClient.getContractEvents({
  abi: erc20Abi, 
})

address

Type: Address | Address[]

A contract address or a list of contract addresses. Only logs originating from the contract(s) will be included in the result.

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
})

eventName

Type: string

An event name on the abi.

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  eventName: 'Transfer'
})

args

Type: Inferred.

A list of indexed event arguments.

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  eventName: 'Transfer',
  args: { 
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  },
})

fromBlock

Type: bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'

Block to start including logs from. Mutually exclusive with blockHash.

const filter = await publicClient.getContractEvents({
  abi: erc20Abi,
  fromBlock: 69420n
})

toBlock

Type: bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'

Block to stop including logs from. Mutually exclusive with blockHash.

const filter = await publicClient.getContractEvents({
  abi: erc20Abi,
  toBlock: 70120n
})

blockHash

Type: '0x${string}'

Block hash to include logs from. Mutually exclusive with fromBlock/toBlock.

const logs = await publicClient.getContractEvents({
  abi: erc20Abi,
  blockHash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d'
})

JSON-RPC Method

eth_getLogs