Appearance

useContractEvents ​

Hook that fetches a list of contract event logs matching the provided parameters.

Import ​

ts
import { useContractEvents } from 'wagmi'

Usage ​

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

tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'

function App() {
  // Fetch event logs for every event on every ERC-20 contract. 
  const result = useContractEvents({ abi })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Parameters ​

ts
import { type UseContractEventsParameters } from 'wagmi'

abi ​

Abi

The contract's ABI. Check out the TypeScript docs for how to set up ABIs for maximum type inference and safety.

tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'

function App() {
 const result = useContractEvents({
    abi,
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

address ​

Address | undefined

The contract's address.

tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'

function App() {
  const result = useContractEvents({
    address: '0x6b175474e89094c44da98b954eedeac495271d0f',
    abi,
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

args ​

object | readonly unknown[] | undefined

  • Logs can be scoped to given indexed arguments.
  • Inferred from abi and eventName.
tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'

function App() {
  const result = useContractEvents({
    abi,
    eventName: 'Transfer',
    args: {
      from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
      to: '0xd2135CfB216b74109775236E36d4b433F1DF507B'
    }
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

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:

tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'

function App() {
  const result = useContractEvents({
    abi,
    eventName: 'Transfer',
    args: { 
      from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', 
      to: [
        '0xd2135CfB216b74109775236E36d4b433F1DF507B',
        '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac',
        '0xa152f8bb749c55e9943a3a0a3111d18ee2b3f94e',
    ],
    }
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

blockHash ​

`0x${string}` | undefined

  • Block hash to include logs from. Mutually exclusive with fromBlock/toBlock.
tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'

function App() {
  const result = useContractEvents({
    abi,
    blockHash: '0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d',
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

chainId ​

config['chains'][number]['id'] | undefined

ID of chain to use when fetching data.

tsx
import { useContractEvents } from 'wagmi'
import { mainnet } from '@wagmi/core/chains'
import { abi } from './abi'

function App() {
  const result = useContractEvents({
    abi,
    chainId: mainnet.id,
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

config ​

Config | undefined

Config to use instead of retrieving from the nearest WagmiProvider.

tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'
import { config } from './config'

function App() {
  const result = useContractEvents({
    abi,
    config,
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

eventName ​

string | undefined

  • Event to filter for the contract.
  • Inferred from abi.
tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'
import { config } from './config'

function App() {
  const result = useContractEvents({
    abi,
    eventName: 'Transfer',
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

fromBlock ​

bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized' | undefined

  • Block to start including logs from. Mutually exclusive with blockHash.
tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'
import { config } from './config'

function App() {
  const result = useContractEvents({
    abi,
    fromBlock: 69420n,
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

strict ​

boolean | undefined

  • Flag to only return logs that conform to the indexed & non-indexed arguments on the event, meaning that args will always be defined. Defaults to false.
tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'
import { config } from './config'

function App() {
  const result = useContractEvents({
    abi,
    strict: true,
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

toBlock ​

bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized' | undefined

  • Block to stop including logs from. Mutually exclusive with blockHash.
tsx
import { useContractEvents } from 'wagmi'
import { abi } from './abi'
import { config } from './config'

function App() {
  const result = useContractEvents({
    abi,
    toBlock: 70120n,
  })
}
ts
export const abi = [
  {
    type: 'event',
    name: 'Approval',
    inputs: [
      { indexed: true, name: 'owner', type: 'address' },
      { indexed: true, name: 'spender', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
  {
    type: 'event',
    name: 'Transfer',
    inputs: [
      { indexed: true, name: 'from', type: 'address' },
      { indexed: true, name: 'to', type: 'address' },
      { indexed: false, name: 'value', type: 'uint256' },
    ],
  },
] as const
ts
import { createConfig, http } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Return Type ​

ts
import { type UseContractEventsReturnType } from 'wagmi'

A list of event logs.

Action ​

Released under the MIT License.

Copyright © 2022-present Weth, LLC