# Gas Distribution API

The Blocknative Gas Distribution API gives you the distribution and breakdown of gas prices in the mempool at that moment in time. 

## Authentication

A valid Blocknative API key is required in the `Authorization` Header of every request. Request an API key [here](https://www.blocknative.com/request-api-key).

## Rate Limits

Each endpoint is limited to provide updated results each second for paid tier API keys, or every 5 seconds for free tier API keys. Polling faster than these rates may deliver stale data.

## API Endpoint

<mark style="color:blue;">`GET`</mark> `https://api.blocknative.com/gasprices/distribution`

Get the gas prices of the highest n transactions eligible for inclusion in the next block. If n is not specified, it defaults to number of expected transactions in the next block.

### Query Parameters

| Name    | Type    | Description                                                                                                                          |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| chainid | integer | The ID of the chain from which gas data is being requested. Currently only Ethereum mainnet (chaind=1 and the default) is supported. |

### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Valid paid tier apikey |

{% tabs %}
{% tab title="200 Success" %}

```javascript
{
    "system": "ethereum",
    "network": "main",
    "unit": "gwei",
    "maxPrice": Number, // Highest priced transaction eligible for inclusion in next block
    "currentBlockNumber": Number, // Block number at moment in time
    "msSinceLastBlock": Number, // Milliseconds since last block at time of capture
    "topNDistribution": {
        "distribution": [ // List of tuples [(price,count), ...], ordered by price
            [
                Number, // Price in "unit"
                Number // Transaction count with this price
            ],
            ...,
        ],
        "n": Number // Top N priced pending transactions included in this distribution
    }
}
```

{% endtab %}

{% tab title="401 Key invalid or not provided" %}

```
{
    "msg": "Authorization header must contain a valid apikey"
}
```

{% endtab %}

{% tab title="429 Rate limit exceeded. Refer to the headers for when to retry the request." %}

```
{ "msg": "Too Many Requests" }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Pending transactions unlikely to be included in the next block due to poor nonce ordering are not included in distribution data
{% endhint %}

### Example request

{% code overflow="wrap" %}

```
curl -H "Authorization: your-apikey-here" https://api.blocknative.com/gasprices/distribution
```

{% endcode %}

### Example Response

```json
{
  "system": "ethereum",
  "network": "main",
  "unit": "gwei",
  "maxPrice": 26,
  "currentBlockNumber": 19720652,
  "msSinceLastBlock": 9775,
  "topNDistribution": {
    "distribution": [
      [15, 2],
      [14.162957017, 1],
      [11, 1],
      [7, 1],
      [5.162957017, 1],
      [5, 10],
      [4.162957017, 4],
      [4, 3],
      [3.162957017, 5],
      [3, 9],
      [2.162957017, 1],
      [2, 15],
      [1.162957017, 5],
      [1, 11],
      [0.194403241, 1],
      [0.162957017, 5]
    ],
    "n": 128
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blocknative.com/gas-prediction/gas-distribution-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.