> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# contract.read

## Overview

Use [`contract.read.<name>`](#contractread) to read state without sending a transaction.

The group contains one method for each `pure` or `view` function in the bound ABI.

Each method calls [`Actions.contract.read`](/docs/actions/public/contract/read) with the ABI, address, and function name supplied by the contract instance.

## Recipes

### Pass Function Arguments

Pass ABI function inputs as the first parameter. The ABI determines the tuple's order and types.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})

const balance = await contract.read.balanceOf([ // [!code focus]
  '0x0000000000000000000000000000000000000000', // [!code focus]
]) // [!code focus]
// @log: 0n
```

### Call a Function Without Inputs

Omit the arguments array when the ABI function has no inputs.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})

const name = await contract.read.name() // [!code focus]
// @log: 'USD Coin'
```

### Read a Specific Block

Pass `blockTag` to read state from a named block instead of the latest block.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})

const name = await contract.read.name({
  blockTag: 'finalized', // [!code focus]
})
// @log: 'USD Coin'
```

## `contract.read`

Calls a read-only contract function and returns its decoded result.

### Usage

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })

const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})

const balance = await contract.read.balanceOf([ // [!code focus]
  '0x0000000000000000000000000000000000000000', // [!code focus]
]) // [!code focus]
// @log: 0n
```

### Parameters

#### args

* **Type:** Inferred from the ABI function.

The function inputs as a positional tuple. Omit this parameter when the function has no inputs.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const balance = await contract.read.balanceOf([ // [!code focus]
  '0x0000000000000000000000000000000000000000', // [!code focus]
]) // [!code focus]
```

Use supported [read options](/docs/actions/public/contract/read#parameters) for block selection and
call context. Pass options second when the function has inputs, or first when it has none.

The instance supplies the contract address. Do not pass `code`; a contract instance always calls
its bound address.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })

const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({ // [!code focus]
  blockTag: 'finalized', // [!code focus]
}) // [!code focus]
```

#### options.account

* **Type:** `Account | Address`
* **Default:** `client.account`

Sets the call's `msg.sender`. This option does not sign or send a transaction.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const balance = await contract.read.balanceOf(
  ['0x0000000000000000000000000000000000000000'],
  {
    account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // [!code focus]
  },
)
```

#### options.as

* **Type:** `'Object' | 'Array'`
* **Default:** `'Object'`

Returns multiple named outputs as an object or positional array. Fully unnamed outputs remain
arrays.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abi } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abi.from([
    'function metadata() view returns (string name, string symbol)',
  ]),
  address: '0x0000000000000000000000000000000000000000',
  client,
})
// ---cut---
const [name, symbol] = await contract.read.metadata({
  as: 'Array', // [!code focus]
})
```

#### options.authorizationList

* **Type:** `AuthorizationList`
* **Optional**

Attaches a signed EIP-7702 authorization list to the call.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  authorizationList: [ // [!code focus]
    { // [!code focus]
      address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', // [!code focus]
      chainId: 1, // [!code focus]
      nonce: 0n, // [!code focus]
      r: '0x...', // [!code focus]
      s: '0x...', // [!code focus]
      yParity: 0, // [!code focus]
    }, // [!code focus]
  ], // [!code focus]
})
```

#### options.blockHash

* **Type:** `Hex`
* **Optional**

Reads state at the block with this hash. This option cannot be combined with `blockNumber` or
`blockTag`.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d', // [!code focus]
})
```

#### options.blockNumber

* **Type:** `bigint`
* **Optional**

Reads state at this block number. This option cannot be combined with `blockHash` or `blockTag`.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  blockNumber: 20_000_000n, // [!code focus]
})
```

#### options.blockOverrides

* **Type:** `BlockOverrides`
* **Optional**

Overrides block fields for this call. The RPC provider must support block overrides.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  blockOverrides: { // [!code focus]
    baseFeePerGas: 1_000_000_000n, // [!code focus]
  }, // [!code focus]
})
```

#### options.blockTag

* **Type:** `'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'`
* **Default:** `client.blockTag ?? 'latest'`

Reads state at the named block. This option cannot be combined with `blockHash` or `blockNumber`.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  blockTag: 'safe', // [!code focus]
})
```

#### options.factory

* **Type:** `Address`
* **Optional**

Sets the deployment factory for a counterfactual call. Pass `factoryData` with this option.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  factory: '0xE8Df82fA4E10e6A12a9Dab552bceA2acd26De9bb', // [!code focus]
  factoryData: '0x...',
})
```

#### options.factoryData

* **Type:** `Hex`
* **Optional**

Sets the calldata that the deployment factory executes. Pass `factory` with this option.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  factory: '0xE8Df82fA4E10e6A12a9Dab552bceA2acd26De9bb',
  factoryData: '0x...', // [!code focus]
})
```

#### options.requestOptions

* **Type:** `{ dedupe?: boolean; signal?: AbortSignal; ... }`
* **Optional**

Passes transport options to the underlying JSON-RPC request.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const controller = new AbortController()
const name = await contract.read.name({
  requestOptions: { signal: controller.signal }, // [!code focus]
})
```

#### options.requireCanonical

* **Type:** `boolean`
* **Default:** `false`

Requires `blockHash` to identify a block on the canonical chain.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d',
  requireCanonical: true, // [!code focus]
})
```

#### options.stateOverride

* **Type:** `StateOverrides`
* **Optional**

Overrides account balance, code, nonce, or storage for this call. The RPC provider must support
state overrides.

```ts twoslash
import { Client, Contract, http } from 'viem'
import { mainnet } from 'viem/chains'
import { Abis } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const name = await contract.read.name({
  stateOverride: { // [!code focus]
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045': { // [!code focus]
      balance: 1_000_000_000_000_000_000n, // [!code focus]
    }, // [!code focus]
  }, // [!code focus]
})
```

### Return Value

`Promise<Actions.contract.read.ReturnType>`

The decoded function result. The ABI function determines its type.

### Errors

| Error | Description |
| --- | --- |
| `ContractError.ContractFunctionExecutionError` | The contract function failed. Its cause contains decoded revert or zero-data details when available. |