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

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}"].

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

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

Live Example

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