> **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.estimateGas

## Overview

Use [`contract.estimateGas.<functionName>`](#contractestimategas) to estimate the gas units for a contract write
function.

The group contains one method for each write function in the contract's ABI.

Each method calls
[`Actions.contract.estimateGas`](/docs/actions/public/contract/estimateGas) with the ABI, address,
and function name already bound.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  { account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
)
// @log: 56337n
```

## Recipes

### Estimate from a Sender

Pass an [Account](/docs/accounts) or address in the second parameter when gas usage depends on the transaction
sender.

```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 gas = await contract.estimateGas.approve(
  [
    '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
    1n,
  ],
  {
    account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // [!code focus]
  },
)
```

### Estimate a Payable Function

For a payable function without inputs, pass its options as the first parameter. Set `value` to the
amount of native currency sent by the call.

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

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

const contract = Contract.from({
  abi: Abi.from(['function deposit() payable']),
  address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  client,
})

const gas = await contract.estimateGas.deposit({ // [!code focus]
  account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  value: Value.fromEther('0.01'), // [!code focus]
}) // [!code focus]
```

### Estimate with Historical State Overrides

Select a historical block and temporarily override account state for one estimate. The RPC
provider must support state overrides at the selected 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 sender = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'

export function estimateWithBalance(
  blockNumber: bigint,
  balance: bigint,
) {
  return contract.estimateGas.approve(
    ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
    {
      account: sender,
      blockNumber, // [!code focus]
      stateOverride: { // [!code focus]
        [sender]: { balance }, // [!code focus]
      }, // [!code focus]
    },
  )
}
```

## `contract.estimateGas`

Estimates the gas units that a contract write function may use.

### 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  { account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
)
// @log: 56337n
```

### Parameters

#### args

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

The positional function arguments. This parameter is required for functions with inputs. Omit it
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 gas = await contract.estimateGas.approve(
  [ // [!code focus]
    '0x70997970c51812dc3a010c7d01b50e0d17dc79c8', // [!code focus]
    1n, // [!code focus]
  ], // [!code focus]
  { account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
)
```

The remaining [gas estimation options](/docs/actions/public/contract/estimateGas#parameters). Pass
this object first 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 gas = await contract.estimateGas.approve(
  [
    '0x70997970c51812dc3a010c7d01b50e0d17dc79c8',
    1n,
  ],
  { // [!code focus]
    account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // [!code focus]
  }, // [!code focus]
)
```

#### options.accessList

* **Type:** `AccessList`
* **Optional**

The EIP-2930 access list to attach to the estimation 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    accessList: [ // [!code focus]
      { // [!code focus]
        address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // [!code focus]
        storageKeys: [ // [!code focus]
          '0x0000000000000000000000000000000000000000000000000000000000000001', // [!code focus]
        ], // [!code focus]
      }, // [!code focus]
    ], // [!code focus]
  },
)
```

#### options.account

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

The account or address to use as `msg.sender`.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    account: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // [!code focus]
  },
)
```

#### options.authorizationList

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

The signed EIP-7702 authorization list to attach to the estimation 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    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.blobs

* **Type:** `readonly Hex[]`
* **Optional**

The EIP-4844 blobs to attach. Provide `kzg` to derive their versioned hashes.

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

declare const kzg: Kzg.Kzg

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    blobs: ['0x1234'], // [!code focus]
    kzg,
  },
)
```

#### options.blobVersionedHashes

* **Type:** `readonly Hex[]`
* **Optional**

The EIP-4844 versioned hashes for the blobs. When omitted, Viem derives them from `blobs` and
`kzg`.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    blobVersionedHashes: ['0x...'], // [!code focus]
  },
)
```

#### options.blockHash

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

The block hash whose state to use. 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d', // [!code focus]
  },
)
```

#### options.blockNumber

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

The block number whose state to use. 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    blockNumber: 20_000_000n, // [!code focus]
  },
)
```

#### options.blockTag

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

The block tag whose state to use. 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    blockTag: 'pending', // [!code focus]
  },
)
```

#### options.chainId

* **Type:** `number | Hex`
* **Optional**

The EIP-155 chain ID to include in the transaction 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    chainId: 1, // [!code focus]
  },
)
```

#### options.dataSuffix

* **Type:** `Hex`
* **Default:** `client.dataSuffix`

The data to append to the encoded function call. This value takes precedence over the Client's
`dataSuffix`.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    dataSuffix: '0xdeadbeef', // [!code focus]
  },
)
```

#### options.from

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

The sender address to use when no `account` option or Client Account is available.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    from: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', // [!code focus]
  },
)
```

#### options.gas

* **Type:** `bigint | number | Hex`
* **Optional**

The gas limit to include in the estimation 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    gas: 100_000n, // [!code focus]
  },
)
```

#### options.gasPrice

* **Type:** `bigint | number | Hex`
* **Optional**

The legacy gas price in wei. Do not combine it with EIP-1559 fee fields.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    gasPrice: 20_000_000_000n, // [!code focus]
  },
)
```

#### options.kzg

* **Type:** `Kzg`
* **Optional**

The KZG implementation used to derive versioned hashes from `blobs`.

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

declare const kzg: Kzg.Kzg

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abis.erc20,
  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  client,
})
// ---cut---
const gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    blobs: ['0x1234'],
    kzg, // [!code focus]
  },
)
```

#### options.maxFeePerBlobGas

* **Type:** `bigint | number | Hex`
* **Optional**

The maximum fee per blob gas in wei.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    maxFeePerBlobGas: 1_000_000_000n, // [!code focus]
  },
)
```

#### options.maxFeePerGas

* **Type:** `bigint | number | Hex`
* **Optional**

The maximum total fee per gas in wei.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    maxFeePerGas: 20_000_000_000n, // [!code focus]
  },
)
```

#### options.maxPriorityFeePerGas

* **Type:** `bigint | number | Hex`
* **Optional**

The maximum priority fee per gas in wei.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    maxPriorityFeePerGas: 1_000_000_000n, // [!code focus]
  },
)
```

#### options.nonce

* **Type:** `bigint | number | Hex`
* **Optional**

The nonce to include for the sender.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    nonce: 69n, // [!code focus]
  },
)
```

#### options.requestOptions

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

The transport options for this 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,
})
const controller = new AbortController()
// ---cut---
const gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    requestOptions: { signal: controller.signal }, // [!code focus]
  },
)
```

#### options.requireCanonical

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

Whether to reject a [`blockHash`](#optionsblockhash) that is not in 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    blockHash: '0x89644bbd5c8d682a2e9611170e6c1f02573d866d286f006cbf517eec7254ec2d',
    requireCanonical: true, // [!code focus]
  },
)
```

#### options.stateOverride

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

The account state to override for the estimation.

```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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    stateOverride: { // [!code focus]
      '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045': { // [!code focus]
        balance: 1_000_000_000_000_000_000n, // [!code focus]
      }, // [!code focus]
    }, // [!code focus]
  },
)
```

#### options.type

* **Type:** `string`
* **Optional**

The transaction type to include in the estimation 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 gas = await contract.estimateGas.approve(
  ['0x70997970c51812dc3a010c7d01b50e0d17dc79c8', 1n],
  {
    type: 'eip1559', // [!code focus]
  },
)
```

#### options.value

* **Type:** `bigint | number | Hex`
* **Optional**

The native currency value to send. This option is available only for payable functions.

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

const client = Client.create({ chain: mainnet, transport: http() })
const contract = Contract.from({
  abi: Abi.from(['function deposit() payable']),
  address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  client,
})
// ---cut---
const gas = await contract.estimateGas.deposit({
  value: Value.fromEther('0.01'), // [!code focus]
})
```

### Return Value

`Promise<bigint>`

The estimated gas units for the contract function.

### Errors

| Error | Description |
| --- | --- |
| `ContractError.ContractFunctionExecutionError` | Estimation failed. Inspect `cause` for a decoded revert reason or other underlying failure. |