# Etherscan v2 API Documentation
Welcome to the comprehensive documentation for the Etherscan v2 API integration in the MCP Etherscan Server.
## Overview
The Etherscan v2 API provides unified access to blockchain data across 70+ networks including Ethereum mainnet, Layer 2 solutions, sidechains, and testnets. The v2 API uses a single base URL (`https://api.etherscan.io/v2/api`) with a `chainid` parameter to specify the target network.
## What's New in v2
### Unified API Endpoint
- **v1**: Used separate domain names for each network (e.g., `api.etherscan.io`, `api.arbiscan.io`, `api.polygonscan.com`)
- **v2**: Single base URL with `chainid` parameter: `https://api.etherscan.io/v2/api?chainid=1`
### Expanded Network Support
- **70+ networks** including mainnets and testnets
- All Ethereum Layer 2 solutions (Arbitrum, Optimism, Base, zkSync, etc.)
- Major sidechains (Polygon, BNB Chain, Avalanche, etc.)
- Emerging networks (Sonic, Berachain, Unichain, etc.)
### Consistent API Structure
All endpoints follow the same pattern:
```
https://api.etherscan.io/v2/api?chainid={CHAIN_ID}&module={MODULE}&action={ACTION}&{PARAMS}&apikey={API_KEY}
```
## Quick Start
### Authentication
All API requests require an API key. Get your free API key at [https://etherscan.io/apis](https://etherscan.io/apis).
### Basic Request Example
```bash
# Get ETH balance on Ethereum mainnet (chainid=1)
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balance&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&apikey=YourApiKey"
```
### Response Format
All endpoints return JSON in this structure:
```json
{
"status": "1",
"message": "OK",
"result": "..."
}
```
- `status`: "1" for success, "0" for error
- `message`: Status message or error description
- `result`: Response data (format varies by endpoint)
## API Rate Limits
- **Free Plan**: 5 calls/second, 100,000 calls/day
- **Standard Plan**: Higher limits available with paid subscriptions
> **Note**: Rate limits are shared across all networks.
## Network Specification
You can specify the target network in two ways:
1. **Chain ID (Recommended)**: `chainid=1`
2. **Network Slug**: `chainid=ethereum` (alias for chain ID)
See [NETWORK_SUPPORT.md](./NETWORK_SUPPORT.md) for a complete list of supported networks and their chain IDs.
## API Modules
The v2 API is organized into modules, each handling a specific type of blockchain data:
### [Account Operations](./account-endpoints.md)
Query account balances, transactions, token transfers, and beacon withdrawals.
- Balance queries (single and multi-address)
- Transaction history
- Internal transactions
- ERC20/ERC721/ERC1155 token transfers
- Mined blocks
- Beacon chain withdrawals
### [Block Operations](./blocks-endpoints.md)
Access block information, rewards, and statistics.
- Block rewards
- Block countdown
- Block number by timestamp
- Daily block statistics
### [Contract Operations](./contracts-endpoints.md)
Interact with smart contracts and verification.
- Contract ABI retrieval
- Contract source code
- Contract creation information
- Contract verification (source code and proxy)
### [Gas Tracker](./gas-tracker-endpoints.md)
Monitor gas prices and network usage.
- Current gas oracle prices
- Gas price estimation
- Daily gas statistics
### [Event Logs](./logs-endpoints.md)
Query contract event logs with advanced filtering.
- Logs by address
- Logs by topics
- Combined address and topic filtering
### [Network Statistics](./stats-endpoints.md)
Get network-wide statistics and metrics.
- ETH supply
- ETH price feeds
- Node size
- Transaction counts
- Network utilization
### [Token Information](./tokens-endpoints.md)
Query ERC20 token data and holder information.
- Token metadata
- Token holder lists
- Token balances
- Address token portfolio
- Token supply
## Using with MCP Server
This documentation describes the underlying Etherscan v2 API. When using the MCP Etherscan Server, these endpoints are exposed as MCP tools with user-friendly names:
| MCP Tool | API Module | API Action |
|----------|------------|------------|
| `check-balance` | account | balance |
| `get-transactions` | account | txlist |
| `get-token-transfers` | account | tokentx |
| `get-contract-abi` | contract | getabi |
| `get-gas-prices` | gastracker | gasoracle |
See the main [README.md](../../README.md) for MCP-specific usage.
## Migration from v1
If you're migrating from the v1 API:
1. **Update Base URL**: Replace network-specific URLs with `https://api.etherscan.io/v2/api`
2. **Add chainid Parameter**: Add `chainid={CHAIN_ID}` to all requests
3. **Update Network References**: Use chain IDs instead of network names in code
4. **Test Thoroughly**: Response formats are generally the same, but validate your integration
### v1 Example
```bash
# Ethereum mainnet
curl "https://api.etherscan.io/api?module=account&action=balance&address=0x123...&apikey=KEY"
# Polygon
curl "https://api.polygonscan.com/api?module=account&action=balance&address=0x123...&apikey=KEY"
```
### v2 Example
```bash
# Ethereum mainnet (chainid=1)
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balance&address=0x123...&apikey=KEY"
# Polygon (chainid=137)
curl "https://api.etherscan.io/v2/api?chainid=137&module=account&action=balance&address=0x123...&apikey=KEY"
```
## Additional Resources
- [Etherscan Official API Documentation](https://docs.etherscan.io/)
- [MCP Server GitHub Repository](https://github.com/crazyrabbitltc/mcp-etherscan-server)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
## Support
For issues related to:
- **Etherscan API**: Visit [Etherscan Support](https://etherscan.io/contactus)
- **MCP Server**: Open an issue on [GitHub](https://github.com/crazyrabbitltc/mcp-etherscan-server/issues)
## Next Steps
1. Review the [Network Support](./NETWORK_SUPPORT.md) page to find chain IDs for your target networks
2. Explore specific endpoint documentation:
- [Account Endpoints](./account-endpoints.md)
- [Block Endpoints](./blocks-endpoints.md)
- [Contract Endpoints](./contracts-endpoints.md)
- [Gas Tracker Endpoints](./gas-tracker-endpoints.md)
- [Log Endpoints](./logs-endpoints.md)
- [Statistics Endpoints](./stats-endpoints.md)
- [Token Endpoints](./tokens-endpoints.md)
