n8n-nodes-etherscan

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://api.etherscan.io/api	Sepolia
Binance Smart Chain	BNB	56 / 97	BscScan.com	https://api.bscscan.com/api	BSC Testnet
Polygon	MATIC	137 / 80001	PolygonScan.com	https://api.polygonscan.com/api	Mumbai
Fantom	FTM	250 / 4002	FtmScan.com	https://api.ftmscan.com/api	Fantom Testnet
Avalanche	AVAX	43114 / 43113	SnowTrace.io	https://api.snowtrace.io/api	Fuji
Arbitrum	ETH	42161 / 421613	Arbiscan.io	https://api.arbiscan.io/api	Arbitrum Goerli
Optimism	ETH	10 / 420	Optimistic.Etherscan.io	https://api-optimistic.etherscan.io/api	Optimism Goerli
Cronos	CRO	25 / 338	CronoScan.com	https://api.cronoscan.com/api	Cronos Testnet
Moonbeam	GLMR	1284 / 1287	Moonscan.io	https://api-moonbeam.moonscan.io/api	Moonbase Alpha
Celo	CELO	42220 / 44787	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
BSC	✅	5 req/sec	10,000	Get API Key
Polygon	✅	5 req/sec	100,000	Get API Key
Fantom	✅	5 req/sec	100,000	Get API Key
Avalanche	✅	5 req/sec	100,000	Get API Key
Arbitrum	✅	5 req/sec	100,000	Get API Key
Optimism	✅	5 req/sec	100,000	Get API Key
Cronos	✅	5 req/sec	100,000	Get API Key
Moonbeam	✅	5 req/sec	100,000	Get API Key
Celo	✅	5 req/sec	100,000	Get API Key

🌍 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 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

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 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
   • BSC: BscScan.com
   • Polygon: PolygonScan.com
   • Fantom: FtmScan.com
   • Avalanche: SnowTrace.io
   • Arbitrum: Arbiscan.io
   • Optimism: Optimistic.Etherscan.io
   • Cronos: CronoScan.com
   • Moonbeam: Moonscan.io
   • Celo: CeloScan.io

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

{
  "resource": "account",
  "operation": "getBalance",
  "address": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae"
}

Blockchain Explorer Node (Multi-chain)

Get BSC Account Balance

{
  "resource": "account",
  "operation": "getBalance",
  "address": "0x8894E0a0c962CB723c1976a4421c95949bE2D4E3"
}

Get Polygon Token Supply

{
  "resource": "stats",
  "operation": "getEthSupply"
}

Get Transaction History

{
  "resource": "account",
  "operation": "getNormalTxs",
  "address": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
  "startBlock": 0,
  "endBlock": "latest",
  "page": 1,
  "offset": 10,
  "sort": "desc"
}

Get Contract ABI

{
  "resource": "contract",
  "operation": "getAbi",
  "contractAddress": "0x6B175474E89094C44Da98b954EedeAC495271d0F"
}

Get Gas Oracle

{
  "resource": "gas",
  "operation": "getGasOracle"
}

API Response Format

All responses include metadata for better tracking and debugging:

{
  "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

# 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:

# 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

# 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 file for details.

Support

• Issues: GitHub Issues
• Documentation: Etherscan API Docs
• n8n Community: n8n Community Forum

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