API Keys Setup

Etherscan issues one API key per account, from the API Keys section of your Etherscan account. The same key authenticates every chain the V2 API covers — there is no per-chain key. The free tier covers most of this client's surface; a handful of endpoints (bulk exports, extended historical stats, some NFT/token lookups) require a paid Etherscan plan and return an explicit "Pro endpoint" or "Exclusive endpoint" message on the free tier.

Environment Variables

# .env
ETHERSCAN_API_KEY="your_api_key"
ETHERSCAN_RATE_LIMIT="4"

ETHERSCAN_API_KEY is required for everything except usage.chain_list. ETHERSCAN_RATE_LIMIT is optional — see Rate Limiting below.

Using It

from dotenv import load_dotenv
from typed_etherscan import Etherscan

load_dotenv()

async with Etherscan.new() as client:
  balance = await client.account.balance(address='0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae')

You can also pass the key directly, instead of relying on the environment:

from typed_etherscan import Etherscan

async with Etherscan.new(api_key='your_api_key') as client:
  balance = await client.account.balance(address='0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae')

Rate Limiting

Etherscan's free tier enforces a strict per-second call cap. Set ETHERSCAN_RATE_LIMIT (or pass rate_limit= to Etherscan.new) to cap calls client-side and avoid RateLimited errors; leave it unset and Etherscan's own cap is the only limit, enforced reactively after you've already gone over it.

from typed_etherscan import Etherscan

async with Etherscan.new(rate_limit=4) as client:
  usage = await client.usage.api_limit()  # check your current usage

Public Access

One endpoint needs no key at all: the list of chains the V2 API supports.

from typed_etherscan import Etherscan

async with Etherscan.new(public=True) as client:
  chains = await client.usage.chain_list()

Every other endpoint raises AuthError on a client built with public=True.