etherscanio: Lightweight Python wrapper for the Etherscan v2 Multi-chain API

A modern, clean, and intuitive Python client for interacting with Etherscan's API across multiple blockchain networks.

Features

• Simple & Intuitive - Clean, Pythonic interface
• Multi-chain Support - Works with Ethereum, BSC, Polygon, and more
• Minimal Dependencies - Only requires httpx
• Modular Design - Organized API endpoints into logical modules

Installation

pip install etherscanio

Quick Start

from etherscan import Etherscan

# Initialize with your API key
client = Etherscan(chain_id=1, api_key="YOUR_API_KEY")

# Or use environment variable ETHERSCAN_API_KEY
client = Etherscan(chain_id=1)

# Get account balance
balance = client.accounts.get_balance("0x...")

# Get transaction details
tx = client.transactions.get_transaction("0x...")

# Get gas prices
gas = client.gastracker.get_gas_oracle()

Supported Chains

The library supports all chains available in the Etherscan v2 API. Use the appropriate chain ID for your target network. For a complete list of supported chains and their IDs, visit the official documentation.

You can also fetch the list programmatically:

chains = Etherscan.chainlist()

API Modules

The API is organized into logical modules for easy access to different Etherscan endpoints.

Accounts

Access account-related data including balances, transaction history, and token holdings.

# Get ETH balance for an address
balance = client.accounts.get_balance("0x...")

# Get ERC20 token balance
token_balance = client.accounts.get_token_balance(
    address="0x...",
    contract_address="0x..."
)

# Get transaction history for an address
txs = client.accounts.get_transactions("0x...")

Transactions

Query transaction details, receipts, and execution status.

# Get transaction receipt
receipt = client.transactions.get_transaction_receipt("0x...")

# Check transaction status
status = client.transactions.get_transaction_status("0x...")

Tokens

Retrieve information about ERC20 and ERC721 tokens including supply, holders, and transfers.

# Get total supply of an ERC20 token
supply = client.tokens.get_token_supply("0x...")

# Get token information
info = client.tokens.get_token_info("0x...")

Blocks

Access block data including rewards, timestamps, and block production information.

# Get block reward information
reward = client.blocks.get_block_reward(12345678)

# Get estimated time until a future block
countdown = client.blocks.get_block_countdown(12345678)

Gas Tracker

Monitor current gas prices and estimate transaction costs.

# Get current gas price recommendations
gas = client.gastracker.get_gas_oracle()

# Estimate gas for a transaction
estimate = client.gastracker.estimate_gas(
    to="0x...",
    value=1000000000000000000,
    gas_price=20000000000
)

Smart Contracts

Interact with smart contracts, retrieve source code, and verify contract deployments.

# Get contract ABI
abi = client.contracts.get_contract_abi("0x...")

# Get verified source code
source = client.contracts.get_source_code("0x...")

# Verify and publish contract source code
result = client.contracts.verify_solidity_source_code(
    address="0x...",
    contract_name="MyContract",
    code_format="solidity-single-file",
    source_code="pragma solidity...",
    compiler_version="v0.8.0+commit.c7dfd78e"
)

Statistics

Access network-wide statistics including supply metrics and price data.

# Get total ETH supply
supply = client.statistics.get_total_supply()

# Get current ETH price in USD
price = client.statistics.get_eth_price()

Proxy (Direct Ethereum JSON-RPC)

Make direct Ethereum JSON-RPC calls through Etherscan's infrastructure.

# Get the latest block number
block_num = client.eth.get_block_number()

# Call a contract method (read-only)
result = client.eth.call(
    to="0x...",
    data="0x..."
)

# Get transaction count for an address (nonce)
count = client.eth.get_transaction_count("0x...")

Configuration

API Key

Set your API key in one of three ways:

1. Pass directly:

   client = Etherscan(chain_id=1, api_key="YOUR_KEY")

2. Environment variable:

   export ETHERSCAN_API_KEY="YOUR_KEY"

   client = Etherscan(chain_id=1)

3. No key (limited requests):

   client = Etherscan(chain_id=1)  # Uses public rate limits

Timeout

Configure request timeout:

client = Etherscan(chain_id=1, api_key="YOUR_KEY")
client.configure_timeout(30)  # 30 seconds

Error Handling

from etherscan import Etherscan, EtherscanException

try:
    client = Etherscan(chain_id=999, api_key="YOUR_KEY")
except EtherscanException as e:
    print(f"Error: {e}")

Development

Setup

# Clone the repository
git clone https://github.com/traverne/etherscanio.git
cd etherscanio

# Install with hatch
pip install hatch

# Enter development environment
hatch shell

Running Tests

# Run tests
hatch run test

# Run with coverage
hatch run test-cov

Linting

# Check code
hatch run lint:check

# Format code
hatch run lint:fmt

Requirements

• Python >=3.9
• httpx

License

etherscanio is distributed under the terms of the MIT license.

Links

• Documentation: GitHub README
• Source Code: GitHub
• Issue Tracker: GitHub Issues
• PyPI: pypi.org/project/etherscanio
• Etherscan API Docs: docs.etherscan.io

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with Hatch and powered by httpx.

---

Made with ❤️ by Athen Traverne