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.

Import #

import { readContract } from 'viem'

Usage #

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

import { readContract } from 'viem'
import { publicClient } from './client'
import { wagmiAbi } from './abi'

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

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

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

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

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 { readContract } from 'viem'
import { publicClient } from './client'
import { wagmiAbi } from './abi'

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

export const wagmiAbi = [
  ...
  {
    inputs: [{ name: "owner", type: "address" }],
    name: "balanceOf",
    outputs: [{ name: "", type: "uint256" }],
    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 #

The response from the contract. Type is inferred.

Parameters #

address #

• Type: Address

The contract address.

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

abi #

• Type: Abi

The contract's ABI.

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

functionName #

• Type: string

A function to extract from the ABI.

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

args (optional) #

• Type: Inferred from ABI.

Arguments to pass to function call.

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

from (optional) #

• Type: Address

Optional sender override.

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

blockNumber (optional) #

• Type: number

The block number to perform the read against.

const data = await readContract(publicClient, {
  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 readContract(publicClient, {
  address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2',
  abi: wagmiAbi,
  functionName: 'totalSupply',
  blockTag: 'safe', 
})