🛡️ ETH Gas Guardian

Real-time Ethereum gas price monitor - Find the best time to transact and save on gas fees.

ETH Gas Guardian is a powerful CLI tool that helps you monitor Ethereum gas prices in real-time, set alerts, and find the best time to make transactions. Perfect for DeFi users, NFT collectors, and anyone who wants to save on gas fees.

✨ Features

• 🔍 Real-time gas prices from multiple sources (aggregated for accuracy)
• 📊 Live monitoring with auto-refresh display
• 🔔 Price alerts - get notified when gas drops below your threshold
• 📈 Gas history - view trends over the past 24+ hours
• 💰 Cost estimation - calculate transaction costs in USD
• 🌐 Multi-network support - Mainnet + L2s (Arbitrum, Optimism, Base, Polygon)
• 📱 Webhook notifications - integrate with Discord, Slack, or custom endpoints
• ⚡ Fast & lightweight - minimal dependencies, runs in seconds

📦 Installation

Via npm (recommended)

npm install -g ethgas-guardian

Via yarn

yarn global add ethgas-guardian

From source

git clone https://github.com/deepdadou/ethgas-guardian.git
cd ethgas-guardian
npm install
npm link

🚀 Quick Start

# Check current gas prices
ethgas now

# Keep watching in real-time (refreshes every 30s)
ethgas watch

# Set an alert for when gas drops below 20 gwei
ethgas alert -t 20

# Estimate transaction cost
ethgas estimate -g 21000

# Compare gas across networks
ethgas compare

📖 Command Reference

ethgas now

Show current gas prices from multiple sources.

# Basic usage
ethgas now

# JSON output for scripting
ethgas now --json

# Specific network
ethgas now --network arbitrum

Example output:

🛡️  ETH Gas Guardian - Current Gas Prices

Speed          Gas Price        Time              Best For
🚀 Rapid       25.3 gwei        < 15s             Urgent transactions
⚡ Fast        22.1 gwei        < 60s             Normal transfers
📊 Standard   18.5 gwei        < 3m              Most transactions
🐢 Slow        15.2 gwei        < 10m             Non-urgent tasks

Sources: etherscan, blocknative, gasnow
Base fee: 16.2 gwei
Priority fee: 2.3 gwei

💡 Recommendation:
✅ Good time to transact! Gas is moderate.
Suitable for most transactions including swaps and NFT mints.

ethgas watch

Continuously monitor gas prices in real-time.

# Watch with default 30s interval
ethgas watch

# Custom interval (10 seconds)
ethgas watch --interval 10

# Alert threshold while watching
ethgas watch --threshold 15

# Monitor specific network
ethgas watch --network base

ethgas alert

Set a price alert to get notified when gas reaches your target.

# Alert when gas drops below 20 gwei (default)
ethgas alert -t 20

# Monitor for 2 hours
ethgas alert -t 15 --duration 120

# Send webhook notification
ethgas alert -t 20 --webhook https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Alert when gas goes ABOVE threshold (for avoiding high gas)
ethgas alert --type above -t 100 --webhook YOUR_WEBHOOK

Webhook payload:

{
  "text": "🚨 Gas Alert Triggered!",
  "gasPrice": 18.5,
  "threshold": 20,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {
    "slow": 15.2,
    "standard": 18.5,
    "fast": 22.1,
    "rapid": 25.3
  }
}

ethgas estimate

Estimate transaction cost based on current gas prices.

# Estimate simple transfer (21,000 gas)
ethgas estimate

# Estimate contract interaction (150,000 gas)
ethgas estimate --gas 150000

# Custom ETH price
ethgas estimate --price 2500

Example output:

💰 Transaction Cost Estimate

Gas Units: 210,000
ETH Price: $2,250

Speed        Gas Price    ETH Cost        USD Cost
Rapid        25.3 gwei    0.005313 ETH     $11.95
Fast         22.1 gwei    0.004641 ETH     $10.44
Standard     18.5 gwei    0.003885 ETH     $8.74
Slow         15.2 gwei    0.003192 ETH     $7.18

💡 Tip: Use "standard" for most transactions to save on costs

ethgas history

View gas price history and trends.

# Last 24 hours
ethgas history

# Last 7 days
ethgas history --hours 168

ethgas compare

Compare gas prices across different networks.

ethgas compare

Example output:

🌐 Gas Price Comparison Across Networks

Network       Gas Price      vs Mainnet    Avg Tx Cost        Savings
Mainnet       18.5 gwei      baseline      $3.89              -
Arbitrum      0.12 gwei      1%            $0.02              99%
Optimism      0.01 gwei      0.1%          $0.002             99.9%
Base          0.01 gwei      0.1%          $0.002             99.9%
Polygon       30.2 gwei      163%          $0.01              99.7%

💡 Consider using L2s for significant gas savings!

ethgas config

Manage configuration settings.

# List current config
ethgas config --list

# Set API key
ethgas config --set etherscanApiKey=YOUR_API_KEY

# Set default network
ethgas config --set defaultNetwork=arbitrum

🔑 API Keys (Optional)

For the best experience, configure API keys from these providers:

1. Etherscan (Free)

1. Visit etherscan.io/apis
2. Create a free account
3. Get your API key
4. Set it:

   ethgas config --set etherscanApiKey=YOUR_KEY

   Or via environment variable:

   export ETHERSCAN_API_KEY=YOUR_KEY

2. BlockNative (Free tier)

1. Visit blocknative.com
2. Sign up for API access
3. Set it:

   ethgas config --set blocknativeApiKey=YOUR_KEY

Note: The tool works without API keys using free public endpoints, but adding keys provides more reliable and accurate data.

🌍 Supported Networks

| Network | Support Level | Notes | |---------|---------------|-------| | Ethereum Mainnet | ✅ Full | Multiple data sources, highest accuracy | | Arbitrum | ✅ Full | RPC-based estimation | | Optimism | ✅ Full | RPC-based estimation | | Base | ✅ Full | RPC-based estimation | | Polygon | ✅ Full | RPC-based estimation | | zkSync Era | ✅ Full | RPC-based estimation | | Scroll | ✅ Full | RPC-based estimation |

💡 Use Cases

For DeFi Users

# Set alert before swapping large amounts
ethgas alert -t 15 --webhook YOUR_DISCORD_WEBHOOK

# Monitor in background while doing other things
ethgas watch --interval 60 --threshold 20

For NFT Collectors

# Check gas before minting
ethgas estimate --gas 250000

# Compare L2 costs
ethgas compare

For Developers

# JSON output for scripts
ethgas now --json | jq '.standard'

# Integrate into CI/CD for optimal deployment timing
node -e "const gas = JSON.parse(require('child_process').execSync('ethgas now --json')); if (gas.standard < 20) process.exit(0); else process.exit(1);"

For Trading Bots

import { GasGuardian } from 'ethgas-guardian';

const guardian = new GasGuardian();
const gas = await guardian.getGasPrices('mainnet');

if (gas.standard < targetGas) {
  await executeTrade();
}

⚙️ Configuration

Configuration is stored in ~/.ethgas-guardian/config.json:

{
  "etherscanApiKey": null,
  "blocknativeApiKey": null,
  "defaultNetwork": "mainnet",
  "refreshInterval": 30,
  "alertThreshold": 20,
  "alertDuration": 60,
  "webhookUrl": null,
  "showUsdEstimates": true,
  "defaultGasUnits": 21000
}

🧪 Programmatic API

import { GasGuardian, AlertManager, ConfigManager } from 'ethgas-guardian';

const config = new ConfigManager();
const guardian = new GasGuardian(config);
const alerts = new AlertManager(config, guardian);

// Get gas prices
const gas = await guardian.getGasPrices('mainnet');
console.log(`Current gas: ${gas.standard} gwei`);

// Get ETH price
const ethPrice = await guardian.getEthPrice();
console.log(`ETH price: $${ethPrice}`);

// Compare networks
const comparison = await guardian.compareNetworks(['mainnet', 'arbitrum', 'optimism']);

// Set up alert
const alertId = alerts.createAlert({
  threshold: 15,
  network: 'mainnet',
  webhook: 'https://your-webhook-url'
});
await alerts.startMonitoring(alertId);

📊 Gas Price Sources

ETH Gas Guardian aggregates data from multiple sources for maximum accuracy:

1. ETH Gas Station - Free tier, good for quick estimates
2. Etherscan Gas Oracle - Requires API key, very reliable
3. BlockNative - Most accurate, includes EIP-1559 details
4. GasNow - Free, Ethereum Foundation sponsored
5. Direct RPC - Fallback for any network

Data is weighted and averaged for optimal accuracy.

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT License - see LICENSE file.

🙏 Acknowledgments

• ETH Gas Station
• Etherscan
• BlockNative
• GasNow

Made with ❤️ by the Mike Wang Team

Star ⭐ this repo if you find it useful!