eth_feeHistory — Ethereum JSON-RPC

Status: Available

Returns a window of historical base fees, gas-usage ratios, and priority-fee percentiles, used to estimate EIP-1559 fees.

POSThttps://triport.io/eth

Network: Ethereum
Scope: eth_read_rpc
Auth: x-token: $TRIPORT_API_KEY (or Authorization: Bearer)
Rate limit: free 10 RPS sustained · up to 20 burst · basic 20 RPS sustained · up to 40 burst · pro 100 RPS sustained · up to 200 burst · business 250 RPS sustained · up to 500 burst; Burst capacity

Endpoint and plans: Ethereum RPC endpoint.

Request

cURLJavaScriptPython

curl https://triport.io/eth \
  -H "Authorization: Bearer $TRIPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_feeHistory",
    "params": ["0x4", "latest", [10, 50, 90]]
  }'

const res = await fetch("https://triport.io/eth", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TRIPORT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_feeHistory",
    "params": [
      "0x4",
      "latest",
      [
        10,
        50,
        90
      ]
    ]
  }),
});
const data = await res.json();
console.log(data);

import os


import requests


resp = requests.post(
    "https://triport.io/eth",
    headers={
        "Authorization": f"Bearer {os.environ['TRIPORT_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "eth_feeHistory",
        "params": [
            "0x4",
            "latest",
            [
                10,
                50,
                90,
            ],
        ],
    },
)
data = resp.json()
print(data)

Response

JSON

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "oldestBlock": "0x149e2be",
    "baseFeePerGas": [
      "0x6f3c4e2a1",
      "0x6e1b9d3f0",
      "0x70a2c5b18",
      "0x6d8f1a4c2",
      "0x6c4e9b330"
    ],
    "gasUsedRatio": [
      0.4821,
      0.5093,
      0.3744,
      0.6612
    ],
    "reward": [
      ["0x3b9aca00", "0x59682f00", "0xee6b2800"],
      ["0x3b9aca00", "0x59682f00", "0xb2d05e00"],
      ["0x1dcd6500", "0x3b9aca00", "0x77359400"],
      ["0x3b9aca00", "0x77359400", "0x12a05f200"]
    ]
  }
}

eth_feeHistory returns fee-market data for a contiguous range of blocks ending at newestBlock. For each block in the window it reports the base fee per gas, the gas-used ratio, and — when you pass rewardPercentiles — the effective priority fee (tip) at each requested percentile. The response also includes the projected base fee for the block immediately after the window, so the baseFeePerGas array always has one more entry than the number of blocks requested.

Use it to build EIP-1559 fee estimates: read recent base fees to anticipate the next block's base fee, and read tip percentiles to pick a maxPriorityFeePerGas that matches how aggressively you want a transaction included. A common pattern is to request the last few blocks at the [10, 50, 90] percentiles and choose a tip from the median or upper band depending on urgency.

All numeric values are returned as 0x-prefixed hexadecimal strings (wei), including the entries inside the reward arrays. The gasUsedRatio field is the exception — it is a JSON number between 0 and 1.

Parameters

Positional params array, in order:

blockCountstring | numberrequired

Number of blocks in the requested window, 1–1024. Accepts a hex-encoded string (e.g. "0x5") or an integer.

newestBlockstringrequired

Highest block of the window: a 0x-prefixed block number or a tag ("latest", "pending", "earliest", "safe", "finalized").

rewardPercentilesnumber[]optional

Monotonically increasing list of percentiles (0–100) at which to sample effective priority fees per block. Omit to skip the reward array.

Response

Response fields

Field	Type	Description
`jsonrpc`	`string`	JSON-RPC version, always `"2.0"`.
`id`	`number`	Echoes the request `id`.
`result`	`object`	The fee-history window.
`result.oldestBlock`	`string`	Block number of the lowest (oldest) block in the window, as a `0x`-prefixed hex string.
`result.baseFeePerGas`	`string[]`	Base fee per gas (wei, hex) for each block in the window plus the projected base fee for the next block. Length = `blockCount + 1`.
`result.gasUsedRatio`	`number[]`	Ratio of gas used to gas limit (`0`–`1`) for each block in the window. Length = `blockCount`.
`result.reward`	`string[][]`	Per-block array of effective priority fees (wei, hex), one entry per requested percentile. Length = `blockCount`. Omitted when `rewardPercentiles` is not supplied.

Errors

Code	Meaning	When it happens
`401`	`trial_expired`	The account's trial period has ended.
`429`	`rate_limited`	The per-tier RPS limit was exceeded. Back off and retry.
`-32602`	`invalid_params`	`blockCount` is outside `1`–`1024`, `rewardPercentiles` is not increasing or out of range, or `newestBlock` is malformed.

See errors.md for the full error envelope and handling guidance.

Examples

JavaScript (fetch)

JavaScript

const res = await fetch("https://triport.io/eth", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TRIPORT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_feeHistory",
    params: ["0x4", "latest", [10, 50, 90]],
  }),
});


const { result } = await res.json();


// Suggest a tip from the median (50th percentile) of the most recent block.
const recentReward = result.reward.at(-1);
const medianTip = parseInt(recentReward[1], 16);
const nextBaseFee = parseInt(result.baseFeePerGas.at(-1), 16);
console.log({ nextBaseFee, medianTip });

Notes

baseFeePerGas is always one element longer than blockCount — the last entry is the predicted base fee for the block after newestBlock, which is what you feed into a maxFeePerGas estimate.
gasUsedRatio values near 1.0 indicate full blocks and an upward-trending base fee; values well below 0.5 indicate the base fee is likely to fall.
Omitting rewardPercentiles returns a lighter response without the reward array — useful when you only need base-fee trends.
All wei amounts (base fees and rewards) are hex strings; convert with base 16 before arithmetic. gasUsedRatio is already a decimal number.
eth_feeHistory is available on the Free trial (eth_read_rpc category). Rate limiting is RPS-per-tier with burst; there is no daily quota. An HTTP 429 rate_limited error means you should back off and retry shortly.
For a single spot price instead of a window, see eth_gasPrice. To learn the current chain head before requesting a historical window, see eth_blockNumber.