@cryptodevops/n8n-nodes-blockchain-explorer
Version:
n8n node for accessing multiple blockchain networks (Ethereum, BSC, Polygon, Fantom, Avalanche, Arbitrum, Optimism, etc.) with comprehensive analytics and data retrieval capabilities
372 lines (285 loc) • 12 kB
Markdown
# n8n-nodes-etherscan
[](https://badge.fury.io/js/%40cryptodevops%2Fn8n-nodes-etherscan)
[](https://opensource.org/licenses/MIT)
A comprehensive n8n community node package for accessing multiple blockchain networks via Etherscan-compatible APIs. This package provides powerful blockchain analytics and data retrieval capabilities across major EVM-compatible networks.
## 🌐 Supported Blockchains
| Blockchain | Native Token | Chain ID | Explorer | API Endpoint | Testnet |
|------------|--------------|----------|----------|--------------|---------|
| **Ethereum** | ETH | 1 / 11155111 | [Etherscan.io](https://etherscan.io) | `https://api.etherscan.io/api` | Sepolia |
| **Binance Smart Chain** | BNB | 56 / 97 | [BscScan.com](https://bscscan.com) | `https://api.bscscan.com/api` | BSC Testnet |
| **Polygon** | MATIC | 137 / 80001 | [PolygonScan.com](https://polygonscan.com) | `https://api.polygonscan.com/api` | Mumbai |
| **Fantom** | FTM | 250 / 4002 | [FtmScan.com](https://ftmscan.com) | `https://api.ftmscan.com/api` | Fantom Testnet |
| **Avalanche** | AVAX | 43114 / 43113 | [SnowTrace.io](https://snowtrace.io) | `https://api.snowtrace.io/api` | Fuji |
| **Arbitrum** | ETH | 42161 / 421613 | [Arbiscan.io](https://arbiscan.io) | `https://api.arbiscan.io/api` | Arbitrum Goerli |
| **Optimism** | ETH | 10 / 420 | [Optimistic.Etherscan.io](https://optimistic.etherscan.io) | `https://api-optimistic.etherscan.io/api` | Optimism Goerli |
| **Cronos** | CRO | 25 / 338 | [CronoScan.com](https://cronoscan.com) | `https://api.cronoscan.com/api` | Cronos Testnet |
| **Moonbeam** | GLMR | 1284 / 1287 | [Moonscan.io](https://moonscan.io) | `https://api-moonbeam.moonscan.io/api` | Moonbase Alpha |
| **Celo** | CELO | 42220 / 44787 | [CeloScan.io](https://celoscan.io) | `https://api.celoscan.io/api` | Alfajores |
### 🔑 API Keys & Rate Limits
| Network | Free Tier | Rate Limit | Daily Limit | Registration |
|---------|-----------|------------|-------------|--------------|
| **Ethereum** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://etherscan.io/apis) |
| **BSC** | ✅ | 5 req/sec | 10,000 | [Get API Key](https://bscscan.com/apis) |
| **Polygon** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://polygonscan.com/apis) |
| **Fantom** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://ftmscan.com/apis) |
| **Avalanche** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://snowtrace.io/apis) |
| **Arbitrum** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://arbiscan.io/apis) |
| **Optimism** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://optimistic.etherscan.io/apis) |
| **Cronos** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://cronoscan.com/apis) |
| **Moonbeam** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://moonscan.io/apis) |
| **Celo** | ✅ | 5 req/sec | 100,000 | [Get API Key](https://celoscan.io/apis) |
### 🌍 Network Endpoints
#### Mainnet Endpoints
```
Ethereum: https://api.etherscan.io/api
BSC: https://api.bscscan.com/api
Polygon: https://api.polygonscan.com/api
Fantom: https://api.ftmscan.com/api
Avalanche: https://api.snowtrace.io/api
Arbitrum: https://api.arbiscan.io/api
Optimism: https://api-optimistic.etherscan.io/api
Cronos: https://api.cronoscan.com/api
Moonbeam: https://api-moonbeam.moonscan.io/api
Celo: https://api.celoscan.io/api
```
#### Testnet Endpoints
```
Ethereum (Sepolia): https://api-sepolia.etherscan.io/api
BSC (Testnet): https://api-testnet.bscscan.com/api
Polygon (Mumbai): https://api-testnet.polygonscan.com/api
Fantom (Testnet): https://api-testnet.ftmscan.com/api
Avalanche (Fuji): https://api-testnet.snowtrace.io/api
Arbitrum (Goerli): https://api-goerli.arbiscan.io/api
Optimism (Goerli): https://api-goerli-optimistic.etherscan.io/api
Cronos (Testnet): https://api-testnet.cronoscan.com/api
Moonbeam (Moonbase): https://api-moonbase.moonscan.io/api
Celo (Alfajores): https://api-alfajores.celoscan.io/api
```
## 📦 Available Nodes
This package provides two complementary nodes:
### 1. **Etherscan Node** (Original)
- Focused specifically on Ethereum networks
- Supports Ethereum Mainnet, Goerli, and Sepolia testnets
- Optimized for Ethereum-specific operations
### 2. **Blockchain Explorer Node** (New)
- Multi-blockchain support across 10+ networks
- Unified API interface for all supported blockchains
- Dynamic network selection with mainnet/testnet options
- Custom base URL support for additional networks
## Features
This package provides two main nodes:
### 1. Etherscan Node (Ethereum only) - ⚠️ DEPRECATED
> **Migration Notice**: The Etherscan node is deprecated and will be removed in a future version. Please migrate to the Blockchain Explorer node for better multi-chain support. See [MIGRATION-GUIDE.md](./MIGRATION-GUIDE.md) for detailed instructions.
- **Account**: Get balance, transaction history, token transfers
- **Block**: Get block information and rewards
- **Contract**: Get ABI and source code
- **Gas**: Get gas price information
- **Statistics**: Get ETH supply and price data
- **Token**: Get token supply and balance information
- **Transaction**: Get transaction receipt status
### 2. Blockchain Explorer Node (Multi-blockchain support) - ✅ RECOMMENDED
Supports 10+ blockchain networks with comprehensive operations:
#### 🔍 Account Operations
- **Get Balance**: Retrieve ETH balance for single or multiple addresses
- **Transaction History**: Get normal and internal transactions by address
- **Token Transfers**: Access ERC20 and ERC721 token transfer events
#### 📦 Block Operations
- **Block Rewards**: Get block and uncle rewards by block number
- **Block by Timestamp**: Find block numbers by Unix timestamp
#### 📄 Contract Operations
- **Contract ABI**: Get verified contract ABIs
- **Source Code**: Access verified contract source code
#### ⛽ Gas Operations
- **Gas Oracle**: Real-time gas price recommendations
#### 📊 Statistics
- **ETH Supply**: Total ETH supply information
- **ETH Price**: Current ETH price data
#### 🪙 Token Operations
- **Token Supply**: Get ERC20 token total supply
- **Token Balance**: Check ERC20 token balances
#### 🔄 Transaction Operations
- **Transaction Status**: Get transaction execution status
## Installation
### From npm Registry
```bash
npm install @cryptodevops/n8n-nodes-etherscan
```
### Manual Installation
1. Clone this repository
2. Install dependencies: `npm install`
3. Build the node: `npm run build`
4. Link to your n8n installation
## Configuration
### API Credentials Setup
#### For Etherscan Node (Ethereum only)
1. **Get an API Key**: Visit [Etherscan.io](https://etherscan.io/apis) and create a free account
2. **Configure in n8n**:
- Go to Settings → Credentials
- Add new credential of type "Etherscan API"
- Enter your API key and select the network
#### For Blockchain Explorer Node (Multi-chain)
1. **Get API Keys** for your desired networks:
- **Ethereum**: [Etherscan.io](https://etherscan.io/apis)
- **BSC**: [BscScan.com](https://bscscan.com/apis)
- **Polygon**: [PolygonScan.com](https://polygonscan.com/apis)
- **Fantom**: [FtmScan.com](https://ftmscan.com/apis)
- **Avalanche**: [SnowTrace.io](https://snowtrace.io/apis)
- **Arbitrum**: [Arbiscan.io](https://arbiscan.io/apis)
- **Optimism**: [Optimistic.Etherscan.io](https://optimistic.etherscan.io/apis)
- **Cronos**: [CronoScan.com](https://cronoscan.com/apis)
- **Moonbeam**: [Moonscan.io](https://moonscan.io/apis)
- **Celo**: [CeloScan.io](https://celoscan.io/apis)
2. **Configure in n8n**:
- Go to Settings → Credentials
- Add new credential of type "Blockchain Explorer API"
- Select your network and environment (mainnet/testnet)
- Enter your API key
- Optionally set a custom base URL for additional networks
## Usage Examples
### Etherscan Node (Ethereum)
#### Get Account Balance
```json
{
"resource": "account",
"operation": "getBalance",
"address": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae"
}
```
### Blockchain Explorer Node (Multi-chain)
#### Get BSC Account Balance
```json
{
"resource": "account",
"operation": "getBalance",
"address": "0x8894E0a0c962CB723c1976a4421c95949bE2D4E3"
}
```
#### Get Polygon Token Supply
```json
{
"resource": "stats",
"operation": "getEthSupply"
}
```
### Get Transaction History
```json
{
"resource": "account",
"operation": "getNormalTxs",
"address": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
"startBlock": 0,
"endBlock": "latest",
"page": 1,
"offset": 10,
"sort": "desc"
}
```
### Get Contract ABI
```json
{
"resource": "contract",
"operation": "getAbi",
"contractAddress": "0x6B175474E89094C44Da98b954EedeAC495271d0F"
}
```
### Get Gas Oracle
```json
{
"resource": "gas",
"operation": "getGasOracle"
}
```
## API Response Format
All responses include metadata for better tracking and debugging:
```json
{
"status": "1",
"message": "OK",
"result": "...",
"_metadata": {
"resource": "account",
"operation": "getBalance",
"timestamp": "2024-01-15T10:30:00.000Z",
"apiEndpoint": "https://api.etherscan.io/api"
}
}
```
## Rate Limits
Etherscan API has the following rate limits:
- **Free Plan**: 5 calls/second, 100,000 calls/day
- **Standard Plan**: 5 calls/second, 100,000 calls/day
- **Advanced Plan**: 5 calls/second, 500,000 calls/day
- **Professional Plan**: 5 calls/second, 1,000,000 calls/day
## Error Handling
The node includes comprehensive error handling:
- API rate limit detection
- Invalid address format validation
- Network connectivity issues
- Malformed request handling
## Development
### Prerequisites
- Node.js 18+
- npm or yarn
- n8n development environment
### Setup
```bash
# Clone the repository
git clone https://github.com/GitCryptoDevOps/n8n-nodes-etherscan.git
cd n8n-nodes-etherscan
# Install dependencies
npm install
# Build the node
npm run build
# Run tests
npm test
# Lint code
npm run lint
```
### Testing
#### Test Multi-Blockchain APIs
Run the comprehensive test suite to verify API connectivity across all supported networks:
```bash
# Test all networks
node test-multi-blockchain.js
# Test specific network
node test-multi-blockchain.js ethereum
node test-multi-blockchain.js bsc
node test-multi-blockchain.js polygon
# Test with your API key
node test-multi-blockchain.js ethereum your_api_key_here
```
#### Test Original Etherscan Node
```bash
# Test with environment variable
ETHERSCAN_API_KEY=your_api_key_here node test-token-specific.js
# Or test without API key (limited functionality)
node test-token-specific.js
```
The test script will verify:
- ✅ Token supply retrieval
- ✅ Gas oracle functionality
- ✅ Account balance queries
- ✅ API response format validation
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Make your changes and add tests
4. Ensure all tests pass: `npm test`
5. Commit your changes: `git commit -am 'Add new feature'`
6. Push to the branch: `git push origin feature/new-feature`
7. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/GitCryptoDevOps/n8n-nodes-etherscan/issues)
- **Documentation**: [Etherscan API Docs](https://docs.etherscan.io/)
- **n8n Community**: [n8n Community Forum](https://community.n8n.io/)
## Changelog
### v1.0.0
- Initial release with full Etherscan API support
- Account, Block, Contract, Gas, Stats, Token, and Transaction operations
- Multi-network support (Mainnet, Goerli, Sepolia)
- Comprehensive error handling and rate limit management
- TypeScript support with full type definitions
---
**Made with ❤️ for the n8n community**