Gas Platform API

Gas Platform is an industry leading product that leverages real-time mempool data to deliver transaction gasPrice distribution and precisely predict the gas price required to get into the next block.

Overview

Gas Platform provides access to:

• Gas prices needed to have X% probability to qualify for inclusion in the next block. Need a high probability of being confirmed at the expense of spending extra gas? Use the 99% probability prediction. Don't mind if the tx takes 2-3 blocks if it saves some gas? Use the 70% probability prediction.

• Estimated gas price distribution for the next block. Want a deeper look at live mempool gas statistics? Get a complete breakdown of gas prices in the mempool grouped by gwei.

Gas Platform currently supports Ethereum and Polygon/Matic mainnets.

• For Polygon append: ?chainid=137

You can view an introductory video on Gas Platform here.

Authentication

A valid Blocknative apikey is required in the Authorization Header of every request.

Create an account and apikey here.

Ratelimits

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

blockprices

GET https://api.blocknative.com/gasprices/blockprices

Returns a range of confidence intervals for gas prices needed to qualify a transaction for inclusion in the next block. Order of confidence intervals is subject to change.

Query Parameters

Name	Type	Description
confidenceLevels	number	Override default confidence level order (99,95,90,80,70) in response with up to 5 confidence levels from 1 - 99 (see example confidence level request below)
n	integer	Override 'estimatedTransactionCount' (see example response). Used to estimate how many transactions will fit in the next block.
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 apikey

200 Success

{
    "system": "ethereum",
    "network": "main",
    "unit": "gwei",
    "maxPrice": Number, // Highest priced transaction in the mempool
    "currentBlockNumber": Number, // Block number at time of prediction
    "msSinceLastBlock": Number, // Milliseconds since the last block was mined relative to when this data was computed
    "blockPrices": [
        {
            "blockNumber": Number, // Block this prediction is for
            "estimatedTransactionCount": Number, // Number of items we estimate will be included in next block based on mempool snapshot
            "baseFeePerGas": 1, // Base fee per gas for current block in gwei
            "blobBaseFeePerGas": Number // Base fee per gas for blobs for current block in gwei.
            "estimatedPrices": [
                {
                    "confidence": Number, // 0-99 likelihood the next block will contain a transaction with a gas price >= to the listed price  
                    "price": Number, // Price in gwei
                    "maxPriorityFeePerGas": Number, // Max priority fee per gas in gwei
                    "maxFeePerGas": Number, // Max fee per gas in gwei
                },
                ...,
            ]
        }
    ]
}

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

Example request

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

Example Polygon request

curl -H "Authorization: your-apikey-here" "https://api.blocknative.com/gasprices/blockprices?chainid=137"

Example custom confidence level request

curl -H "Authorization: your-apikey-here" https://api.blocknative.com/gasprices/blockprices?confidenceLevels=10&confidenceLevels=30&confidenceLevels=50&confidenceLevels=70&confidenceLevels=90

Example Response Payload

{
  "system": "ethereum",
  "network": "main",
  "unit": "gwei",
  "maxPrice": 25,
  "currentBlockNumber": 19420156,
  "msSinceLastBlock": 8303,
  "blockPrices": [
    {
      "blockNumber": 19420156,
      "estimatedTransactionCount": 58,
      "baseFeePerGas": 20.118985095,
      "blobBaseFeePerGas": 1e-9,
      "estimatedPrices": [
        {
          "confidence": 99,
          "price": 20,
          "maxPriorityFeePerGas": 0.1,
          "maxFeePerGas": 24.12
        },
        {
          "confidence": 95,
          "price": 20,
          "maxPriorityFeePerGas": 0.09,
          "maxFeePerGas": 24.11
        },
        {
          "confidence": 90,
          "price": 20,
          "maxPriorityFeePerGas": 0.09,
          "maxFeePerGas": 24.11
        },
        {
          "confidence": 80,
          "price": 20,
          "maxPriorityFeePerGas": 0.08,
          "maxFeePerGas": 24.1
        },
        {
          "confidence": 70,
          "price": 20,
          "maxPriorityFeePerGas": 0.07,
          "maxFeePerGas": 24.09
        }
      ]
    }
  ]
}

Type0 and Type2 Transactions

Type0 transactions (Pre EIP-1559) should utilize the Price number under each confidence level. Type2 transactions (EIP-1559) should utilize the values for maxPriorityFeePerGas (also known as the "tip") and maxFeePerGas .

Description of Terms

maxPrice

Highest priced transaction in the mempool.

currentBlockNumber

Block number at the time of prediction.

msSinceLastBlock

Milliseconds since the last block was mined relative to when data was computed.

blockNumber

Block this prediction is for.

estimatedTransactionCount

Number of items we estimate will be included in next block based on mempool snapshot.

baseFeePerGas

Base fee per gas for current block in gwei. (Only type2 transactions Post EIP-1559 have this value and it's burned by the network upon transaction success).

blobBaseFeePerGas

Base fee per gas for blobs for current block in gwei. (Only type3 transactions Post EIP-4844 have this value and it's burned by the network upon transaction success).

estimatedPrices -> confidence

The likelihood the next block will contain a transaction with a price >= to the listed price.

estimatedPrices -> price

Price in Gwei (used for type0 transactions: Pre EIP-1559).

estimatedPrices -> maxPriorityFeePerGas

Max priority fee per gas in gwei also known as the "tip" (used for type2 transactions: EIP-1559).

estimatedPrices -> maxFeePerGas

Max fee per gas in gwei (used for type2 transactions: EIP-1559). maxFeePerGas is computed from baseFeePerGas prediction 5 blocks after the current pending block + maxPriorityFeePerGas.

distribution

GET https://api.blocknative.com/gasprices/distribution

Get the gas price distribution of the highest n

__

priced pending

__

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 GR8 Hackathon or 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 
    "msSinceLastBlock": Number, // Milliseconds since last block at time of capture
    "topNDistribution": {
        "distribution": [ // List of tuples [(price,count), ...], ordered by price
            [
                Number, // Price in gwei
                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