# Token Endpoints
Token endpoints provide information about ERC20, ERC721, and ERC1155 tokens including metadata, supply, holders, and balances.
## Table of Contents
- [Get Token Info](#get-token-info)
- [Get Token Total Supply](#get-token-total-supply)
- [Get Token Balance](#get-token-balance)
- [Get Token Holders](#get-token-holders)
- [Get Address Token Portfolio](#get-address-token-portfolio)
- [Get Token Transfer Events](#get-token-transfer-events)
- [Get Token Info by Contract Address](#get-token-info-by-contract-address)
---
## Get Token Info
Get detailed information about a token by its contract address.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `token` |
| action | Yes | string | Set to `tokeninfo` |
| contractaddress | Yes | string | Token contract address |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get USDC token info
curl "https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokeninfo&contractaddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": {
"contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"tokenName": "USD Coin",
"symbol": "USDC",
"divisor": "6",
"tokenType": "ERC20",
"totalSupply": "25123456789012345",
"blueCheckmark": "true",
"description": "USDC is a fully collateralized US dollar stablecoin...",
"website": "https://www.centre.io/",
"email": "support@centre.io",
"blog": "",
"reddit": "",
"slack": "",
"facebook": "",
"twitter": "https://twitter.com/centre_io",
"bitcointalk": "",
"github": "",
"telegram": "",
"wechat": "",
"linkedin": "",
"discord": "",
"whitepaper": "",
"tokenPriceUSD": "1.00"
}
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| contractAddress | Token contract address |
| tokenName | Full token name |
| symbol | Token symbol/ticker |
| divisor | Decimal places (6 = divide by 10^6) |
| tokenType | ERC20, ERC721, or ERC1155 |
| totalSupply | Total supply in smallest unit |
| blueCheckmark | "true" if verified project |
| description | Project description |
| website | Official website |
| tokenPriceUSD | Current price in USD (if available) |
| (social links) | Various social media links |
### Notes
- Blue checkmark indicates verified/trusted tokens
- Decimal places (divisor): Most tokens use 18, stablecoins often use 6
- Price data available for major tokens only
- Social links may be empty for newer tokens
---
## Get Token Total Supply
Get the current total supply of a token.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `stats` |
| action | Yes | string | Set to `tokensupply` |
| contractaddress | Yes | string | Token contract address |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get USDC total supply
curl "https://api.etherscan.io/v2/api?chainid=1&module=stats&action=tokensupply&contractaddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "25123456789012345"
}
```
### Notes
- Result is in token's smallest unit
- For USDC (6 decimals): Divide by 10^6
- For most tokens (18 decimals): Divide by 10^18
- Total supply can change due to:
- Minting new tokens
- Burning tokens
- Rebasing mechanisms
### Convert to Human-Readable
```javascript
const supply = "25123456789012345";
const decimals = 6; // USDC has 6 decimals
const humanReadable = Number(supply) / Math.pow(10, decimals);
console.log(`Total Supply: ${humanReadable.toLocaleString()} USDC`);
// Total Supply: 25,123,456,789.012345 USDC
```
---
## Get Token Balance
Get the token balance of an address for a specific token.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `tokenbalance` |
| contractaddress | Yes | string | Token contract address |
| address | Yes | string | Address to check balance |
| tag | No | string | Block parameter (default: latest) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get USDC balance for an address
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokenbalance&contractaddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&tag=latest&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": "135000000"
}
```
### Notes
- Result in token's smallest unit (USDC: divide by 10^6)
- Use `tag` parameter for historical balances
- Returns "0" if address has no balance
- Works for ERC20 tokens only
---
## Get Token Holders
Get list of token holders (top holders by balance).
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `token` |
| action | Yes | string | Set to `tokenholderlist` |
| contractaddress | Yes | string | Token contract address |
| page | No | number | Page number (default: 1) |
| offset | No | number | Records per page (max 100, default: 10) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get top USDC holders
curl "https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokenholderlist&contractaddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&page=1&offset=10&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"TokenHolderAddress": "0x1234567890123456789012345678901234567890",
"TokenHolderQuantity": "5000000000000"
},
{
"TokenHolderAddress": "0x2345678901234567890123456789012345678901",
"TokenHolderQuantity": "4500000000000"
}
]
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| TokenHolderAddress | Address holding tokens |
| TokenHolderQuantity | Balance in smallest unit |
### Notes
- Sorted by balance (highest first)
- Maximum 100 results per request
- Useful for:
- Token distribution analysis
- Whale tracking
- Decentralization metrics
- May exclude exchange wallets in some cases
---
## Get Address Token Portfolio
Get all token balances for a specific address.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `account` |
| action | Yes | string | Set to `addresstokenbalance` |
| address | Yes | string | Address to query |
| page | No | number | Page number |
| offset | No | number | Records per page (max 100) |
| apikey | Yes | string | Your API key |
### Example Request
```bash
# Get all token balances for an address
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=addresstokenbalance&address=0x742d35Cc6634C0532925a3b844Bc454e4438f44e&page=1&offset=100&apikey=YourApiKey"
```
### Example Response
```json
{
"status": "1",
"message": "OK",
"result": [
{
"TokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"TokenName": "USD Coin",
"TokenSymbol": "USDC",
"TokenQuantity": "135000000",
"TokenDivisor": "6"
},
{
"TokenAddress": "0x6b175474e89094c44da98b954eedeac495271d0f",
"TokenName": "Dai Stablecoin",
"TokenSymbol": "DAI",
"TokenQuantity": "50000000000000000000",
"TokenDivisor": "18"
}
]
}
```
### Response Fields
| Field | Description |
|-------|-------------|
| TokenAddress | Token contract address |
| TokenName | Full token name |
| TokenSymbol | Token symbol |
| TokenQuantity | Balance in smallest unit |
| TokenDivisor | Decimal places |
### Notes
- Returns all ERC20 tokens held by address
- Excludes tokens with zero balance
- Useful for:
- Wallet portfolio display
- Asset tracking
- Tax reporting
- Does not include NFTs (use separate NFT endpoints)
---
## Get Token Transfer Events
Get token transfer events (covered in [Account Endpoints](./account-endpoints.md)):
- **ERC20 Transfers**: `module=account&action=tokentx`
- **ERC721 Transfers**: `module=account&action=tokennfttx`
- **ERC1155 Transfers**: `module=account&action=token1155tx`
See [Get ERC20 Token Transfers](./account-endpoints.md#get-erc20-token-transfers) for details.
---
## Get Token Info by Contract Address
Alternative method to get token metadata using the contract module.
### Endpoint
```
GET https://api.etherscan.io/v2/api
```
### Parameters
| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| chainid | Yes | number | Network chain ID |
| module | Yes | string | Set to `contract` |
| action | Yes | string | Set to `getsourcecode` |
| address | Yes | string | Token contract address |
| apikey | Yes | string | Your API key |
### Example Request
```bash
curl "https://api.etherscan.io/v2/api?chainid=1&module=contract&action=getsourcecode&address=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&apikey=YourApiKey"
```
### Notes
- Returns contract source code along with basic token info
- Includes ABI for programmatic interaction
- See [Contract Endpoints](./contracts-endpoints.md#get-contract-source-code) for full details
---
## Token Standards Overview
### ERC20 (Fungible Tokens)
**Characteristics:**
- All units are identical and interchangeable
- Has decimals (typically 18)
- Examples: USDC, DAI, USDT, WETH
**Common Uses:**
- Stablecoins
- Governance tokens
- Utility tokens
- Wrapped assets
### ERC721 (Non-Fungible Tokens)
**Characteristics:**
- Each token is unique (identified by tokenID)
- No decimals (always 0)
- Examples: BAYC, CryptoPunks, ENS names
**Common Uses:**
- Digital art/collectibles
- Gaming assets
- Domain names
- Real-world asset tokenization
### ERC1155 (Multi-Token Standard)
**Characteristics:**
- Can represent both fungible and non-fungible tokens
- Multiple token types in single contract
- Batch transfer support
- Examples: Gaming items, multi-edition art
**Common Uses:**
- Gaming ecosystems
- Multi-edition NFTs
- Hybrid assets
- Efficient batch minting
---
## Popular Tokens Reference
### Stablecoins
| Token | Address | Decimals | Description |
|-------|---------|----------|-------------|
| USDC | 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 | 6 | Circle stablecoin |
| USDT | 0xdac17f958d2ee523a2206206994597c13d831ec7 | 6 | Tether stablecoin |
| DAI | 0x6b175474e89094c44da98b954eedeac495271d0f | 18 | MakerDAO stablecoin |
| BUSD | 0x4fabb145d64652a948d72533023f6e7a623c7c53 | 18 | Binance USD |
### DeFi Tokens
| Token | Address | Decimals | Description |
|-------|---------|----------|-------------|
| UNI | 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 | 18 | Uniswap governance |
| AAVE | 0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9 | 18 | Aave governance |
| COMP | 0xc00e94cb662c3520282e6f5717214004a7f26888 | 18 | Compound governance |
| MKR | 0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2 | 18 | MakerDAO governance |
### Wrapped Assets
| Token | Address | Decimals | Description |
|-------|---------|----------|-------------|
| WETH | 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 | 18 | Wrapped Ether |
| WBTC | 0x2260fac5e5542a773aa44fbcfedf7c193bc2c599 | 8 | Wrapped Bitcoin |
| stETH | 0xae7ab96520de3a18e5e111b5eaab095312d7fe84 | 18 | Lido Staked ETH |
---
## Working with Token Data
### Calculate Human-Readable Balance
```javascript
function formatTokenBalance(rawBalance, decimals) {
return Number(rawBalance) / Math.pow(10, decimals);
}
// Example: USDC balance
const balance = "135000000"; // Raw balance
const decimals = 6; // USDC decimals
const formatted = formatTokenBalance(balance, decimals);
console.log(`Balance: ${formatted.toLocaleString()} USDC`);
// Balance: 135 USDC
```
### Get Token Price in USD
```javascript
async function getTokenValueUSD(address, balance, decimals) {
// Get token info (includes price if available)
const response = await fetch(
`https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokeninfo&contractaddress=${address}&apikey=YourApiKey`
);
const data = await response.json();
const tokenPrice = parseFloat(data.result.tokenPriceUSD);
const humanBalance = Number(balance) / Math.pow(10, decimals);
const valueUSD = humanBalance * tokenPrice;
return valueUSD;
}
```
### Check Token Approval
```javascript
// Use contract ABI to check allowance
import { ethers } from 'ethers';
async function checkApproval(tokenAddress, ownerAddress, spenderAddress) {
const provider = new ethers.JsonRpcProvider('YOUR_RPC_URL');
const tokenContract = new ethers.Contract(
tokenAddress,
['function allowance(address owner, address spender) view returns (uint256)'],
provider
);
const allowance = await tokenContract.allowance(ownerAddress, spenderAddress);
return allowance;
}
```
---
## Token Security Considerations
### Verify Tokens
1. **Check Blue Checkmark**: Indicates verified project
2. **Verify Contract Address**: Always check official sources
3. **Review Token Info**: Check website, social links
4. **Check Holder Distribution**: Avoid tokens with single whale
5. **Review Source Code**: Verify contract is open source
### Red Flags
- No verified source code
- Ownership is centralized (single address holds >50%)
- No social presence or website
- Suspiciously high yield promises
- Tokens with similar names to popular tokens
### Due Diligence Checklist
```bash
# 1. Get token info
curl "https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokeninfo&contractaddress=0x...&apikey=KEY"
# 2. Check source code verification
curl "https://api.etherscan.io/v2/api?chainid=1&module=contract&action=getsourcecode&address=0x...&apikey=KEY"
# 3. Review top holders
curl "https://api.etherscan.io/v2/api?chainid=1&module=token&action=tokenholderlist&contractaddress=0x...&page=1&offset=10&apikey=KEY"
# 4. Check recent transfers
curl "https://api.etherscan.io/v2/api?chainid=1&module=account&action=tokentx&contractaddress=0x...&page=1&offset=100&sort=desc&apikey=KEY"
```
---
## Error Codes
| Status | Message | Description |
|--------|---------|-------------|
| 0 | Invalid contract address | Address is not a token contract |
| 0 | Contract not found | Address doesn't exist |
| 0 | No token balance | Address has zero balance |
| 0 | Invalid token type | Not an ERC20/721/1155 token |
## Rate Limits
- Free tier: **5 calls/second**
- Token holder list: Max **100** per request
- Token portfolio: Max **100** tokens per request
## Use Cases
### Portfolio Tracking
- Display all tokens held by a wallet
- Calculate total portfolio value
- Track token price changes
### Token Analytics
- Monitor token holder distribution
- Track supply changes
- Analyze transfer patterns
### DeFi Integration
- Check token allowances
- Verify token balances before swaps
- Track liquidity pool tokens
### Security Monitoring
- Track whale movements
- Monitor token distribution
- Alert on large transfers
## See Also
- [Account Endpoints](./account-endpoints.md) - Token transfers
- [Contract Endpoints](./contracts-endpoints.md) - Contract ABIs
- [Event Logs](./logs-endpoints.md) - Transfer events
- [ERC20 Standard](https://eips.ethereum.org/EIPS/eip-20)
- [ERC721 Standard](https://eips.ethereum.org/EIPS/eip-721)
- [ERC1155 Standard](https://eips.ethereum.org/EIPS/eip-1155)
