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

# Get Fee History \[fee.getHistory]

Returns a collection of historical gas information.

## Usage

This example returns a collection of historical gas information.

:::code-group
```ts twoslash [example.ts]
import { client } from './viem.config'

const feeHistory = await client.fee.getHistory({
  blockCount: 4,
  rewardPercentiles: [25, 75],
})
// @log: {
// @log:   baseFeePerGas: [12952210265n, 13007005941n, 12914819642n, 12832378110n, 12832378110n],
// @log:   gasUsedRatio: [0.5232, 0.4283, 0.4291, 0.4869],
// @log:   oldestBlock: 19868015n,
// @log:   reward: [[1000000000n, 2000000000n], ...],
// @log: }
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

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

### Standalone Action

Call `Actions.fee.getHistory` directly by passing the Client as the first argument.

:::code-group
```ts twoslash [example.ts]
import { Actions } from 'viem'
import { client } from './viem.config'

const feeHistory = await Actions.fee.getHistory(client, {
  blockCount: 4,
  rewardPercentiles: [25, 75],
})
// @log: {
// @log:   baseFeePerGas: [12952210265n, 13007005941n, 12914819642n, 12832378110n, 12832378110n],
// @log:   gasUsedRatio: [0.5232, 0.4283, 0.4291, 0.4869],
// @log:   oldestBlock: 19868015n,
// @log:   reward: [[1000000000n, 2000000000n], ...],
// @log: }
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http } from 'viem'
import { mainnet } from 'viem/chains'

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

## Recipes

### Compare Priority Fee Percentiles

Pass ascending reward percentiles to compare low, median, and high effective priority fees in each block.

```ts twoslash
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

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

const feeHistory = await client.fee.getHistory({
  blockCount: 20,
  rewardPercentiles: [10, 50, 90], // [!code focus]
})
```

### Select a Historical Range

Use `blockNumber` as the highest block and `blockCount` as the requested range length.

```ts twoslash
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

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

const feeHistory = await client.fee.getHistory({
  blockCount: 10, // [!code focus]
  blockNumber: 19_868_020n, // [!code focus]
  rewardPercentiles: [50],
})
```

## Return Value

`Fee.FeeHistory`

A collection of historical gas information:

* `baseFeePerGas`: Block base fees per gas. Includes the next block after the newest of the returned range.
* `gasUsedRatio`: Block gas used ratios (`gasUsed / gasLimit`).
* `oldestBlock`: Lowest number block of the returned range.
* `reward`: Effective priority fees per gas for each requested percentile (only present when `rewardPercentiles` is supplied).

## Parameters

### blockCount

* **Type:** `number`

Number of blocks in the requested range. Between 1 and 1024 blocks can be requested in a single query.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const feeHistory = await Actions.fee.getHistory(client, {
  blockCount: 4, // [!code focus]
  rewardPercentiles: [25, 75],
})
```

### blockNumber

* **Type:** `bigint`

Highest number block of the requested range. Mutually exclusive with [`blockTag`](#blocktag).

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const feeHistory = await Actions.fee.getHistory(client, {
  blockCount: 4,
  blockNumber: 19868020n, // [!code focus]
  rewardPercentiles: [25, 75],
})
```

### blockTag

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

Highest number block of the requested range. Mutually exclusive with [`blockNumber`](#blocknumber).

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const feeHistory = await Actions.fee.getHistory(client, {
  blockCount: 4,
  blockTag: 'safe', // [!code focus]
  rewardPercentiles: [25, 75],
})
```

### rewardPercentiles

* **Type:** `number[]`

A monotonically increasing list of percentile values to sample from each block's effective priority fees per gas, in ascending order, weighted by gas used.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const feeHistory = await Actions.fee.getHistory(client, {
  blockCount: 4,
  rewardPercentiles: [25, 50, 75], // [!code focus]
})
```