Etherscan provides a robust API suite for interacting with Ethereum-based tokens, including ERC20 and ERC721 standards. Below is a detailed guide to key endpoints for querying token data, balances, and historical information.
Key ERC20 Token Endpoints
1. Fetching ERC20 Token Total Supply
Retrieve the current circulating supply of an ERC20 token using its contract address.
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=stats&action=tokensupply&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055&apikey=YourApiKeyToken`Parameters:
contractaddress: ERC20 token contract address.
2. Checking ERC20 Token Account Balance
Get the balance of a specific ERC20 token held by an address.
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokenbalance&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055&address=0xe04f27eb70e025b78871a2ad7eabe85e61212761&tag=latest&apikey=YourApiKeyToken`Parameters:
contractaddress: ERC20 token contract address.address: Wallet address to query.
3. Historical ERC20 Total Supply
Fetch the token supply at a specific block height (throttled to 2 calls/second).
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=stats&action=tokensupplyhistory&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055&blockno=8000000&apikey=YourApiKeyToken`Parameters:
contractaddress: ERC20 token contract address.blockno: Block number for historical data.
4. Historical ERC20 Account Balance
Query the balance of an address at a past block (throttled to 2 calls/second).
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokenbalancehistory&contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055&address=0xe04f27eb70e025b78871a2ad7eabe85e61212761&blockno=8000000&apikey=YourApiKeyToken`Parameters:
contractaddress: ERC20 token contract address.address: Wallet address.blockno: Target block number.
Token Holder and Metadata Endpoints
5. Listing Token Holders
Retrieve ERC20 token holders and their balances.
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokenholderlist&contractaddress=0xaaaebe6fe48e54f431b0c390cfaf0b017d09d42d&page=1&offset=10&apikey=YourApiKeyToken`Parameters:
contractaddress: ERC20 token contract address.page/offset: Pagination controls.
6. Token Holder Count
Get the total number of holders for an ERC20 token.
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokenholdercount&contractaddress=0xaaaebe6fe48e54f431b0c390cfaf0b017d09d42d&apikey=YourApiKeyToken`7. Token Metadata
Fetch project details and social links for a token (throttled to 2 calls/second).
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokeninfo&contractaddress=0x0e3a2a1f2146d86a604adc220b4967a898d7fe07&apikey=YourApiKeyToken`ERC721 (NFT) Specific Queries
8. Address ERC721 Holdings
List all ERC721 tokens held by an address.
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=account&action=addresstokennftbalance&address=0x6b52e83941eb10f9c613c395a834457559a80114&page=1&offset=100&apikey=YourApiKeyToken`9. Filtered ERC721 Inventory
Get ERC721 tokens held by an address, filtered by contract.
**Endpoint**:
`https://api.etherscan.io/v2/api?chainid=1&module=account&action=addresstokennftinventory&address=0x123432244443b54409430979df8333f9308a6040&contractaddress=0xed5af388653567af2f388e6224dc7c4b3241c544&page=1&offset=100&apikey=YourApiKeyToken`FAQ Section
Why is my API call throttled?
Etherscan enforces a rate limit of 2 calls/second for certain endpoints to ensure fair usage. 👉 Upgrade to API Pro for higher limits.
How do I find a token’s contract address?
Search the token symbol on Etherscan’s explorer or use the tokeninfo endpoint.
Can I fetch historical NFT data?
Yes, use the addresstokennftinventory endpoint with a block number parameter.
👉 Explore Etherscan’s full API documentation for advanced features like gas tracking and proxy calls.