@cryptodevops/n8n-nodes-etherscan

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

• Ethereum (Mainnet, Sepolia)
• Binance Smart Chain (Mainnet, Testnet)
• Polygon (Mainnet, Mumbai)
• Fantom (Mainnet, Testnet)
• Avalanche (Mainnet, Fuji)
• Arbitrum (Mainnet, Goerli)
• Optimism (Mainnet, Goerli)
• Cronos (Mainnet, Testnet)
• Moonbeam (Mainnet, Moonbase Alpha)
• Celo (Mainnet, Alfajores)

📦 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

• Clone this repository
• Install dependencies: npm install
• Build the node: npm run build
• Link to your n8n installation

Configuration

API Credentials Setup

For Etherscan Node (Ethereum only)

• Get an API Key: Visit Etherscan.io and create a free account
• 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)

• 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

• 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

• Fork the repository
• Create a feature branch: git checkout -b feature/new-feature
• Make your changes and add tests
• Ensure all tests pass: npm test
• Commit your changes: git commit -am 'Add new feature'
• Push to the branch: git push origin feature/new-feature
• 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