# Infura Gas API reference

> Complete Infura Gas API reference documentation

This file contains all documentation content in a single document following the llmstxt.org standard.

## Get the base fee history


Returns the base fee history of the specified blockchain network for the previous 500 blocks. <CreditCost network="gasApi" method="baseFeeHistory" />

The base fee is a part of the EIP-1559 upgrade to the Ethereum network, and it represents the
minimum price a user must pay for their transaction to be included in a block.

This method can be useful for applications that need to display or analyze the historical base fee
data for a specific blockchain network.

**GET** `https://gas.api.infura.io/networks/${chainId}/baseFeeHistory`

## Parameters

**Path**:

- `chainId`: `string` - ID of the chain to query.
  See the [list of supported chain IDs](../../../get-started/endpoints.md#gas-api).

## Returns

Array of historical base fees.

## Example

### Request

Include your [API key](/dashboard/get-started/create-api)
and optional [API key secret](/dashboard/how-to/secure-an-api/api-key-secret)
to authorize your account to use the APIs.

:::tip
You can call the API with only an API key, and [include it as a path parameter](../api-reference/index.md#supported-api-request-formats)
instead of using the curl authentication option (`-u`).
:::

<Tabs>
  <TabItem value="curl" label="curl" default >

```bash
curl -X "GET" \
  -u <YOUR-API-KEY>:<YOUR-API-KEY-SECRET> \
  "https://gas.api.infura.io/networks/1/baseFeeHistory"
```

  </TabItem>
  <TabItem value="JavaScript" label="JavaScript">

```javascript
const axios = require('axios')

const apiKey = '<YOUR-API-KEY>' // Replace with your API key.
const apiKeySecret = '<YOUR-API-KEY-SECRET>' // Replace with your API key secret.

const Auth = Buffer.from(apiKey + ':' + apiKeySecret).toString('base64')

// The chain ID of the supported network.
const chainId = 1

;(async () => {
  try {
    const { data } = await axios.get(
      `https://gas.api.infura.io/networks/${chainId}/baseFeeHistory`,
      {
        headers: {
          Authorization: `Basic ${Auth}`,
        },
      }
    )
    console.log('Base fee history:', data)
  } catch (error) {
    console.log('Server responded with:', error)
  }
})()
```

  </TabItem>
</Tabs>

### Response

```json
[
  "14.585610312",
  "16.407222984",
  "16.687763116",
  "16.357094117",
  "15.82929799",
  "15.21546789",
  "17.113938208",
  "16.92324819",
  ...
]
```

---

## Get the base fee percentile


Returns the base fee percentile (50th percentile) of the specified blockchain network. <CreditCost network="gasApi" method="baseFeePercentile" />

For example, if the API returns a value of `20` Gwei, it means that 50% of the historical base fees
are less than or equal to `20` Gwei.

This can be useful for users or applications to estimate the optimal gas price for transactions
based on historical data.

**GET** `https://gas.api.infura.io/networks/${chainId}/baseFeePercentile`

## Parameters

**Path**:

- `chainId`: `string` - ID of the chain to query.
  See the [list of supported chain IDs](../../../get-started/endpoints.md#gas-api).

## Returns

`baseFeePercentile`: `string` - The base fee in Gwei at the 50th percentile, meaning that 50% of the base fees are
less than or equal to the provided amount.

## Example

### Request

Include your [API key](/dashboard/get-started/create-api)
and optional [API key secret](/dashboard/how-to/secure-an-api/api-key-secret)
to authorize your account to use the APIs.

:::tip
You can call the API with only an API key, and [include it as a path parameter](../api-reference/index.md#supported-api-request-formats)
instead of using the curl authentication option (`-u`).
:::

<Tabs>
  <TabItem value="curl" label="curl" default >

```bash
curl -X "GET" \
  -u <YOUR-API-KEY>:<YOUR-API-KEY-SECRET> \
  "https://gas.api.infura.io/networks/1/baseFeePercentile"
```

  </TabItem>
  <TabItem value="JavaScript">

```javascript
const axios = require('axios')

const apiKey = '<YOUR-API-KEY>' // Replace with your API key.
const apiKeySecret = '<YOUR-API-KEY-SECRET>' // Replace with your API key secret.

const Auth = Buffer.from(apiKey + ':' + apiKeySecret).toString('base64')

// The chain ID of the supported network.
const chainId = 1

;(async () => {
  try {
    const { data } = await axios.get(
      `https://gas.api.infura.io/networks/${chainId}/baseFeePercentile`,
      {
        headers: {
          Authorization: `Basic ${Auth}`,
        },
      }
    )
    console.log('Base fee percentile:', data)
  } catch (error) {
    console.log('Server responded with:', error)
  }
})()
```

  </TabItem>
</Tabs>

### Response

```json
{
  "baseFeePercentile": "23.227829059"
}
```

---

## Get the busy threshold


Returns the busy threshold for the specified blockchain network. <CreditCost network="gasApi" method="busyThreshold" />

For example, a `busyThreshold` value of `30` Gwei indicates that 90% of the historical base fees on
the network have been below `30` Gwei.
If the current base fee exceeds this value, it suggests that the network is busier than usual,
likely due to a high volume of transactions.

**GET** `https://gas.api.infura.io/networks/${chainId}/busyThreshold`

## Parameters

**Path**:

- `chainId`: `string` - ID of the chain to query.
  See the [list of supported chain IDs](../../../get-started/endpoints.md#gas-api).

## Returns

`busyThreshold`: `string` - Indicates that 90% of the historical base fees on the network
have been below this threshold, serving as a marker of network congestion when current base fees exceed it.

## Example

### Request

Include your [API key](/dashboard/get-started/create-api)
and optional [API key secret](/dashboard/how-to/secure-an-api/api-key-secret)
to authorize your account to use the APIs.

:::tip
You can call the API with only an API key, and [include it as a path parameter](../api-reference/index.md#supported-api-request-formats)
instead of using the curl authentication option (`-u`).
:::

<Tabs>
  <TabItem value="curl" label="curl" default >

```bash
curl -X "GET" \
  -u <YOUR-API-KEY>:<YOUR-API-KEY-SECRET> \
  "https://gas.api.infura.io/networks/1/busyThreshold"
```

  </TabItem>
  <TabItem value="JavaScript" label="JavaScript">

```javascript
const axios = require('axios')

const apiKey = '<YOUR-API-KEY>' // Replace with your API key.
const apiKeySecret = '<YOUR-API-KEY-SECRET>' // Replace with your API key secret.

const Auth = Buffer.from(apiKey + ':' + apiKeySecret).toString('base64')

// The chain ID of the supported network.
const chainId = 1

;(async () => {
  try {
    const { data } = await axios.get(
      `https://gas.api.infura.io/networks/${chainId}/busyThreshold`,
      {
        headers: {
          Authorization: `Basic ${Auth}`,
        },
      }
    )
    console.log('Busy threshold:', data)
  } catch (error) {
    console.log('Server responded with:', error)
  }
})()
```

  </TabItem>
</Tabs>

### Response

```json
{
  "busyThreshold": "37.378956101"
}
```

---

## Get EIP-1559 gas prices


Returns the estimated [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) gas fees for the specified
blockchain network. <CreditCost network="gasApi" method="suggestedGasFees" />

**GET** `https://gas.api.infura.io/networks/${chainId}/suggestedGasFees`

## Parameters

**Path**:

- `chainId`: `string` - ID of the chain to query.
  See the [list of supported chain IDs](../../../get-started/endpoints.md#gas-api).

## Returns

Recommended gas price details based of the level of urgency:

- `low`, `medium`, `high` - Object containing recommended values for transactions by level of urgency:
  - `suggestedMaxPriorityFeePerGas`: `string` - The maximum suggested priority fee per gas (in gwei) to pay to have transactions included in a block.
  - `suggestedMaxFeePerGas`: `string` - The maximum suggested total fee per gas (in gwei) to pay, including both the base fee and the priority fee.
  - `minWaitTimeEstimate`: `number` - The minimum estimated wait time (in milliseconds) for a transaction to be included in a block at the suggested gas price.
  - `maxWaitTimeEstimate`: `number` - The maximum estimated wait time (in milliseconds) for a transaction to be included in a block at the suggested gas price.
- `estimatedBaseFee`: `string` - The current estimated base fee per gas on the network.
- `networkCongestion`: `number` - The current congestion on the network, represented as a number between `0` and `1`.
  A lower network congestion score (for example `0.1`), indicates that fewer transactions are being submitted, so it's cheaper to validate transactions.
- `latestPriorityFeeRange`: `array` - The range of priority fees per gas for recent transactions on the network.
- `historicalPriorityFeeRange`: `array` - The range of priority fees per gas for transactions on the network over a historical period.
- `historicalBaseFeeRange`: `array` - The range of base fees per gas on the network over a historical period.
- `priorityFeeTrend`: `string` - The current trend in priority fees on the network, either `up` or `down` (whether it's getting more expensive or cheaper).
- `baseFeeTrend`: `string` - The current trend in base fees on the network, either `up` or `down` (whether it's getting more expensive or cheaper).

## Example

### Request

Include your [API key](/dashboard/get-started/create-api)
and optional [API key secret](/dashboard/how-to/secure-an-api/api-key-secret)
to authorize your account to use the APIs.

:::tip
You can call the API with only an API key, and [include it as a path parameter](../api-reference/index.md#supported-api-request-formats)
instead of using the curl authentication option (`-u`).
:::

<Tabs>
  <TabItem value="curl" label="curl" default >

```bash
curl -X "GET" \
  -u <YOUR-API-KEY>:<YOUR-API-KEY-SECRET> \
  "https://gas.api.infura.io/networks/1/suggestedGasFees"
```

  </TabItem>
  <TabItem value="JavaScript">

```javascript
const axios = require('axios')

const apiKey = '<YOUR-API-KEY>' // Replace with your API key.
const apiKeySecret = '<YOUR-API-KEY-SECRET>' // Replace with your API key secret.

const Auth = Buffer.from(apiKey + ':' + apiKeySecret).toString('base64')

// The chain ID of the supported network.
const chainId = 1

;(async () => {
  try {
    const { data } = await axios.get(
      `https://gas.api.infura.io/networks/${chainId}/suggestedGasFees`,
      {
        headers: {
          Authorization: `Basic ${Auth}`,
        },
      }
    )
    console.log('Suggested gas fees:', data)
  } catch (error) {
    console.log('Server responded with:', error)
  }
})()
```

  </TabItem>
</Tabs>

### Response

```json
{
  "low": {
    "suggestedMaxPriorityFeePerGas": "0.05",
    "suggestedMaxFeePerGas": "16.334026964",
    "minWaitTimeEstimate": 15000,
    "maxWaitTimeEstimate": 30000
  },
  "medium": {
    "suggestedMaxPriorityFeePerGas": "0.1",
    "suggestedMaxFeePerGas": "22.083436402",
    "minWaitTimeEstimate": 15000,
    "maxWaitTimeEstimate": 45000
  },
  "high": {
    "suggestedMaxPriorityFeePerGas": "0.3",
    "suggestedMaxFeePerGas": "27.982845839",
    "minWaitTimeEstimate": 15000,
    "maxWaitTimeEstimate": 60000
  },
  "estimatedBaseFee": "16.284026964",
  "networkCongestion": 0.5125,
  "latestPriorityFeeRange": ["0", "3"],
  "historicalPriorityFeeRange": ["0.000000001", "89"],
  "historicalBaseFeeRange": ["13.773088584", "29.912845463"],
  "priorityFeeTrend": "down",
  "baseFeeTrend": "up"
}
```

---

## Gas API reference


This section provides reference information for the Gas REST APIs.
Use the APIs to:

- [Get EIP-1559 gas prices.](./gasprices-type2.md)
- [Get the base fee history (in Gwei).](./basefeehistory.md)
- [Get the base fee percentile (in Gwei).](./basefeepercentile.md)
- [Get the busy threshold for a network.](./busythreshold.md)

:::info
See the [list of supported Gas API networks](../../../get-started/endpoints.md#gas-api).
:::

## Supported API request formats

You can call the Gas APIs in two ways:

- **Using the API key only** - Add your [API key](/dashboard/get-started/create-api)
  as a path option.
- **Using the API key and API key secret** - Use basic authentication and specify the API key
  and [API key secret](/dashboard/how-to/secure-an-api/api-key-secret).

<Tabs>
  <TabItem value="API key only" label="Use an API key only" default>

```bash
curl -X "GET" "https://gas.api.infura.io/v3/<YOUR-API-KEY>/networks/1/suggestedGasFees"
```

  </TabItem>
  <TabItem value="API key and API key secret" label="Use an API key and API key secret" >

```bash
curl -X "GET" -u <YOUR-API-KEY>:<YOUR-API-KEY-SECRET> "https://gas.api.infura.io/networks/1/suggestedGasFees"
```

  </TabItem>
</Tabs>

---

## Gas API


The Gas API is a tool that delivers real-time [gas prices](../../concepts/gas.md) for supported networks, enabling users to identify the best times to execute transactions based on current rates and intricacies introduced by [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559).

:::info
See the [list of supported Gas API networks](../../get-started/endpoints.md#gas-api).
:::

<CardList
items={[
{
href: "/reference/gas-api/quickstart",
title: "Quickstart",
description: "Learn how to quickly connect and make calls to the Gas API."
},
{
href: "/reference/gas-api/api-reference",
title: "REST APIs",
description: "View the APIs available for communicating with the Gas API."
},
{
href: "/dashboard/get-started/create-api",
title: "Create an API key",
description: "Learn how to create and secure an API key."
}
]}
/>

---

## Gas API quickstart


This quickstart shows you how to call the Gas API using JavaScript.
You can also use a tool such as [curl](https://curl.se/) or [Postman](https://www.postman.com/) to
call the REST APIs.

:::tip
View the [API reference content](api-reference/index.md) to view the `curl` command for each API.
:::

## Prerequisites

- A valid [Web3 API key](/dashboard/get-started/create-api)
  and optional [API key secret](/dashboard/how-to/secure-an-api/api-key-secret).
- [Node.js and npm installed](https://nodejs.org/en/download).

## Initialize a new project directory

```bash
mkdir new_project
cd new_project
npm init -y
```

## Install required packages

Install the `axios` package:

```bash
npm install axios
```

Install the [`dotenv`](../../how-to/javascript-dotenv.md) package:

```bash
npm install dotenv
```

## Create your `.env` file

Create a `.env` file at the project root and add the following data:

:::caution warning
Do not commit the `.env` file to your repository if it contains sensitive data.
You can [create a `.gitignore` file](../../how-to/javascript-dotenv.md#create-a-gitignore-file)
to prevent accidentally committing the file.
:::

```bash title=".env"
INFURA_API_KEY=<YOUR-API-KEY>
INFURA_API_KEY_SECRET=<YOUR-API-KEY-SECRET>
```

Replace the Infura project credential placeholders with your own.

:::note
The `INFURA_API_KEY_SECRET` is optional and only necessary if you are using an
[API key secret](/dashboard/how-to/secure-an-api/api-key-secret) to authenticate requests.
:::

## Create your script

The Gas API supports [multiple request formats](./api-reference/index.md#supported-api-request-formats), and
you can call the methods with or without specifying an API key secret.

Create a file (in this example `index.js`):

```bash
touch index.js
```

Copy the following code into your script:

:::info note
If using a network other than Ethereum Mainnet, update the `chainId` value (`1`) in the code to an
alternate [supported network](../../get-started/endpoints.md#gas-api).
:::

<Tabs>
  <TabItem value="Use API key" label="Use an API key only" default>

```javascript title="index.js"
const axios = require('axios')
require('dotenv').config()

// The chain ID of the supported network
const chainId = 1

;(async () => {
  try {
    const { data } = await axios.get(
      `https://gas.api.infura.io/v3/${process.env.INFURA_API_KEY}/networks/${chainId}/suggestedGasFees`
    )
    console.log('Suggested gas fees:', data)
  } catch (error) {
    console.log('Server responded with:', error)
  }
})()
```

  </TabItem>
  <TabItem value="With basic authentication" label="Use an API key and API key secret" default>

```javascript title="index.js"
const axios = require('axios')
require('dotenv').config()

const Auth = Buffer.from(
  process.env.INFURA_API_KEY + ':' + process.env.INFURA_API_KEY_SECRET
).toString('base64')

// The chain ID of the supported network
const chainId = 1

;(async () => {
  try {
    const { data } = await axios.get(
      `https://gas.api.infura.io/networks/${chainId}/suggestedGasFees`,
      {
        headers: {
          Authorization: `Basic ${Auth}`,
        },
      }
    )
    console.log('Suggested gas fees:', data)
  } catch (error) {
    console.log('Server responded with:', error)
  }
})()
```

  </TabItem>
</Tabs>

## Run the script

```bash
node index.js
```

The result should look similar to:

```json
Suggested gas fees: {
  low: {
    suggestedMaxPriorityFeePerGas: "0.05", // The gas price in gwei
    suggestedMaxFeePerGas: "24.086058416", // The gas price in gwei
    minWaitTimeEstimate: 15000,
    maxWaitTimeEstimate: 30000
  },
  medium: {
    suggestedMaxPriorityFeePerGas: "0.1", // The gas price in gwei
    suggestedMaxFeePerGas: "32.548678862", // The gas price in gwei
    minWaitTimeEstimate: 15000,
    maxWaitTimeEstimate: 45000
  },
  high: {
    suggestedMaxPriorityFeePerGas: "0.3", // The gas price in gwei
    suggestedMaxFeePerGas: "41.161299308", // The gas price in gwei
    minWaitTimeEstimate: 15000,
    maxWaitTimeEstimate: 60000
  },
  estimatedBaseFee: "24.036058416",
  networkCongestion: 0.7143,
  latestPriorityFeeRange: [ "0.1", "20" ],
  historicalPriorityFeeRange: [ "0.007150439", "113" ],
  historicalBaseFeeRange: [ "19.531410688", "36.299069766" ],
  priorityFeeTrend: "down",
  baseFeeTrend: "down"
}
```