Distribution API

The Blocknative 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. Create an account and API key here.

Ratelimits

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

GET 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
n	integer	Number of transactions (ordered by gas price) to use to build the distribution.
chainid	integer	The ID of the chain gas data being requested. Currently supported chains are 1 (Ethereum mainnet) and 137 (Polygon/Matic mainnet). Default is 1.

Headers

Name	Type	Description
Authorization	string	Valid paid tier apikey

200 Success

{
    "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
    }
}

401 Key invalid or not provided

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

429 Rate limit exceeded. Refer to the headers for when to retry the request.

{ "msg": "Too Many Requests" }

Pending transactions unlikely to be included in the next block due to poor nonce ordering are not included in distribution data

Example request

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

Example Response

{
  "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
  }
}