@pulsadev/gas-oracle

EIP-1559 gas estimation for EVM chains — speed tiers, confidence intervals, trend analysis, L2 cost separation. Zero dependencies.

Know exactly what gas price to set for slow, standard, fast, or instant confirmation. Works across 15+ chains out of the box.

Features

• 4 speed tiers — slow, standard, fast, instant with estimated confirmation time
• EIP-1559 native — baseFee + priorityFee with next-block baseFee prediction
• Confidence intervals — low/mid/high range with confidence percentage
• Gas trend analysis — rising, falling, or stable with change percentage
• L2 cost separation — split L2 execution fee from L1 data fee (Optimism, Base, Arbitrum)
• 15+ chains — Ethereum, Polygon, Arbitrum, Optimism, Base, BSC, Avalanche, and more
• Legacy chain support — works on non-EIP-1559 chains like BSC
• Built-in caching — configurable TTL, 0ms cache hits
• Fee history — analyze baseFee and priorityFee across recent blocks
• Zero dependencies — ~15 KB bundled, ESM + CJS, pure TypeScript

Install

npm install @pulsadev/gas-oracle

Quick Start

import { GasOracle } from '@pulsadev/gas-oracle'

const oracle = new GasOracle('https://eth.llamarpc.com', { chainId: 1 })

// Get all 4 speed tiers
const prices = await oracle.getGasPrices()
console.log(prices.fast)
// {
//   maxFeePerGas: 12500000000n,
//   maxPriorityFeePerGas: 2000000000n,
//   baseFee: 8000000000n,
//   estimatedSeconds: 12
// }

// Get a single tier
const instant = await oracle.getGasPrice('instant')

API

new GasOracle(rpcUrl, options?)

const oracle = new GasOracle('https://eth.llamarpc.com', {
  chainId: 1,         // auto-detected if omitted
  blockCount: 20,     // blocks to analyze (default: 20)
  percentiles: [10, 25, 50, 75], // priority fee percentiles
  cacheMs: 5000,      // cache TTL in ms (0 = disabled)
})

Speed Tiers

const prices = await oracle.getGasPrices()
// prices.slow     — ~3 blocks wait
// prices.standard — ~2 blocks wait
// prices.fast     — ~1 block wait
// prices.instant  — next block

// Single tier
const fast = await oracle.getGasPrice('fast')

Confidence Interval

const ci = await oracle.getConfidenceInterval(20)
// {
//   low: 5000000000n,    // 5th percentile baseFee
//   mid: 8000000000n,    // 50th percentile (median)
//   high: 12000000000n,  // 95th percentile
//   confidence: 85       // 0-100, higher = tighter range
// }

Gas Trend

const trend = await oracle.getGasTrend(50)
// {
//   direction: 'rising',   // 'rising' | 'falling' | 'stable'
//   changePercent: 15.3,   // percent change
//   avgBaseFee: 8000000000n,
//   minBaseFee: 5000000000n,
//   maxBaseFee: 12000000000n,
//   blocks: 50
// }

L2 Cost Separation

import { estimateL2Cost } from '@pulsadev/gas-oracle'

// Optimism / Base (OP Stack)
const cost = await estimateL2Cost(rpcUrl, 10, calldata)
// {
//   l1DataFee: 1287847501n,  // L1 data posting cost
//   l2ExecutionFee: 0n,      // add from gas estimation
//   totalFee: 1287847501n,
//   l1DataBytes: 68
// }

// Arbitrum
const arbCost = await estimateL2Cost(rpcUrl, 42161, calldata)

// Non-L2 chains return zero L1 cost
const ethCost = await estimateL2Cost(rpcUrl, 1, calldata)
// { l1DataFee: 0n, ... }

Fee History

const history = await oracle.getFeeHistory(20)
// {
//   baseFees: [8000000000n, 8100000000n, ...],
//   priorityFees: [[1000000000n, 2000000000n, ...], ...],
//   gasUsedRatios: [0.45, 0.67, ...],
//   blockRange: { from: 25700000n, to: 25700019n }
// }

Legacy Gas Prices

// For non-EIP-1559 chains (e.g. BSC)
const legacy = await oracle.getLegacyGasPrices()
// { slow: 3000000000n, standard: 3000000000n, fast: 3600000000n, instant: 4500000000n }

Utilities

const baseFee = await oracle.getBaseFee()
const blockNumber = await oracle.getBlockNumber()
oracle.clearCache()

Chain Registry

import { getChainConfig, getSupportedChains, isL2Chain, isEip1559Chain } from '@pulsadev/gas-oracle'

const config = getChainConfig(42161)
// { chainId: 42161, name: 'Arbitrum One', isEip1559: true, isL2: true, blockTimeMs: 250, ... }

const chains = getSupportedChains() // 15+ chains
isL2Chain(8453)      // true (Base)
isEip1559Chain(56)   // false (BSC)

Supported Chains

| Chain | ID | EIP-1559 | L2 | L2 Cost Split | |-------|---:|:--------:|:--:|:-------------:| | Ethereum | 1 | ✅ | — | — | | Optimism | 10 | ✅ | ✅ | ✅ | | BSC | 56 | ❌ | — | — | | Gnosis | 100 | ✅ | — | — | | Polygon | 137 | ✅ | — | — | | Fantom | 250 | ✅ | — | — | | zkSync Era | 324 | ✅ | ✅ | — | | Mantle | 5000 | ✅ | ✅ | — | | Base | 8453 | ✅ | ✅ | ✅ | | Arbitrum One | 42161 | ✅ | ✅ | ✅ | | Avalanche | 43114 | ✅ | — | — | | Linea | 59144 | ✅ | ✅ | — | | Blast | 81457 | ✅ | ✅ | — | | Scroll | 534352 | ✅ | ✅ | — |

Unlisted EIP-1559 chains work automatically with default settings.

Performance

Benchmarked on a dedicated VPS (Dallas, 4 vCPU, 8 GB RAM). Median of 5 runs.

| Operation | Time | |-----------|-----:| | getGasPrices (4 tiers) | 120ms | | getGasPrice (single) | 54ms | | getBaseFee | 55ms | | getFeeHistory (20 blocks) | 54ms | | getGasTrend (20 blocks) | 53ms | | getConfidenceInterval | 53ms | | getGasPrices (cached) | 0ms |

License

MIT © Yuto Nakamura