# Network Statistics Endpoints
Statistics endpoints provide network-wide metrics and historical data for blockchain analysis.
## Table of Contents
- [Get Total ETH Supply](#get-total-eth-supply)
- [Get ETH Last Price](#get-eth-last-price)
- [Get ETH Historical Price](#get-eth-historical-price)
- [Get Ethereum Nodes Size](#get-ethereum-nodes-size)
- [Get Daily Transaction Count](#get-daily-transaction-count)
- [Get Daily Network Utilization](#get-daily-network-utilization)
- [Get Daily New Address Count](#get-daily-new-address-count)
- [Get Daily Network Hash Rate](#get-daily-network-hash-rate)
---
## Get Total ETH Supply
Get the current total supply of ETH (or native token for other networks).
### 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 `ethsupply` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=ethsupply&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "120523456789012345678901234"
}
```
### Notes
- Result is in **Wei** (1 ETH = 10^18 Wei)
- For Ethereum mainnet: Total supply includes all minted ETH
- Post-merge (PoS): Supply can be deflationary due to EIP-1559 burns
- Other networks: Returns native token supply (MATIC, BNB, AVAX, etc.)
### Convert to ETH
```javascript
const supplyWei = "120523456789012345678901234";
const supplyEth = Number(supplyWei) / 1e18;
console.log(`Total Supply: ${supplyEth.toLocaleString()} ETH`);
// Total Supply: 120,523,456.789... ETH
```
---
## Get ETH Last Price
Get the latest price of ETH (or native token) in USD and BTC.
### 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 `ethprice` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=ethprice&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": {
"ethbtc": "0.05234",
"ethbtc_timestamp": "1698765432",
"ethusd": "2345.67",
"ethusd_timestamp": "1698765432"
}
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| ethbtc | ETH price in BTC |
| ethbtc_timestamp | Last update timestamp (Unix) |
| ethusd | ETH price in USD |
| ethusd_timestamp | Last update timestamp (Unix) |
### Notes
- Prices are updated every ~5 minutes
- Source: Multiple exchange aggregators
- For other networks: Returns native token price (MATIC/USD, BNB/USD, etc.)
- Useful for:
- Transaction cost calculations
- Portfolio valuation
- Historical analysis
---
## Get ETH Historical Price
Get historical price data for a specific date.
### 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 `ethprice` |
| timestamp | Yes | number | Unix timestamp |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get ETH price on January 1, 2024
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=ethprice×tamp=1704067200&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": {
"ethbtc": "0.05123",
"ethusd": "2287.45"
}
}
```
### Notes
- Returns price closest to the specified timestamp
- Historical data available from Ethereum genesis
- Useful for:
- Cost analysis at transaction time
- ROI calculations
- Tax reporting
---
## Get Ethereum Nodes Size
Get the size of the Ethereum node data (archive node).
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID (1 for Ethereum) |
| module | Yes | string | Set to `stats` |
| action | Yes | string | Set to `chainsize` |
| startdate | Yes | string | Start date (YYYY-MM-DD) |
| enddate | Yes | string | End date (YYYY-MM-DD) |
| clienttype | Yes | string | `geth` or `parity` |
| syncmode | Yes | string | `default` or `archive` |
| 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=chainsize&startdate=2024-01-01&enddate=2024-01-07&clienttype=geth&syncmode=default&sort=asc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"blockNumber": "18900000",
"chainTimeStamp": "2024-01-01",
"chainSize": "950123456789",
"clientType": "geth",
"syncMode": "default"
},
{
"blockNumber": "18906000",
"chainTimeStamp": "2024-01-02",
"chainSize": "951234567890",
"clientType": "geth",
"syncMode": "default"
}
]
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| blockNumber | Block number |
| chainTimeStamp | Date |
| chainSize | Size in bytes |
| clientType | Node client type |
| syncMode | Sync mode |
### Notes
- Size in bytes
- Archive nodes are much larger than default (pruned) nodes
- Geth typical sizes:
- Default mode: ~400-500 GB
- Archive mode: ~12-14 TB
- Growth rate: ~100-150 GB per year (default mode)
---
## Get Daily Transaction Count
Get the number of transactions 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 `dailytx` |
| 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=dailytx&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",
"transactionCount": "1234567"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"transactionCount": "1189234"
}
]
}
```
### Notes
- Includes all transaction types (transfers, contract calls, etc.)
- Ethereum typical range: 1-1.5 million transactions/day
- Spikes during:
- NFT mints
- DeFi events
- Airdrops
- Useful for network activity analysis
---
## Get Daily Network Utilization
Get network utilization as percentage of gas used vs gas limit.
### 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 `dailynetutilization` |
| 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=dailynetutilization&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",
"networkUtilization": "0.52"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"networkUtilization": "0.48"
}
]
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| networkUtilization | Ratio of gas used to gas limit (0-1) |
### Notes
- Value range: 0.0 to 1.0 (0% to 100%)
- High utilization (>90%): Network congestion
- Low utilization (<50%): Plenty of capacity
- Ethereum typical: 45-55% utilization
- Useful for:
- Capacity planning
- Congestion analysis
- Gas price prediction
---
## Get Daily New Address Count
Get the number of new addresses created 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 `dailynewaddress` |
| 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=dailynewaddress&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",
"newAddressCount": "125678"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"newAddressCount": "118234"
}
]
}
```
### Notes
- "New address" = address that received its first transaction
- Includes both EOAs (wallets) and contract addresses
- Ethereum typical: 100-150k new addresses/day
- Growth indicator for network adoption
- Spikes during:
- Major airdrops
- New protocol launches
- Bull market periods
---
## Get Daily Network Hash Rate
Get the network hash rate per day (Proof of Work chains only).
### 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 `dailyavghashrate` |
| 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
# Note: Only available on PoW chains (pre-merge Ethereum, etc.)
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=dailyavghashrate&startdate=2022-01-01&enddate=2022-01-07&sort=asc&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"UTCDate": "2022-01-01",
"unixTimeStamp": "1640995200",
"networkHashRate": "920000000000000"
},
{
"UTCDate": "2022-01-02",
"unixTimeStamp": "1641081600",
"networkHashRate": "925000000000000"
}
]
}
```
### Notes
- **Only available on Proof of Work networks**
- Not available on Ethereum post-merge (September 2022)
- Hash rate in H/s (hashes per second)
- Available on networks like:
- Ethereum Classic
- Bitcoin-compatible chains
- Indicates mining power and network security
---
## Network Comparison Table
### Transaction Volume (Daily Average)
| Network | Typical Daily Transactions |
|---------|---------------------------|
| Ethereum | 1.0-1.5M |
| Polygon | 2.5-4M |
| BNB Chain | 3-5M |
| Arbitrum | 800k-1.2M |
| Optimism | 500-800k |
| Base | 1-2M |
### Network Utilization (Target %)
| Network | Typical Utilization |
|---------|-------------------|
| Ethereum | 45-55% |
| Polygon | 30-40% |
| BNB Chain | 35-45% |
| Arbitrum | 20-30% |
| Optimism | 25-35% |
---
## Use Cases
### Network Health Monitoring
```bash
# Check daily stats for a week
for stat in dailytx dailynetutilization dailynewaddress; do
echo "Fetching $stat..."
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=$stat&startdate=2024-01-01&enddate=2024-01-07&apikey=YourApiKey"
done
```
### Price Tracking
```javascript
// Get current price every 5 minutes
setInterval(async () => {
const response = await fetch(
'https://api.etherscan.io/v2/api?chainid=1&module=stats&action=ethprice&apikey=YourApiKey'
);
const data = await response.json();
const price = data.result.ethusd;
console.log(`ETH Price: $${price}`);
}, 300000);
```
### Growth Analysis
```javascript
// Analyze network growth
const txResponse = await fetch(
'https://api.etherscan.io/v2/api?chainid=1&module=stats&action=dailytx&startdate=2024-01-01&enddate=2024-12-31&apikey=YourApiKey'
);
const txData = await txResponse.json();
const addressResponse = await fetch(
'https://api.etherscan.io/v2/api?chainid=1&module=stats&action=dailynewaddress&startdate=2024-01-01&enddate=2024-12-31&apikey=YourApiKey'
);
const addressData = await addressResponse.json();
// Calculate growth metrics
const avgTxGrowth = calculateGrowth(txData.result);
const avgAddressGrowth = calculateGrowth(addressData.result);
console.log(`Transaction growth: ${avgTxGrowth}%`);
console.log(`Address growth: ${avgAddressGrowth}%`);
```
---
## Error Codes
| Status | Message | Description |
|--------|---------|-------------|
| 0 | Invalid date range | Date range too large or invalid format |
| 0 | No data available | No statistics for specified period |
| 0 | Invalid client type | Use 'geth' or 'parity' |
| 0 | Feature not available | Stat not available on this network |
## Rate Limits
- Free tier: **5 calls/second**
- Date range limit: Maximum **365 days**
- Historical data: Available from chain genesis
## Data Update Frequency
| Endpoint | Update Frequency |
|----------|-----------------|
| ethprice | ~5 minutes |
| ethsupply | ~15 minutes |
| dailytx | Once per day (UTC) |
| dailynetutilization | Once per day (UTC) |
| dailynewaddress | Once per day (UTC) |
## See Also
- [Gas Tracker Endpoints](./gas-tracker-endpoints.md)
- [Block Endpoints](./blocks-endpoints.md)
- [Network Support](./NETWORK_SUPPORT.md)
