# Gas Tracker Endpoints
Gas tracker endpoints provide real-time and historical gas price data to help optimize transaction costs.
## Table of Contents
- [Get Gas Oracle](#get-gas-oracle)
- [Get Estimated Confirmation Time](#get-estimated-confirmation-time)
- [Get Daily Average Gas Limit](#get-daily-average-gas-limit)
- [Get Daily Total Gas Used](#get-daily-total-gas-used)
- [Get Daily Average Gas Price](#get-daily-average-gas-price)
---
## Get Gas Oracle
Get current gas price recommendations for different transaction speeds.
### MCP Tool
`get-gas-prices`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `gastracker` |
| action | Yes | string | Set to `gasoracle` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=gastracker&action=gasoracle&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": {
"LastBlock": "19500000",
"SafeGasPrice": "15",
"ProposeGasPrice": "20",
"FastGasPrice": "25",
"suggestBaseFee": "14.5",
"gasUsedRatio": "0.485,0.512,0.498,0.489,0.503"
}
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| LastBlock | Latest block number |
| SafeGasPrice | Safe (slow) gas price in Gwei (~10 minutes) |
| ProposeGasPrice | Standard gas price in Gwei (~3 minutes) |
| FastGasPrice | Fast gas price in Gwei (~30 seconds) |
| suggestBaseFee | Suggested base fee in Gwei (EIP-1559) |
| gasUsedRatio | Gas usage ratio for last 5 blocks |
### Notes
- Prices are in **Gwei** (1 Gwei = 10^9 Wei)
- **EIP-1559 Networks**: Use `suggestBaseFee` as base, add priority fee
- **Legacy Networks**: Use SafeGasPrice/ProposeGasPrice/FastGasPrice directly
- Update frequency: Every block (~12 seconds on Ethereum)
### Gas Price Tiers Explained
| Tier | Confirmation Time | Use Case |
|------|------------------|----------|
| Safe | ~10 minutes | Non-urgent transactions, batch operations |
| Propose | ~3 minutes | Standard transactions, most use cases |
| Fast | ~30 seconds | Time-sensitive transactions, trading |
### EIP-1559 Transaction Example
```javascript
// Using suggested base fee
const baseFee = result.suggestBaseFee; // 14.5 Gwei
const priorityFee = 2; // 2 Gwei tip to miner
const maxFeePerGas = baseFee * 1.2 + priorityFee; // 19.4 Gwei
const tx = {
to: '0x...',
value: ethers.parseEther('0.1'),
maxFeePerGas: ethers.parseUnits(maxFeePerGas.toString(), 'gwei'),
maxPriorityFeePerGas: ethers.parseUnits(priorityFee.toString(), 'gwei')
};
```
---
## Get Estimated Confirmation Time
Estimate how long a transaction will take to confirm based on gas price.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `gastracker` |
| action | Yes | string | Set to `gasestimate` |
| gasprice | Yes | number | Gas price in Gwei |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=gastracker&action=gasestimate&gasprice=20&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "180"
}
```
### Notes
- Result is in **seconds**
- Based on historical confirmation times
- Actual time may vary based on network conditions
- Lower gas prices = longer confirmation times
- During high network congestion, estimates may be less accurate
### Usage Example
```bash
# Fast confirmation (25 Gwei)
curl "https://api.etherscan.io/v2/api?chainid=1&module=gastracker&action=gasestimate&gasprice=25&apikey=YourApiKey"
# Returns: ~30 seconds
# Standard confirmation (20 Gwei)
curl "https://api.etherscan.io/v2/api?chainid=1&module=gastracker&action=gasestimate&gasprice=20&apikey=YourApiKey"
# Returns: ~180 seconds
# Safe confirmation (15 Gwei)
curl "https://api.etherscan.io/v2/api?chainid=1&module=gastracker&action=gasestimate&gasprice=15&apikey=YourApiKey"
# Returns: ~600 seconds
```
---
## Get Daily Average Gas Limit
Get the average gas limit per day.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `stats` |
| action | Yes | string | Set to `dailyavggaslimit` |
| startdate | Yes | string | Start date (YYYY-MM-DD) |
| enddate | Yes | string | End date (YYYY-MM-DD) |
| sort | No | string | `asc` or `desc` (default: asc) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=dailyavggaslimit&startdate=2024-01-01&enddate=2024-01-07&sort=asc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"UTCDate": "2024-01-01",
"unixTimeStamp": "1704067200",
"gasLimit": "30000000"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"gasLimit": "30000000"
}
]
}
```
### Notes
- Gas limit is the maximum gas per block
- Ethereum mainnet: ~30,000,000 gas per block
- Gas limit adjusts based on network demand
- Higher limits = more transactions per block
- Useful for capacity planning
---
## Get Daily Total Gas Used
Get the total gas consumed per day across all transactions.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `stats` |
| action | Yes | string | Set to `dailygasused` |
| startdate | Yes | string | Start date (YYYY-MM-DD) |
| enddate | Yes | string | End date (YYYY-MM-DD) |
| sort | No | string | `asc` or `desc` (default: asc) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=dailygasused&startdate=2024-01-01&enddate=2024-01-07&sort=asc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"UTCDate": "2024-01-01",
"unixTimeStamp": "1704067200",
"gasUsed": "12500000000"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"gasUsed": "13200000000"
}
]
}
```
### Notes
- Total gas used across all blocks in a day
- Indicates network activity level
- High gas usage = high network demand
- Useful for:
- Network utilization analysis
- Activity trend tracking
- Congestion monitoring
---
## Get Daily Average Gas Price
Get the average gas price per day.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `stats` |
| action | Yes | string | Set to `dailyavggasprice` |
| startdate | Yes | string | Start date (YYYY-MM-DD) |
| enddate | Yes | string | End date (YYYY-MM-DD) |
| sort | No | string | `asc` or `desc` (default: asc) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=dailyavggasprice&startdate=2024-01-01&enddate=2024-01-07&sort=asc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"UTCDate": "2024-01-01",
"unixTimeStamp": "1704067200",
"maxGasPrice_Wei": "50000000000",
"minGasPrice_Wei": "10000000000",
"avgGasPrice_Wei": "20000000000"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"maxGasPrice_Wei": "45000000000",
"minGasPrice_Wei": "12000000000",
"avgGasPrice_Wei": "22000000000"
}
]
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| maxGasPrice_Wei | Highest gas price in Wei |
| minGasPrice_Wei | Lowest gas price in Wei |
| avgGasPrice_Wei | Average gas price in Wei |
### Notes
- Prices are in Wei (divide by 10^9 for Gwei)
- Shows price volatility (max vs min)
- Useful for historical analysis and trending
- Plan transactions during low-price periods
---
## Gas Price by Network
Typical gas prices vary significantly by network:
| Network | Typical Range (Gwei) | Notes |
|---------|---------------------|-------|
| Ethereum | 5-50 | Higher during peak hours |
| Arbitrum | 0.01-0.1 | Very low, L2 optimization |
| Optimism | 0.001-0.01 | Very low, L2 optimization |
| Base | 0.001-0.01 | Very low, L2 optimization |
| Polygon | 30-200 | In native MATIC |
| BNB Chain | 3-5 | In native BNB |
| Avalanche | 25-50 | In native AVAX |
## Transaction Cost Calculation
### Standard Transfer (21,000 gas)
```
Cost = Gas Used × Gas Price
Cost in ETH = 21,000 × (Gas Price in Gwei) / 10^9
Example:
Gas Price: 20 Gwei
Cost = 21,000 × 20 / 10^9 = 0.00042 ETH
```
### Token Transfer (~65,000 gas)
```
Cost = 65,000 × (Gas Price in Gwei) / 10^9
Example:
Gas Price: 20 Gwei
Cost = 65,000 × 20 / 10^9 = 0.0013 ETH
```
### Complex DeFi Transaction (~200,000 gas)
```
Cost = 200,000 × (Gas Price in Gwei) / 10^9
Example:
Gas Price: 20 Gwei
Cost = 200,000 × 20 / 10^9 = 0.004 ETH
```
## Optimization Tips
### Save on Gas Costs
1. **Time Your Transactions**: Use gas oracle to find low-price periods
2. **Batch Operations**: Combine multiple operations into one transaction
3. **Use L2 Networks**: Arbitrum, Optimism, Base for lower costs
4. **Optimize Contracts**: Write efficient Solidity code
5. **Set Appropriate Limits**: Don't overpay with excessive gas prices
### Best Times to Transact (Ethereum)
**Lowest Gas Prices (UTC)**:
- Weekend mornings
- Weekday early mornings (2am-6am)
- Avoid: Weekday evenings, major NFT drops, DeFi events
## Monitoring Tools
### Set Up Alerts
```javascript
// Check gas price every 5 minutes
setInterval(async () => {
const response = await fetch(
'https://api.etherscan.io/v2/api?chainid=1&module=gastracker&action=gasoracle&apikey=YourApiKey'
);
const data = await response.json();
const gasPrice = data.result.ProposeGasPrice;
if (gasPrice < 15) {
console.log(`Gas price low: ${gasPrice} Gwei - Good time to transact!`);
}
}, 300000); // 5 minutes
```
## Error Codes
| Status | Message | Description |
|--------|---------|-------------|
| 0 | Invalid gas price | Gas price must be positive |
| 0 | Date range too large | Maximum 365 days |
| 0 | Invalid date format | Use YYYY-MM-DD format |
## Rate Limits
- Free tier: **5 calls/second**
- Gas oracle: Update every block
- Historical data: Cache for efficiency
## Use Cases
### Application Integration
- Display current gas prices in wallet
- Estimate transaction costs
- Auto-adjust gas for optimal confirmation
### Cost Analysis
- Track gas spending over time
- Budget for contract deployments
- Compare networks for cost efficiency
### Trading Bots
- Adjust strategy based on gas prices
- Skip trades during high-gas periods
- Optimize MEV opportunities
## See Also
- [Transaction Endpoints](./account-endpoints.md)
- [Statistics Endpoints](./stats-endpoints.md)
- [Network Support](./NETWORK_SUPPORT.md)
- [EIP-1559 Documentation](https://eips.ethereum.org/EIPS/eip-1559)
