# Block Endpoints
Block endpoints provide access to block-specific data including rewards, timing information, and statistics.
## Table of Contents
- [Get Block Reward](#get-block-reward)
- [Get Block Countdown](#get-block-countdown)
- [Get Block Number by Timestamp](#get-block-number-by-timestamp)
- [Get Daily Block Size](#get-daily-block-size)
- [Get Daily Block Count](#get-daily-block-count)
- [Get Daily Block Rewards](#get-daily-block-rewards)
---
## Get Block Reward
Get block and uncle reward information for a specific block.
### MCP Tool
`get-block-reward`
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `block` |
| action | Yes | string | Set to `getblockreward` |
| blockno | Yes | number | Block number |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=block&action=getblockreward&blockno=15000000&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": {
"blockNumber": "15000000",
"timeStamp": "1655200000",
"blockMiner": "0x00192fb10df37c9fb26829eb2cc623cd1bf599e8",
"blockReward": "2062500000000000000",
"uncles": [
{
"miner": "0x1234567890123456789012345678901234567890",
"unclePosition": "0",
"blockreward": "625000000000000000"
}
],
"uncleInclusionReward": "62500000000000000"
}
}
```
### Notes
- Block rewards vary by network and consensus mechanism
- Ethereum PoW blocks included base reward + uncle rewards + fees
- Ethereum PoS blocks (post-merge) have different reward structure
- All reward values are in Wei
- `uncles` array contains uncle block information (PoW only)
- `uncleInclusionReward` is the reward for including uncle blocks
---
## Get Block Countdown
Get estimated time until a target block is mined.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `block` |
| action | Yes | string | Set to `getblockcountdown` |
| blockno | Yes | number | Target block number |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=block&action=getblockcountdown&blockno=20000000&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": {
"CurrentBlock": "19500000",
"CountdownBlock": "20000000",
"RemainingBlock": "500000",
"EstimateTimeInSec": "6000000"
}
}
```
### Notes
- Estimation based on average block time
- Block times vary by network:
- Ethereum: ~12 seconds
- Polygon: ~2 seconds
- BNB Chain: ~3 seconds
- Arbitrum: ~0.25 seconds
- Use for planning upgrades, launches, or time-locked events
- Actual time may vary based on network conditions
---
## Get Block Number by Timestamp
Get the block number closest to a specific timestamp.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `block` |
| action | Yes | string | Set to `getblocknobytime` |
| timestamp | Yes | number | Unix timestamp |
| closest | Yes | string | `before` or `after` |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get block before timestamp
curl "https://api.etherscan.io/v2/api?chainid=1&module=block&action=getblocknobytime×tamp=1698765432&closest=before&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "18500000"
}
```
### Notes
- `closest=before`: Returns the last block before or at the timestamp
- `closest=after`: Returns the first block after or at the timestamp
- Useful for:
- Historical data analysis
- Finding blocks for specific events
- Time-based queries
- Event correlation
- Timestamp is Unix time (seconds since epoch)
### Example Use Cases
```bash
# Find block for a specific date
# January 1, 2024 00:00:00 UTC = 1704067200
curl "https://api.etherscan.io/v2/api?chainid=1&module=block&action=getblocknobytime×tamp=1704067200&closest=before&apikey=YourApiKey"
# Find block right after an event
curl "https://api.etherscan.io/v2/api?chainid=1&module=block&action=getblocknobytime×tamp=1698765432&closest=after&apikey=YourApiKey"
```
---
## Get Daily Block Size
Get average block size for a specific date range.
### 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 `dailyavgblocksize` |
| 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=dailyavgblocksize&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",
"blockSize_bytes": "89524"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"blockSize_bytes": "91234"
}
]
}
```
### Notes
- Block size in bytes
- Represents average daily block size
- Useful for network capacity analysis
- Block size limits vary by network
---
## Get Daily Block Count
Get the number of blocks mined 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 `dailyblkcount` |
| 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=dailyblkcount&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",
"blockCount": "7200"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"blockCount": "7185"
}
]
}
```
### Notes
- Block count varies by network block time
- Ethereum: ~7,200 blocks per day (12s block time)
- Polygon: ~43,200 blocks per day (2s block time)
- Useful for:
- Network health monitoring
- Block time analysis
- Validator performance tracking
---
## Get Daily Block Rewards
Get total block rewards distributed 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 `dailyblockrewards` |
| 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=dailyblockrewards&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",
"blockRewards_Eth": "14400.5"
},
{
"UTCDate": "2024-01-02",
"unixTimeStamp": "1704153600",
"blockRewards_Eth": "14370.2"
}
]
}
```
### Notes
- Rewards are shown in native currency (ETH for Ethereum)
- Includes base rewards + transaction fees
- Ethereum PoW: 2 ETH base + fees per block
- Ethereum PoS: Variable based on validator participation
- Does not include MEV rewards
---
## Block Data Fields Reference
### Common Block Fields
| Field | Type | Description |
|-------|------|-------------|
| blockNumber | string | Block number |
| timeStamp | string | Unix timestamp when block was mined |
| blockMiner | string | Address of miner/validator |
| blockReward | string | Block reward in Wei |
| blockHash | string | Block hash |
| parentHash | string | Previous block hash |
| difficulty | string | Block difficulty (PoW) |
| gasUsed | string | Total gas used in block |
| gasLimit | string | Gas limit for block |
### Block Time by Network
| Network | Average Block Time |
|---------|-------------------|
| Ethereum | 12 seconds |
| Arbitrum | 0.25 seconds |
| Optimism | 2 seconds |
| Base | 2 seconds |
| Polygon | 2 seconds |
| BNB Chain | 3 seconds |
| Avalanche | 2 seconds |
## Error Codes
| Status | Message | Description |
|--------|---------|-------------|
| 0 | Invalid block number | Block doesn't exist or invalid format |
| 0 | Block not found | Block number out of range |
| 0 | Invalid date format | Date must be YYYY-MM-DD |
| 0 | Date range too large | Maximum 365 days |
## Rate Limits
- Free tier: **5 calls/second**
- Historical data queries may take longer
- Use date ranges to limit response size
## Use Cases
### Network Analysis
- Monitor block production consistency
- Track block size trends
- Analyze block reward changes
### Developer Tools
- Estimate transaction confirmation times
- Find historical blocks for testing
- Plan contract deployments
### Research
- Study network growth
- Analyze consensus changes
- Compare network performance
## See Also
- [Account Endpoints](./account-endpoints.md)
- [Statistics Endpoints](./stats-endpoints.md)
- [Network Support](./NETWORK_SUPPORT.md)
