etherscan-api

Etherscan API V2

Overview

Query blockchain data using Etherscan's unified API V2. This skill covers:

• Native ETH balance queries
• ERC-20 token balance queries (single contract on every plan; full holdings on PRO)
• Transaction history queries (normal, internal, ERC-20/ERC-721/ERC-1155 transfers)
• First-funding lookup for an address (PRO fundedby with a 2-call free-tier fallback)
• Multi-chain support via the chainid parameter
• Auto-detection of Free vs Lite vs PRO so paid-only chains and PRO-only endpoints are used when available

Scope: Read-only account queries. For other Etherscan API features, consult the fallback documentation.

Prerequisites

API Key Validation

Before making any API call, verify the ETHERSCAN_API_KEY environment variable is set:

if [ -z "$ETHERSCAN_API_KEY" ]; then
  echo "Error: ETHERSCAN_API_KEY environment variable is not set."
  echo "Get a free API key at: https://etherscan.io/myapikey"
  exit 1
fi

If the environment variable is missing, inform the user and halt execution.

Plan Detection

Run the detection helper once per session and cache the result. It maps getapilimit → plan tier and probes a Base balance call to disambiguate Free from Lite:

./scripts/detect-plan.sh

Output (key=value lines):

plan=lite
credit_limit=100000
credits_used=4
credits_available=99996
limit_interval=daily
interval_expiry=14:38:10
pro_endpoints=false
paid_chains=true

plan is one of free, lite, standard, advanced, professional, pro_plus, enterprise, unknown. Two boolean fields gate behavior:

• paid_chains=true — paid-only chains (Base, OP, Avalanche, BNB) are queryable. True for Lite and all higher tiers.
• pro_endpoints=true — PRO-only actions (addresstokenbalance, balancehistory, tokenholderlist, fundedby, daily-stats endpoints, etc.) are callable. True for Standard and higher; false on Lite.

Manual detection (if the script is unavailable):

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=getapilimit&action=getapilimit&apikey=$ETHERSCAN_API_KEY"
# → {"status":"1","message":"OK","result":{"creditsUsed":1,"creditsAvailable":99999,"creditLimit":100000,"limitInterval":"daily","intervalExpiryTimespan":"07:20:05"}}

creditLimit	Plan	Paid-only chains	PRO endpoints
100,000	Free or Lite	Probe to confirm	No
200,000	Standard	Yes	Yes
500,000	Advanced	Yes	Yes
1,000,000	Professional	Yes	Yes
1,500,000	Pro Plus	Yes	Yes
> 1,500,000	Enterprise	Yes	Yes

Free and Lite both report creditLimit: 100000. Lite ($49/mo) raises rate-limit-per-second (5 vs 3) and unlocks every supported chain (Base, OP, Avalanche, BNB), but does not add PRO endpoints — those start at Standard. To disambiguate, attempt a paid-chain balance call (e.g., chainid=8453): status=1 → Lite, status=0 → Free. To probe PRO instead, the failure response is "Sorry, it looks like you are trying to access an API Pro endpoint.".

getapilimit itself consumes 1 credit (plus 1 more for the paid-chain probe), so do not re-run mid-session.

Chain Inference

Do not default to Ethereum Mainnet. Always infer the chain from the user's prompt before making any API call.

Inference Rules

1. Explicit chain mention — If the user mentions a chain name (e.g., "on Polygon", "Arbitrum balance", "Base chain"), use that chain.
2. Chain-specific tokens — Some tokens exist primarily on specific chains:
   • POL → Polygon (137)
   • ARB → Arbitrum One (42161)
   • OP → OP Mainnet (10)
   • AVAX → Avalanche C-Chain (43114)
   • BNB → BNB Smart Chain (56)
   • SONIC → Sonic (146)
   • SEI → Sei (1329)
   • MON → Monad (143)
3. Contract address patterns — If the user provides a contract address, consider asking which chain it's deployed on (many contracts exist on multiple chains).
4. Testnet keywords — Words like "testnet", "Sepolia", "Hoodi", "Amoy" indicate testnet chains.
5. Ambiguous cases — If the chain cannot be inferred, ask the user before proceeding. Do not assume Ethereum Mainnet.

Unsupported Chains

If the user references an EVM chain that Etherscan API V2 does not cover (e.g., a niche L2 or appchain not in ./references/chains.md), do not halt. Fall back to direct RPC calls against the chain's default public RPC:

1. Resolve the chain via the evm-chains skill to get the default public RPC, chain ID, native currency symbol, and explorer URL.
2. Issue equivalent JSON-RPC calls (e.g., eth_getBalance, eth_getLogs, eth_getTransactionByHash) against that RPC using curl or the cast CLI from the cli-cast skill.
3. Note in the response that the data came from the chain's public RPC, not Etherscan, so PRO-style aggregations (full token holdings, first-funding lookup) are unavailable and must be derived manually from logs/transactions if needed.

If the user references a non-EVM chain (e.g., Solana, Bitcoin, Cosmos), inform them — no RPC fallback applies:

The chain "[chain name]" is not supported by Etherscan API V2.

Etherscan supports EVM-compatible chains only. For the full list, see:
https://docs.etherscan.io/supported-chains

For the complete list of Etherscan-supported chains and their IDs, see ./references/chains.md.

API Base URL

All requests use the unified V2 endpoint:

https://api.etherscan.io/v2/api

The chainid parameter determines which blockchain to query.

ETH Balance Query

Query native ETH (or native token) balance for an address.

Endpoint Parameters

Parameter	Required	Default	Description
chainid	No	1	Chain ID (see chains.md)
module	Yes	-	Set to account
action	Yes	-	Set to balance
address	Yes	-	Wallet address (supports up to 20 comma-separated)
tag	No	latest	latest or hex block number. On free/Lite, only the last 128 blocks are queryable; older history needs the balancehistory PRO endpoint (Standard+)
apikey	Yes	-	API key from $ETHERSCAN_API_KEY

Single Address Query

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balance&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

Multi-Address Query (up to 20)

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=balancemulti&address=0xaddress1,0xaddress2,0xaddress3&tag=latest&apikey=$ETHERSCAN_API_KEY"

Response Format

Single address:

{
  "status": "1",
  "message": "OK",
  "result": "172774397764084972158218"
}

Multi-address:

{
  "status": "1",
  "message": "OK",
  "result": [
    {"account": "0xaddress1", "balance": "1000000000000000000"},
    {"account": "0xaddress2", "balance": "2500000000000000000"}
  ]
}

ERC-20 Token Balance Query

Query ERC-20 token balance for an address.

Endpoint Parameters

Parameter	Required	Default	Description
chainid	No	1	Chain ID (see chains.md)
module	Yes	-	Set to account
action	Yes	-	Set to tokenbalance
contractaddress	Yes	-	ERC-20 token contract address
address	Yes	-	Wallet address to query
tag	No	latest	Block tag
apikey	Yes	-	API key from $ETHERSCAN_API_KEY

Example Query

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokenbalance&contractaddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&address=0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe&tag=latest&apikey=$ETHERSCAN_API_KEY"

Response Format

{
  "status": "1",
  "message": "OK",
  "result": "135499000000"
}

Full Holdings

tokenbalance returns the balance for one ERC-20 contract at a time. To list every token an address holds:

Action	Returns
addresstokenbalance	All ERC-20 holdings (token, quantity, decimals, USD price)
addresstokennftbalance	All ERC-721 collection holdings and counts

Use only when pro_endpoints=true from plan detection. Both require Standard plan or higher and are throttled to 2 calls/second regardless of tier.

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=addresstokenbalance&address=0x...&page=1&offset=100&apikey=$ETHERSCAN_API_KEY"

When pro_endpoints=false, fall back to looping tokenbalance over a known token contract list.

Transaction History Queries

Query an address's transaction history. Five actions are available under module=account:

Action	Returns
txlist	Normal (external) transactions
txlistinternal	Internal transactions (contract-initiated)
tokentx	ERC-20 token transfer events
tokennfttx	ERC-721 (NFT) token transfer events
token1155tx	ERC-1155 token transfer events

Endpoint Parameters

Parameter	Required	Default	Description
chainid	No	1	Chain ID (see chains.md)
module	Yes	-	Set to account
action	Yes	-	One of the actions above
address	Yes	-	Wallet address
contractaddress	No	-	Token contract filter (tokentx/tokennfttx/token1155tx)
startblock	No	0	Starting block number
endblock	No	999999999	Ending block number
page	No	1	Page number for pagination
offset	No	100	Results per page (see free-tier limit note below)
sort	No	asc	asc or desc by block number
apikey	Yes	-	API key from $ETHERSCAN_API_KEY

Pagination cap by plan (effective July 1, 2026): offset maximum is 1000 for free-tier accounts and 10000 for paid tiers (Lite included) on txlist, txlistinternal, tokentx, tokennfttx, token1155tx, and other list endpoints. When plan=free, paginate in batches ≤ 1,000.

Example Query

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlist&address=0x8877bcb2223682048baDD5b09b7eE5a8FA2F3424&startblock=0&endblock=999999999&page=1&offset=100&sort=desc&apikey=$ETHERSCAN_API_KEY"

Response Format

result is an array of transaction objects. Each contains a Unix timeStamp (seconds, as a string) and chain-specific fields (hash, from, to, value, gasUsed, etc.).

{
  "status": "1",
  "message": "OK",
  "result": [
    {
      "blockNumber": "18000000",
      "timeStamp": "1693526400",
      "hash": "0x...",
      "from": "0x...",
      "to": "0x...",
      "value": "1000000000000000000",
      "gasUsed": "21000"
    }
  ]
}

Timestamp Conversion

timeStamp is a Unix epoch in seconds. Always produce timezone-aware UTC datetimes.

from datetime import datetime, timezone

dt = datetime.fromtimestamp(int(tx["timeStamp"]), tz=timezone.utc)

Do not use datetime.utcfromtimestamp() — it returns a naive datetime and is deprecated in Python 3.12+.

# Shell equivalent (GNU date)
date -u -d "@1693526400" --iso-8601=seconds
# macOS / BSD date
date -u -r 1693526400 +"%Y-%m-%dT%H:%M:%SZ"

NFT Transfer History

Fetch historical ERC-721 or ERC-1155 transfers for an address. Both actions share the parameter table in the previous section; pass contractaddress to filter by collection. Pagination caps (1,000 free / 10,000 paid) and the startblock/endblock/page/offset/sort semantics are identical to txlist.

ERC-721 Transfers (tokennfttx)

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokennfttx&address=0x6975be450864c02b4613023c2152ee0743572325&contractaddress=0x06012c8cf97bead5deae237070f9587f8e7a266d&startblock=0&endblock=999999999&page=1&offset=100&sort=asc&apikey=$ETHERSCAN_API_KEY"

Response entry (one per Transfer event involving the address):

{
  "blockNumber": "4708120",
  "timeStamp": "1512907118",
  "hash": "0x031e6968...",
  "nonce": "0",
  "blockHash": "0x4be19c27...",
  "from": "0xb1690c08e213a35ed9bab7b318de14420fb57d8c",
  "contractAddress": "0x06012c8cf97bead5deae237070f9587f8e7a266d",
  "to": "0x6975be450864c02b4613023c2152ee0743572325",
  "tokenID": "202106",
  "tokenName": "CryptoKitties",
  "tokenSymbol": "CK",
  "tokenDecimal": "0",
  "transactionIndex": "81",
  "gas": "158820",
  "gasPrice": "40000000000",
  "gasUsed": "60508",
  "cumulativeGasUsed": "4880352",
  "input": "deprecated",
  "methodId": "0x454a2ab3",
  "functionName": "bid(uint256 _tokenId)",
  "confirmations": "18759540"
}

NFT-specific fields: contractAddress (collection), tokenID (per-NFT identifier), tokenName, tokenSymbol, tokenDecimal (always "0" for ERC-721).

ERC-1155 Transfers (token1155tx)

Same parameter shape — swap action=token1155tx. ERC-1155 differs from ERC-721 in two response fields:

• tokenValue (string) — quantity transferred for this tokenID. Required because ERC-1155 is semi-fungible; a single transfer can move N copies of one ID. Not present in ERC-721 responses.
• tokenDecimal is omitted (ERC-1155 has no decimals concept).

{
  "blockNumber": "...",
  "timeStamp": "...",
  "hash": "...",
  "from": "...",
  "to": "...",
  "contractAddress": "0x76be3b62873462d2142405439777e971754e8e77",
  "tokenID": "10371",
  "tokenValue": "1",
  "tokenName": "...",
  "tokenSymbol": "...",
  "...": "(other tx-level fields identical to tokennfttx)"
}

TransferBatch events (multiple IDs in one tx) appear as multiple result entries sharing the same hash — one per (tokenID, tokenValue) pair. Group by hash to reconstruct the batch.

Filtering by Collection or Token ID

• By collection — pass contractaddress=<collection>. The API filters server-side; omit to fetch transfers across all collections.
• By token ID — no server-side filter exists. Fetch the collection's transfers and filter result[].tokenID == <id> client-side. For high-volume collections, narrow with startblock/endblock first.
• Mint vs burn vs transfer — derive from from/to:
  • from == 0x0000...0000 → mint
  • to == 0x0000...0000 → burn
  • otherwise → transfer

Cost & Limits

Standard list-endpoint pricing — 1 credit per call, same rate-limit tier as txlist. Not a PRO endpoint; available on Free and Lite for all supported chains (paid-chain restriction still applies to Base/OP/Avalanche/BNB).

First Funding Transaction

Identify the earliest transaction that sent native value to an address — useful for fund-origin tracing, provenance, or compliance checks. Cost is 1 API call (PRO) or 2 API calls (fallback).

Preferred: fundedby (PRO endpoint)

Returns the address, tx hash, block, timestamp, and value of the transaction that first funded an EOA. Single call, structured response.

Parameter	Required	Default	Description
chainid	No	1	Chain ID (see chains.md)
module	Yes	-	Set to account
action	Yes	-	Set to fundedby
address	Yes	-	EOA address (contracts unsupported)
apikey	Yes	-	API key from $ETHERSCAN_API_KEY

curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=fundedby&address=0x4838B106FCe9647Bdf1E7877BF73cE8B0BAD5f97&apikey=$ETHERSCAN_API_KEY"

Response:

{
  "status": "1",
  "message": "OK",
  "result": {
    "block": 53708500,
    "timeStamp": "1708349932",
    "fundingAddress": "0x6969174fd72466430a46e18234d0b530c9fd5f49",
    "fundingTxn": "0xbc0ca4a67eb1555920552246409626cd60df01314dd2bcdb99718b506d9c9946",
    "value": "1000000000000000"
  }
}

Requirements & limits:

• PRO endpoint — requires Standard plan or higher (pro_endpoints=true from plan detection).
• Throttled to 2 calls/second regardless of paid tier.
• EOA only. Contract addresses return an error; use the fallback below.

Fallback: scan ASC normal + internal transactions

When pro_endpoints=false (free/Lite) or the address is a contract, scan both transaction lists ascending and pick the earliest qualifying incoming entry. Two API calls per address.

# Earliest normal txs involving the address
curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlist&address=0x...&startblock=0&endblock=999999999&page=1&offset=10&sort=asc&apikey=$ETHERSCAN_API_KEY"

# Earliest internal txs involving the address
curl -s "https://api.etherscan.io/v2/api?chainid=1&module=account&action=txlistinternal&address=0x...&startblock=0&endblock=999999999&page=1&offset=10&sort=asc&apikey=$ETHERSCAN_API_KEY"

For each response, pick the first entry where all of the following hold:

• to.toLowerCase() == address.toLowerCase() — incoming, not outgoing.
• value (in wei) is greater than 0 — actual funding, not a zero-value call.
• isError == "0" (omit this filter for internal txs, which use isError differently or not at all).

The funding tx is whichever match has the lower blockNumber; break ties by transactionIndex (normal txs) or by list order (internal txs).

Why both lists: An address may be funded externally (normal tx) or internally (contract sent ETH — common for CEX withdrawals routed through proxy/router contracts, contract deployments with non-zero msg.value, or SELFDESTRUCT refunds). Checking only txlist will miss internally-funded addresses.

Why offset=10, not 1: A txlist query returns every tx involving the address, including outgoing ones. The very first entry is occasionally outgoing (e.g., the address was internally pre-funded), so fetch a small window and scan for the first incoming match.

Edge cases:

• No qualifying entry in the first 10 — extend with offset=100 and page=1, or paginate further. In practice, > 10 outgoing-before-incoming is exceedingly rare.
• Genesis allocation — pre-mined balances do not appear in either list. The address shows a balance with no funding tx; report this explicitly.
• Token-only funding — fundedby and this fallback only consider native value. If the address was bootstrapped with ERC-20 transfers alone (rare for EOAs since gas is needed), repeat the fallback against tokentx.

Multi-Chain Usage

Specify the chainid parameter to query different blockchains.

Common Chain IDs (Free Tier)

Chain	Chain ID
Ethereum	1
Polygon	137
Arbitrum One	42161
Linea	59144
Blast	81457
Unichain	130
Mantle	5000

Example: Polygon Query

curl -s "https://api.etherscan.io/v2/api?chainid=137&module=account&action=balance&address=0x...&tag=latest&apikey=$ETHERSCAN_API_KEY"

For the complete list of supported chains, see ./references/chains.md.

Wei to Human-Readable Conversion

API responses return balances in the smallest unit (wei for ETH, smallest decimals for tokens).

ETH Conversion

Divide by 10^18:

# Using bc for precision
echo "scale=18; 172774397764084972158218 / 1000000000000000000" | bc
# Result: 172774.397764084972158218

ERC-20 Conversion

Divide by 10^decimals (typically 18, but varies per token):

Token	Decimals
Most tokens	18
USDC, USDT	6
WBTC	8

# USDC example (6 decimals)
echo "scale=6; 135499000000 / 1000000" | bc
# Result: 135499.000000

Output Formatting

Default behavior: Present results in a Markdown table:

| Address | Balance (ETH) | Chain |
|---------|---------------|-------|
| 0xde0B...7BAe | 172,774.40 | Ethereum |
| 0xabc1...2def | 50.25 | Polygon |

User preference: If the user requests a specific format (JSON, CSV, plain text, etc.), use that format instead. Do not generate a Markdown table when the user specifies an alternative output format.

Plan-Gated Capabilities

Decisions in this section depend on the cached output of ./scripts/detect-plan.sh.

Paid-Only Chains

Four chain families (8 chains total, mainnet + testnet) require any paid Etherscan plan. Lite ($49/mo) is sufficient — it grants access to every supported chain at the same 100,000 daily-credit limit as Free. Data endpoints (balance, txlist, logs, etc.) fail only when plan=free (i.e., paid_chains=false):

Chain	Chain ID
Base Mainnet	8453
Base Sepolia	84532
OP Mainnet	10
OP Sepolia	11155420
Avalanche C-Chain	43114
Avalanche Fuji	43113
BNB Smart Chain	56
BNB Testnet	97

Exception: module=contract endpoints (getsourcecode, getabi, etc.) work on all chains for every plan including free. The paid-plan requirement applies only to data endpoints.

If paid_chains=false (i.e., plan=free) and the user requests a data query on the chains above, halt and inform them upgrading to Lite or higher is required.

PRO-Only Endpoints

When pro_endpoints=true, the following actions become available (non-exhaustive — see https://docs.etherscan.io/api-pro/api-pro for the full list):

Module	Action(s)	Use case
account	addresstokenbalance, addresstokennftbalance, balancehistory, fundedby	Full holdings, historical balances, first-funding lookup
token	tokenholderlist, tokeninfo, tokensupplyhistory, tokenbalancehistory	Token analytics
block	dailyavgblocksize, dailyblkcount, dailyblockrewards, etc.	Daily block stats
stats	dailytxnfee, dailynewaddress, dailynetutilization, etc.	Network-wide daily metrics
gastracker	dailyavggaslimit, dailygasused, dailyavggasprice	Daily gas metrics

When pro_endpoints=false (free or Lite), prefer the non-PRO equivalents listed in this skill or fall back to per-token loops.

All Plans

All other supported chains — Ethereum, Polygon, Arbitrum One, Linea, Blast, Mantle, Unichain, Gnosis, Celo, Fraxtal, Moonbeam, Moonriver, opBNB, Sonic, Sei, Monad, Berachain, Abstract, ApeChain, World, Katana, HyperEVM, MegaETH, Memecore, Plasma, Stable, Taiko, BitTorrent, XDC, and their testnets — are available on every plan including Free. On Lite and higher, the paid-only chains above also become available.

See ./references/chains.md for the full list with chain IDs.

Error Handling

Common Error Responses

Status	Message	Cause
0	NOTOK	Invalid API key or rate limited
0	Invalid address format	Malformed address
0	No transactions found	Address has no activity

Rate Limits by Plan

Plan	Calls/second	Daily calls
Free	3	100,000
Lite	5	100,000
Standard	10	200,000
Advanced	20	500,000
Professional	30	1,000,000
Pro Plus	30	1,500,000
Enterprise	custom	unmetered

PRO endpoints (addresstokenbalance, etc.) are throttled to 2 calls/second regardless of tier. See https://docs.etherscan.io/resources/rate-limits for the authoritative schedule.

If rate limited, wait briefly and retry.

Reference Files

• ./references/chains.md - Complete list of supported chains with chain IDs
• ./scripts/detect-plan.sh - Plan-tier detection helper (run once per session)

Fallback Documentation

For use cases not covered by this skill (transaction history, contract verification, gas estimates, etc.), fetch the AI-friendly documentation:

https://docs.etherscan.io/llms.txt

Use WebFetch to retrieve this documentation for extended API capabilities.