Batch reads with Multicall3

In this guide you read token balances, token metadata and a native balance in a single RPC request, using Multicall3 and viem.

How it works

Multicall3 is a contract that takes a list of calls, runs each one, and returns all the results together. viem wraps it: you pass an array of reads to multicall, and viem sends them as one eth_call to Multicall3’s aggregate3 function. Fewer requests mean faster pages and less chance of hitting RPC rate limits. BOT Chain’s Multicall3 is at the same address on both networks:

Network	Address
Mainnet	`0x47FA21f684bBAD707A53a0f9BE59F1422F46C265`
Testnet	`0x47FA21f684bBAD707A53a0f9BE59F1422F46C265`

The standard Multicall3 address, 0xcA11bde05977b3631167028862bE2a173976CA11, exists on mainnet but not on testnet. Tools that assume it will fail on testnet. See Known limitations.

What you’ll build

A script that reads five values in one request, including one call that fails on purpose, and handles each result on its own.

Prerequisites

Node.js 22 or later.

Steps

Create the project

mkdir bot-multicall
cd bot-multicall
npm init -y
npm pkg set type=module
npm install viem @uzolabs/sdk
npm install -D tsx

The chain objects in @uzolabs/sdk/chains already set contracts.multicall3 to BOT Chain’s address, so viem knows where to send the batch.

Write the script

multicall.ts

import { createPublicClient, erc20Abi, formatEther, formatUnits, http, parseAbi } from "viem";
import { botChainTestnet } from "@uzolabs/sdk/chains";
import { getAddresses } from "@uzolabs/sdk/contracts";

const client = createPublicClient({ chain: botChainTestnet, transport: http() });
const { usdt, wbot } = getAddresses(botChainTestnet.id);
const multicall3 = botChainTestnet.contracts.multicall3.address;
const holder = "0xEc526474F4F9De027942d5f7118A9613266B0C4c";

// Multicall3 can also read native balances, so tBOT fits in the same batch.
const multicall3Abi = parseAbi(["function getEthBalance(address addr) view returns (uint256)"]);

const results = await client.multicall({
  contracts: [
    { address: usdt, abi: erc20Abi, functionName: "symbol" },
    { address: usdt, abi: erc20Abi, functionName: "decimals" },
    { address: usdt, abi: erc20Abi, functionName: "balanceOf", args: [holder] },
    { address: wbot, abi: erc20Abi, functionName: "balanceOf", args: [holder] },
    { address: multicall3, abi: multicall3Abi, functionName: "getEthBalance", args: [holder] },
    // This one fails on purpose: the holder is a wallet, not a token.
    { address: holder, abi: erc20Abi, functionName: "decimals" },
  ],
});

const [symbol, decimals, usdtBalance, wbotBalance, tbotBalance, broken] = results;
if (symbol.status === "success" && decimals.status === "success" && usdtBalance.status === "success") {
  console.log(`${symbol.result}: ${formatUnits(usdtBalance.result, decimals.result)}`);
}
if (wbotBalance.status === "success") console.log(`WBOT: ${formatEther(wbotBalance.result)}`);
if (tbotBalance.status === "success") console.log(`tBOT: ${formatEther(tbotBalance.result)}`);
console.log(`Last call: ${broken.status}`);

const blockNumber = await client.getBlockNumber();
console.log(`Sent through ${multicall3} at block ${blockNumber}`);

Replace holder with your own address.Each item in results has a status. A failed call returns status: "failure" and an error, and the other calls still succeed. Checking status also narrows the type of result, so TypeScript knows usdtBalance.result is a bigint.

Run it

npx tsx multicall.ts

Verify it worked

Output from a run on testnet on 2026-10-02:

Output

USDT: 0.020366
WBOT: 0
tBOT: 0.000313799982351838
Last call: failure
Sent through 0x47FA21f684bBAD707A53a0f9BE59F1422F46C265 at block 25429267

To confirm the batch is one request, log what the transport sends:

multicall.ts

const client = createPublicClient({
  chain: botChainTestnet,
  transport: http(undefined, { onFetchRequest: async (request) => console.log(await request.clone().text()) }),
});

The six reads appear as a single eth_call whose data starts with 0x82ad56cb, the selector of aggregate3.

Options

Option	Default	Use it to
`allowFailure`	`true`	Set `false` to throw on the first failed call and get plain values back instead of `{ status, result }` objects.
`batchSize`	`1024`	Split very large batches into several requests. The size is in bytes of calldata.
`blockNumber`	latest	Read every call at the same past block.
`multicallAddress`	from the chain	Point at Multicall3 when your chain object doesn’t define it.

To batch reads automatically without calling multicall yourself, create the client with batch: { multicall: true }. viem then groups readContract calls made in the same tick into one Multicall3 request.

Troubleshooting

Chain does not support contract multicall3

Your chain object has no contracts.multicall3. Use botChainTestnet from @uzolabs/sdk/chains, add the address to your own defineChain, or pass multicallAddress. If the client has no chain at all, the error reads client chain not configured. multicallAddress is required.

Every call fails on testnet

You’re probably using the standard address 0xcA11...CA11, which has no code on testnet. Use 0x47FA21f684bBAD707A53a0f9BE59F1422F46C265.

One call fails and I don't know why

Log result.error.message for that item. Common causes are a wrong address, an address with no contract, or a function the contract doesn’t have.

The RPC rejects the request as too large

Lower batchSize, or split your list into several multicall calls.

Next steps

Read contract state

Batch reads in React with wagmi.

Use the BOTScan API

Query history the RPC can’t give you.

Development environment

Deploy and verify

Frontend

DeFi

Bridge

Gasless transactions

AI agents

Data and indexing

Batch reads with Multicall3

How it works

What you’ll build

Prerequisites

Steps

Verify it worked

Options

Troubleshooting

Next steps

Read contract state

Use the BOTScan API

​How it works

​What you’ll build

​Prerequisites

​Steps

​Verify it worked

​Options

​Troubleshooting

​Next steps

Read contract state

Use the BOTScan API

How it works

What you’ll build

Prerequisites

Steps

Verify it worked

Options

Troubleshooting

Next steps