getLogs

Returns a list of event logs matching the provided parameters.

Usage

By default, getLogs returns all events. In practice, you must use scoping to filter for specific events.

example.ts

import { publicClient } from './client'
 
const logs = await publicClient.getLogs()  
Output: [{ ... }, { ... }, { ... }]

Scoping

You can also scope to a set of given attributes.

example.ts

import { parseAbiItem } from 'viem'
import { publicClient } from './client'
 
const logs = await publicClient.getLogs({  
  address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256)'),
  args: {
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  },
  fromBlock: 16330000n,
  toBlock: 16330050n
})

By default, event accepts the AbiEvent type:

example.ts

import { publicClient } from './client'
 
const logs = await publicClient.getLogs(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' }
    ] 
  },
  args: {
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
    to: '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac'
  },
  fromBlock: 16330000n,
  toBlock: 16330050n
})

Address

Logs can be scoped to an address:

example.ts

import { publicClient } from './client'
 
const logs = await publicClient.getLogs({
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2'
})

Event

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

example.ts

import { parseAbiItem } from 'viem'
import { publicClient } from './client'
 
const logs = await publicClient.getLogs({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'), 
})

Arguments

Logs can be scoped to given indexed arguments:

import { parseAbiItem } from 'viem'
 
const logs = await publicClient.getLogs({
  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.

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

import { parseAbiItem } from 'viem'
 
const logs = await publicClient.getLogs({
  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

Logs can be scoped to a block range:

import { parseAbiItem } from 'viem'
 
const logs = await publicClient.getLogs({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  fromBlock: 16330000n, 
  toBlock: 16330050n
})

Multiple Events

Logs can be scoped to multiple events:

import { parseAbi } from 'viem'
 
const logs = await publicClient.getLogs({
  events: parseAbi([ 
    'event Approval(address indexed owner, address indexed sender, uint256 value)',
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ]),
})

Note: Logs scoped to multiple events cannot be also scoped with indexed arguments (args).

Strict Mode

By default, getLogs 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.

import { parseAbiItem } from 'viem' 
 
const logs = await publicClient.getLogs({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)')
})
 
logs[0].
args: {
    from?: `0x${string}` | undefined;
    to?: `0x${string}` | undefined;
    value?: bigint | undefined;
}args

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.

import { parseAbiItem } from 'viem' 
 
const logs = await publicClient.getLogs({
  address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  strict: true
})
 
logs[0].
args: {
    from: `0x${string}`;
    to: `0x${string}`;
    value: bigint;
}args

Returns

Log[]

A list of event logs.

Parameters

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.getLogs({
  address: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', 
})

event

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 logs = await publicClient.getLogs({
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'), 
})

args

Type: Inferred.

A list of indexed event arguments.

import { parseAbiItem } from 'viem'
 
const logs = await publicClient.getLogs({
  event: parseAbiItem('event Transfer(address indexed from, address indexed to, uint256 value)'),
  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.createEventFilter({
  fromBlock: 69420n
})

toBlock

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

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

const filter = await publicClient.createEventFilter({
  toBlock: 70120n
})

blockHash

Type: '0x${string}'

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

const logs = await publicClient.getLogs({
  blockHash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d'
})

Live Example

Check out the usage of getLogs in the live Event Logs Example below.

JSON-RPC Method

eth_getLogs