Loading Ethereum Transactions with LangChain EtherscanLoader

The LangChain EtherscanLoader provides an interface to load transaction data and account information from the Ethereum blockchain through the Etherscan API. This guide shows you how to use it effectively.

What is EtherscanLoader?

EtherscanLoader is a document loader class that allows you to fetch various types of Ethereum blockchain data including:

• Normal transactions
• Internal transactions
• ERC20 token transfers
• ERC721 (NFT) transfers
• ERC1155 token transfers
• ETH balances

The loader uses the Etherscan API to interact with the Ethereum mainnet and returns the data as LangChain Document objects.

Reference

Here are the key methods provided by EtherscanLoader:

How to Use EtherscanLoader

First, you'll need an Etherscan API key. You can set it as an environment variable:

import os
from langchain_community.document_loaders import EtherscanLoader

os.environ["ETHERSCAN_API_KEY"] = "your-api-key"

Basic Usage

The simplest way to use the loader is to fetch normal transactions for an address:

# Create loader for an Ethereum address
loader = EtherscanLoader(
    account_address="0x123...", # The Ethereum address to query
)

# Load the transactions
documents = loader.load()

Customizing the Query

You can customize various parameters when creating the loader:

loader = EtherscanLoader(
    account_address="0x123...",
    page=1,              # Page number for pagination
    offset=100,          # Number of records per page
    start_block=0,       # Starting block number
    end_block=99999999,  # Ending block number  
    sort="desc"          # Sort direction ("asc" or "desc")
)

Loading Different Transaction Types

You can specify which type of transactions to load using the filter parameter:

# Load ERC20 token transfers
erc20_loader = EtherscanLoader(
    account_address="0x123...",
    filter="erc20_transaction"
)
erc20_docs = erc20_loader.load()

# Load NFT transfers
nft_loader = EtherscanLoader(
    account_address="0x123...", 
    filter="erc721_transaction"
)
nft_docs = nft_loader.load()

# Get ETH balance
balance_loader = EtherscanLoader(
    account_address="0x123...",
    filter="eth_balance"
)
balance_docs = balance_loader.load()

Lazy Loading

For large datasets, you can use lazy loading to iterate through the documents:

loader = EtherscanLoader(account_address="0x123...")

# Use lazy loading iterator
for document in loader.lazy_load():
    # Process each document
    print(document.page_content)

Async Loading

The loader also supports async operations:

import asyncio

async def load_transactions():
    loader = EtherscanLoader(account_address="0x123...")
    documents = await loader.aload()
    return documents

# Run the async function
documents = asyncio.run(load_transactions())

Remember that the Etherscan API has rate limits, especially for free API keys (5 calls per second). Plan your queries accordingly and implement appropriate rate limiting if needed.