multicall

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

Usage

example.tsabi.tsclient.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' }
 * ]
 */

export const wagmiAbi = [
  ...
  {
    inputs: [],
    name: "totalSupply",
    outputs: [{ name: "", type: "uint256" }],
    stateMutability: "view",
    type: "function",
  },
  {
    inputs: [{ name: "tokenId", type: "uint256" }],
    name: "ownerOf",
    outputs: [{ name: "", type: "address" }],
    stateMutability: "view",
    type: "function",
  },
  {
    inputs: [],
    name: "mint",
    outputs: [],
    stateMutability: "view",
    type: "function",
  },
  ...
] as const;

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

export const publicClient = createPublicClient({
  chain: mainnet,
  transport: http()
})

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

Type: Address

The contract address.

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

contracts.abi

Type: 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 
})

account (optional)

Type: Account | Address

Optional Account sender override.

Accepts a JSON-RPC Account or Local Account (Private Key, etc).

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

batchSize (optional)

Type: number
Default: client.batch.multicall.batchSize (if set) or 1024

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 
})

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' 
})

Live Example

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

multicall ​

Usage ​

Return Value ​

Parameters ​

contracts.address ​

contracts.abi ​

contracts.functionName ​

contracts.args (optional) ​

allowFailure (optional) ​

account (optional) ​

batchSize (optional) ​

multicallAddress (optional) ​

Live Example ​