readContract

Calls a read-only function on a contract, and returns the response.

A "read-only" function (constant function) on a Solidity contract is denoted by a view or pure keyword. They can only read the state of the contract, and cannot make any changes to it. Since read-only methods do not change the state of the contract, they do not require any gas to be executed, and can be called by any user without the need to pay for gas.

Internally, readContract uses a Public Client to call the call action with ABI-encoded data.

Usage

Below is a very basic example of how to call a read-only function on a contract (with no arguments).

example.ts

import { publicClient } from './client'
import { wagmiAbi } from './abi'
 
const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
})
// 69420n

Passing Arguments

If your function requires argument(s), you can pass them through with the args attribute.

TypeScript types for args will be inferred from the function name & ABI, to guard you from inserting the wrong values.

For example, the balanceOf function name below requires an address argument, and it is typed as ["0x${string}"].

example.ts

import { publicClient } from './client'
import { wagmiAbi } from './abi'
 
const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'balanceOf',
  args: ['0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC']
})

Deployless Reads

It is possible to call a function on a contract that has not been deployed yet. For instance, we may want to call a function on an ERC-4337 Smart Account contract which has not been deployed.

Viem offers two ways of performing a Deployless Call, via:

Bytecode
a Deploy Factory: "temporarily deploys" a contract with a provided Deploy Factory, and calls the function on the deployed contract.

Bytecode

The example below demonstrates how we can utilize a Deployless Call via Bytecode to call the name function on the Wagmi Example ERC721 contract which has not been deployed:

example.ts

import { parseAbi } from 'viem'
import { publicClient } from './config'
 
const data = await publicClient.readContract({
  abi: parseAbi(['function name() view returns (string)']),
  code: '0x...', // Accessible here: https://etherscan.io/address/0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2#code
  functionName: 'name'
})

Deploy Factory

The example below demonstrates how we can utilize a Deployless Call via a Deploy Factory to call the entryPoint function on an ERC-4337 Smart Account which has not been deployed:

example.ts

import { encodeFunctionData, parseAbi } from 'viem'
import { account, publicClient } from './config'
 
const data = await publicClient.readContract({
  // Address of the Smart Account deployer (factory).
  factory: '0xE8Df82fA4E10e6A12a9Dab552bceA2acd26De9bb',
 
  // Function to execute on the factory to deploy the Smart Account.
  factoryData: encodeFunctionData({
    abi: parseAbi(['function createAccount(address owner, uint256 salt)']),
    functionName: 'createAccount',
    args: [account, 0n],
  }),
 
  // Function to call on the Smart Account.
  abi: account.abi,
  address: account.address,
  functionName: 'entryPoint',
})

Return Value

The response from the contract. Type is inferred.

Parameters

address

Type: Address

The contract address.

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', 
  abi: wagmiAbi,
  functionName: 'totalSupply',
})

abi

Type: Abi

The contract's ABI.

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi, 
  functionName: 'totalSupply',
})

functionName

Type: string

A function to extract from the ABI.

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply', 
})

args (optional)

Type: Inferred from ABI.

Arguments to pass to function call.

const data = await publicClient.readContract({
  address: '0x1dfe7ca09e99d10835bf73044a23b73fc20623df',
  abi: wagmiAbi,
  functionName: 'balanceOf',
  args: ['0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC'] 
})

account (optional)

Type: Account | Address

Optional Account sender override.

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

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
  account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
})

blockNumber (optional)

Type: number

The block number to perform the read against.

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
  blockNumber: 15121123n, 
})

blockTag (optional)

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

The block tag to perform the read against.

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
  blockTag: 'safe', 
})

factory (optional)

Type:

Contract deployment factory address (ie. Create2 factory, Smart Account factory, etc).

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
  factory: '0x0000000000ffe8b47b3e2130213b802212439497', 
  factoryData: '0xdeadbeef',
})## Errors were thrown in the sample, but not included in an error tag

These errors were not marked as being expected: 2304. 
Expected: // @errors: 2304

Compiler Errors:

index.ts
  [2304] 19 - Cannot find name 'publicClient'.
  [2304] 111 - Cannot find name 'wagmiAbi'.

factoryData (optional)

Type:

Calldata to execute on the factory to deploy the contract.

const data = await publicClient.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
  factory: '0x0000000000ffe8b47b3e2130213b802212439497',
  factoryData: '0xdeadbeef', 
})## Errors were thrown in the sample, but not included in an error tag

These errors were not marked as being expected: 2304. 
Expected: // @errors: 2304

Compiler Errors:

index.ts
  [2304] 19 - Cannot find name 'publicClient'.
  [2304] 111 - Cannot find name 'wagmiAbi'.

stateOverride (optional)

Type: StateOverride

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.readContract({
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
  stateOverride: [ 
    { 
      address: '0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC', 
      balance: parseEther('1'), 
      stateDiff: [ 
        { 
          slot: '0x3ea2f1d0abf3fc66cf29eebb70cbd4e7fe762ef8a09bcc06c8edf641230afec0', 
          value: '0x00000000000000000000000000000000000000000000000000000000000001a4', 
        }, 
      ], 
    } 
  ], 
})

Live Example

Check out the usage of readContract in the live Reading Contracts Example below.