⛓️ chainpulse

Multi-chain EVM gas price tracker for the terminal — works out of the box, no API keys required.

chainpulse pulls live gas prices from public EVM RPC endpoints and renders them as a clean, colorful terminal UI. It supports Ethereum, Polygon, Arbitrum, Optimism, Base and BNB Smart Chain — and is designed to be easily extended.

◆ Multi-Chain Gas Pulse
────────────────────────────────────────────────────────────────────────
  Chain       Slow       Standard    Fast        Instant     Status
  ──────────────────────────────────────────────────────────────────────────────
  ETH         0.291      0.332       0.394       0.509       ✓ ok
  POLY        30.2       36.7        43.1        51.9        ✓ ok
  ARB         0.100      0.110       0.130       0.156       ✓ ok
  OP          0.025      0.029       0.034       0.041       ✓ ok
  BASE        0.015      0.018       0.022       0.027       ✓ ok
  BSC         1.20       1.45        1.70        2.05        ✓ ok

✨ Features

• 🌍 6 chains out of the box (Ethereum, Polygon, Arbitrum, Optimism, Base, BSC)
• 🔌 Zero setup — uses public RPCs, no API keys, no signup
• ⚡ EIP-1559 aware — base fee + priority fee percentile sampling
• 📊 History view — sparkline of last N blocks per chain
• 🔁 Watch mode — continuous polling with Ctrl-C to stop
• 💸 USD estimates — plug in an ETH price for cost estimates
• 🤖 JSON output — pipe into your scripts
• 📦 Programmatic API — use as a library in your own TS/JS project

📦 Install

# from npm (when published)
npm install -g chainpulse

# or straight from source
git clone https://github.com/YigitEfe-DEV/chainpulse.git
cd chainpulse
npm install
npm run build
node dist/cli.js --help

Requires Node.js ≥ 18.

🚀 Usage

Current gas prices

chainpulse current                        # all 6 chains
chainpulse current --chain ethereum       # only Ethereum
chainpulse current --chain ethereum,base  # comma-separated
chainpulse current --eth-price 2400       # include USD estimates
chainpulse current --json                 # machine-readable JSON

Per-chain history (sparkline)

chainpulse history ethereum --blocks 30
chainpulse history polygon --blocks 50 --json

Watch mode (poll every N seconds)

chainpulse watch --chain ethereum --interval 10
chainpulse watch --chain ethereum,polygon --interval 30

Press Ctrl-C to stop.

List supported chains

chainpulse chains

🤖 Programmatic API

import { fetchGasForChains, fetchGasHistory, CHAINS } from 'chainpulse';

const results = await fetchGasForChains(['ethereum', 'polygon', 'base']);

for (const r of results) {
  if (r.status === 'ok' && r.data) {
    console.log(`${r.chain}: standard=${r.data.standard.gwei} gwei`);
  } else {
    console.error(`${r.chain}: failed — ${r.error}`);
  }
}

// Historical samples
const points = await fetchGasHistory('ethereum', 50);
console.log(`baseFee range: ${Math.min(...points.map(p => p.baseFeeGwei))} - ${Math.max(...points.map(p => p.baseFeeGwei))} gwei`);

🧠 How it works

For each chain chainpulse issues two JSON-RPC calls against public endpoints:

1. eth_blockNumber — current head
2. eth_feeHistory (or eth_gasPrice as fallback) — recent base fees + priority fee samples

It then buckets the priority-fee samples into 25/50/75/95 percentiles and combines each bucket with the projected next-block base fee to produce slow / standard / fast / instant suggestions. The math is intentionally simple and documented inline in src/gas.ts.

RPC fallback

Every chain has a list of public RPC URLs. chainpulse tries them in order and falls back automatically if one is rate-limited or down. Override the list with a custom RPC by editing src/chains/registry.ts or by forking and shipping your own config.

🛠 Development

npm install          # install deps
npm run build        # compile to dist/
npm run lint         # tsc --noEmit
npm test             # node:test suite
npm run format       # prettier

Project layout:

chainpulse/
├── src/
│   ├── chains/registry.ts   # chain configs + RPC URL lists
│   ├── rpc.ts               # JSON-RPC client w/ timeout + fallback
│   ├── gas.ts               # fee-history → GasSuggestion logic
│   ├── formatter.ts         # terminal output rendering
│   ├── cli.ts               # commander.js CLI entrypoint
│   ├── types.ts             # shared types
│   └── index.ts             # public API
├── test/gas.test.ts
├── .github/workflows/ci.yml # CI: build + test on Node 18/20/22
└── package.json

🗺 Adding a new chain

1. Add the chain config in src/chains/registry.ts:

   avalanche: {
     id: 'avalanche',
     name: 'Avalanche C-Chain',
     shortName: 'AVAX',
     chainId: 43114,
     symbol: 'AVAX',
     rpcUrls: ['https://api.avax.network/ext/bc/C/rpc'],
     supportsEip1559: true,
     blockTime: 2,
     explorerUrl: 'https://snowtrace.io',
     color: 'red',
   },

2. Add a matching test in test/gas.test.ts.

3. Open a PR.

🐛 Troubleshooting

• All chains fail with All RPC endpoints failed — public RPCs may be rate-limiting you. Try again in a minute, or point to a private endpoint (Alchemy/Infura) by editing src/chains/registry.ts.
• SyntaxError: Unexpected token 'export' — you ran the TypeScript source directly. Use npm run build first, then node dist/cli.js.
• Colors missing — your terminal may not support ANSI. Pass --no-color or set NO_COLOR=1.

🤝 Contributing

PRs welcome! Please run npm run lint && npm test before submitting. The main branch is protected; CI must pass.

📄 License

MIT © 2026 Yiğit Efe