Skip to content

multicall

Batches up multiple functions on a contract in a single call.

Similar to readContract, but batches up multiple functions on a contract in a single RPC call via the multicall3 contract.

Usage

example.ts
import { publicClient } from './client'
import { wagmiAbi } from './abi'
 
const wagmiContract = {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi
} as const
 
const results = await publicClient.multicall({
  contracts: [
    {
      ...wagmiContract,
      functionName: 'totalSupply',
    },
    {
      ...wagmiContract,
      functionName: 'ownerOf',
      args: [69420n]
    },
    {
      ...wagmiContract,
      functionName: 'mint'
    }
  ]
})
/**
 * [
 *  { result: 424122n, status: 'success' },
 *  { result: '0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b', status: 'success' },
 *  { error: [ContractFunctionExecutionError: ...], status: 'failure' }
 * ]
 */

Return Value

({ data: <inferred>, status: 'success' } | { error: string, status: 'reverted' })[]

An array of results with accompanying status.

Additionally, when allowFailure is set to false, it directly returns an array of inferred data:

(<inferred>)[]

Parameters

contracts.address

The contract address.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', 
      abi: wagmiAbi,
      functionName: 'totalSupply',
    },
    ...
  ]
})

contracts.abi

The contract ABI.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi, 
      functionName: 'totalSupply',
    },
    ...
  ]
})

contracts.functionName

  • Type: string

The function name to call.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi,
      functionName: 'totalSupply', 
    },
    ...
  ]
})

contracts.args (optional)

  • Type: Inferred from ABI.

Arguments to pass to function call.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi,
      functionName: 'balanceOf',
      args: ['0xc961145a54C96E3aE9bAA048c4F4D6b04C13916b'] 
    },
    ...
  ]
})

allowFailure (optional)

  • Type: boolean
  • Default: true

Whether or not the multicall function should throw if a call reverts. If set to true (default), and a call reverts, then multicall will fail silently and its error will be logged in the results array.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi,
      functionName: 'totalSupply',
    },
    ...
  ],
  allowFailure: false
})

batchSize (optional)

The maximum size (in bytes) for each calldata chunk. Set to 0 to disable the size limit.

Note: Some RPC Providers limit the amount of calldata (data) that can be sent in a single eth_call request. It is best to check with your RPC Provider to see if there are any calldata size limits to eth_call requests.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi,
      functionName: 'totalSupply',
    },
    ...
  ],
  batchSize: 4096 // 4kB
})

blockNumber (optional)

  • Type: number

The block number to perform the read against.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi,
      functionName: 'totalSupply',
    },
    ...
  ],
  blockNumber: 15121123n, 
})

multicallAddress (optional)

  • Type: Address
  • Default: client.chain.contracts.multicall3.address

Address of Multicall Contract.

const results = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi,
      functionName: 'totalSupply',
    },
    ...
  ],
  multicallAddress: '0xca11bde05977b3631167028862be2a173976ca11'
})

stateOverride (optional)

The state override set is an optional address-to-state mapping, where each entry specifies some state to be ephemerally overridden prior to executing the call.

const data = await publicClient.multicall({
  contracts: [
    {
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
      abi: wagmiAbi,
      functionName: 'totalSupply',
    },
    ...
  ],
  stateOverride: [ 
    { 
      address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC', 
      balance: parseEther('1'), 
      stateDiff: [ 
        { 
          slot: '0x3ea2f1d0abf3fc66cf29eebb70cbd4e7fe762ef8a09bcc06c8edf641230afec0', 
          value: '0x00000000000000000000000000000000000000000000000000000000000001a4', 
        }, 
      ], 
    } 
  ], 
})

Live Example

Check out the usage of multicall in the live Multicall Example below.