@cryptodevops/n8n-nodes-blockchain-explorer

v1.0.3

Published

4 months ago

n8n node for accessing multiple blockchain networks (Ethereum, BSC, Polygon, Fantom, Avalanche, Arbitrum, Optimism, etc.) with comprehensive analytics and data retrieval capabilities

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

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