# 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
  }
}
```