A Comprehensive Guide to Etherscan's Token API Endpoints

·

Etherscan provides a robust set of API endpoints specifically designed for interacting with token data on the Ethereum blockchain. These endpoints allow developers and analysts to retrieve crucial information about ERC-20, ERC-721, and other token standards directly. Understanding how to use these tools effectively is key to building applications that leverage on-chain token data.

This guide covers the primary token-related endpoints, explaining their purpose, parameters, and practical usage.

Understanding API Access Tiers

It's important to note that some advanced endpoints require an API Pro subscription. For detailed information on rate limits, features, and upgrading your plan, you should always refer to the official Etherscan API documentation portal.

Core ERC-20 Token Endpoints

Retrieve Total Token Supply

This endpoint is fundamental for fetching the current total supply of an ERC-20 token in circulation. You only need the token's smart contract address to make this request.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=stats
 &action=tokensupply
 &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
 &apikey=YourApiKeyToken

Query Parameter:

Check Account Token Balance

To find out how much of a specific ERC-20 token a particular Ethereum address holds, you use this endpoint. It requires both the token's contract address and the wallet address you wish to query.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=account
 &action=tokenbalance
 &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
 &address=0xe04f27eb70e025b78871a2ad7eabe85e61212761
 &tag=latest&apikey=YourApiKeyToken

Query Parameters:

Historical Token Data Endpoints

Get Historical Total Supply

Blockchain analysis often requires looking back in time. This endpoint returns the total supply of a token at a specific block height, allowing you to track supply changes over time.

📝 Note: This endpoint is throttled to 2 calls/second for all users.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=stats
 &action=tokensupplyhistory
 &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
 &blockno=8000000
 &apikey=YourApiKeyToken

Query Parameters:

Get Historical Account Balance

Similar to the historical supply check, this endpoint retrieves the token balance of a specific address at a past block. This is essential for auditing, snapshotting, and understanding historical portfolio states.

📝 Note: This endpoint is also throttled to 2 calls/second.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=account
 &action=tokenbalancehistory
 &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
 &address=0xe04f27eb70e025b78871a2ad7eabe85e61212761
 &blockno=8000000
 &apikey=YourApiKeyToken

Query Parameters:

Token Holder Information

List Token Holders

This powerful endpoint returns a list of all current holders for a given ERC-20 token and their respective balances. It supports pagination to handle tokens with a large number of holders.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=token
 &action=tokenholderlist
 &contractaddress=0xaaaebe6fe48e54f431b0c390cfaf0b017d09d42d
 &page=1
 &offset=10
 &apikey=YourApiKeyToken

Query Parameters:

Count Token Holders

If you only need the total number of unique addresses holding a token, this endpoint provides a simple and efficient count without returning the entire list.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=token
 &action=tokenholdercount
 &contractaddress=0xaaaebe6fe48e54f431b0c390cfaf0b017d09d42d
 &apikey=YourApiKeyToken

Query Parameter:

Token Metadata and Information

Retrieve Token Information

Beyond balances and supply, you can fetch rich metadata about a token. This endpoint returns project information, social media links, and other details for ERC-20, ERC-721, and ERC-1155 tokens.

📝 Note: This endpoint is throttled to 2 calls/second.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=token
 &action=tokeninfo
 &contractaddress=0x0e3a2a1f2146d86a604adc220b4967a898d7fe07
 &apikey=YourApiKeyToken

Query Parameter:

Address-Centric Token Views

Get Address ERC-20 Token Holdings

This endpoint flips the perspective, showing all ERC-20 tokens and the amounts held by a single address. It's like scanning a wallet's entire fungible token portfolio.

Note: This endpoint is throttled to 2 calls/second.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=account
 &action=addresstokenbalance
 &address=0x983e3660c0bE01991785F80f266A84B911ab59b0
 &page=1
 &offset=100
 &apikey=YourApiKeyToken

Query Parameters:

Get Address ERC-721 Token Holdings (NFTs)

For non-fungible tokens (NFTs), this endpoint returns all ERC-721 tokens (NFTs) held by a given address. This is essential for building NFT galleries or portfolio trackers.

Note: This endpoint is throttled to 2 calls/second.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=account
 &action=addresstokennftbalance
 &address=0x6b52e83941eb10f9c613c395a834457559a80114
 &page=1
 &offset=100
 &apikey=YourApiKeyToken

Query Parameters:

Get Filtered ERC-721 Token Inventory

This is a more precise endpoint for NFTs. It returns the ERC-721 tokens held by an address, but filtered to show only those from a specific NFT collection (contract address).

📝 Note: This endpoint is throttled to 2 calls/second and is limited to 1000 records per query.

Endpoint Structure:

https://api.etherscan.io/api
 ?module=account
 &action=addresstokennftinventory
 &address=0x123432244443b54409430979df8333f9308a6040
 &contractaddress=0xed5af388653567af2f388e6224dc7c4b3241c544
 &page=1
 &offset=100
 &apikey=YourApiKeyToken

Query Parameters:

👉 Explore more advanced blockchain data strategies

Frequently Asked Questions

What is the main use case for the token supply endpoint?
The primary use is to track the circulating supply of a token in real-time. This is crucial for calculating market capitalization, monitoring tokenomics models like burning or minting, and providing accurate data for financial dashboards and applications.

Why are some endpoints throttled to 2 calls per second?
Endpoints providing historical or complex data (like historical balances, token info, and NFT inventories) require more computational resources to query from the blockchain's history. Throttling ensures stability and fair access to the API for all users without overloading Etherscan's systems.

What's the difference between tokenholderlist and addresstokenbalance?
tokenholderlist returns all holders for one specific token contract. addresstokenbalance returns all tokens (and their balances) for one specific wallet address. The first is token-centric, the second is address-centric.

How can I handle pagination for endpoints that return large lists?
Use the page and offset parameters. Start with page=1 and your desired offset (e.g., 100). If the response contains data, increment the page number to get the next set of results until no more data is returned.

Can I get information for tokens other than ERC-20?
Yes. Endpoints like tokeninfo support ERC-721 and ERC-1155 standards. Furthermore, the addresstokennftbalance and addresstokennftinventory endpoints are specifically designed for querying NFT (ERC-721) data associated with an address.

Is the API response real-time?
The API provides data that is as current as Etherscan's indexed blockchain data, which is typically very recent. However, for absolute real-time confirmation of pending transactions, other methods like directly connecting to a node may be necessary.