Tokens

Endpoints with 
 are under the API Pro subscription. To upgrade your API plan, browse through the Etherscan APIs page.
Get ERC20-Token TotalSupply by ContractAddress
Returns the current amount of an ERC-20 token in circulation.
https://api.etherscan.io/api
   ?module=stats
   &action=tokensupply
   &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
   &apikey=YourApiKeyToken
Try this endpoint in your browser 🔗
​
Request
Response
Query Parameters
Parameter
Description
contractaddress
the contract address of the ERC-20 token
Sample Response
{
   "status":"1",
   "message":"OK",
   "result":"21265524714464"
}
​📈
 Tip : The result is returned in the token's smallest decimal representation.
Eg. a token with a balance of 215.241526476136819398 and 18 decimal places will be returned as 215241526476136819398
Get ERC20-Token Account Balance for TokenContractAddress
Returns the current balance of an ERC-20 token of an address.
https://api.etherscan.io/api
   ?module=account
   &action=tokenbalance
   &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
   &address=0xe04f27eb70e025b78871a2ad7eabe85e61212761
   &tag=latest&apikey=YourApiKeyToken
Try this endpoint in your browser 🔗
​
Request
Response
Query Parameters
Parameter
Description
contractaddress
the contract address of the ERC-20 token
address
the string representing the address to check for token balance
Sample Response
{
   "status":"1",
   "message":"OK",
   "result":"135499"
}
​📈
 Tip : The result is returned in the token's smallest decimal representation.
Eg. a token with a balance of 215.241526476136819398 and 18 decimal places will be returned as 215241526476136819398
Get Historical ERC20-Token TotalSupply by ContractAddress & BlockNo 
​
Returns the amount of an ERC-20 token in circulation at a certain block height.
​📝
 Note : This endpoint is throttled to 2 calls/second regardless of API Pro tier.
https://api.etherscan.io/api
   ?module=stats
   &action=tokensupplyhistory
   &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
   &blockno=8000000
   &apikey=YourApiKeyToken 
Try this endpoint in your browser 🔗
​
Request
Response
Query Parameters
Parameter
Description
contractaddress
the contract address of the ERC-20 token
blockno
the integer block number to check total supply for eg. 12697906​
Sample Response
{
   "status":"1",
   "message":"OK",
   "result":"21265524714464"
}
​📈
 Tip : The result is returned in the token's smallest decimal representation.
Eg. a token with a balance of 215.241526476136819398 and 18 decimal places will be returned as 215241526476136819398
Get Historical ERC20-Token Account Balance for TokenContractAddress by BlockNo 
​
Returns the balance of an ERC-20 token of an address at a certain block height.
​📝
 Note : This endpoint is throttled to 2 calls/second regardless of API Pro tier.
https://api.etherscan.io/api
   ?module=account
   &action=tokenbalancehistory
   &contractaddress=0x57d90b64a1a57749b0f932f1a3395792e12e7055
   &address=0xe04f27eb70e025b78871a2ad7eabe85e61212761
   &blockno=8000000
   &apikey=YourApiKeyToken 
Try this endpoint in your browser 🔗
​
Request
Response
Query Parameters
Parameter
Description
contractaddress
the contract address of the ERC-20 token
address
the string representing the address to check for balance
blockno
the integer block number to check total supply for eg. 12697906​
Sample Response
{
   "status":"1",
   "message":"OK",
   "result":"135499"
}
​📈
 Tip : The result is returned in the token's smallest decimal representation.
Eg. a token with a balance of 215.241526476136819398 and 18 decimal places will be returned as 215241526476136819398
Get Token Holder List by Contract Address 
​
Return the current token holders and number of tokens held.
https://api.etherscan.io/api
   ?module=token
   &action=tokenholderlist
   &contractaddress=0x0e09fabb73bd3ade0a17ecc321fd13a19e81ce82
   &page=1
   &offset=10
   &apikey=YourApiKeyToken 
Try this endpoint in your browser 🔗
​
Request
Response
Query Parameters
Parameter
Description
contractaddress
the contract address of the ERC-20 token
page
the integer page number, if pagination is enabled
offset
the number of transactions displayed per page
Sample Response
{
   "status":"1",
   "message":"OK",
   "result":[
      {
         "TokenHolderAddress":"0x0000000000000000000000000000000000000000",
         "TokenHolderQuantity":"34956"
      },
      {
         "TokenHolderAddress":"0x000000000000084e91743124a982076c59f10084",
         "TokenHolderQuantity":"1"
      },
      {
         "TokenHolderAddress":"0x0000000000000d9054f605ca65a2647c2b521422",
         "TokenHolderQuantity":"10000000"
      },
      {
         "TokenHolderAddress":"0x0000000000002d534ff79e9c69e7fcc742f0be83",
         "TokenHolderQuantity":"5"
      },
      {
         "TokenHolderAddress":"0x0000000000003f5e74c1ba8a66b48e6f3d71ae82",
         "TokenHolderQuantity":"1"
      }
   ]
}
Get Token Info by ContractAddress 
​
Returns project information and social media links of an ERC20/ERC721/ERC1155 token.
📝 Note : This endpoint is throttled to 2 calls/second regardless of API Pro tier.
https://api.etherscan.io/api
   ?module=token
   &action=tokeninfo
   &contractaddress=0x0e3a2a1f2146d86a604adc220b4967a898d7fe07
   &apikey=YourApiKeyToken 
Try this endpoint in your browser 🔗
​
Request
Response
Query Parameters
Parameter
Description
contractaddress
the contract address of the ERC-20/ERC-721 token to retrieve token info
Sample Response
{
   "status":"1",
   "message":"OK",
   "result":[
      {
         "contractAddress":"0x0e3a2a1f2146d86a604adc220b4967a898d7fe07",
         "tokenName":"Gods Unchained Cards",
         "symbol":"CARD",
         "divisor":"0",
         "tokenType":"ERC721",
         "totalSupply":"6962498",
         "blueCheckmark":"true",
         "description":"A TCG on the Ethereum blockchain that uses NFT's to bring real ownership to in-game assets.",
         "website":"https://godsunchained.com/",
         "email":"",
         "blog":"https://medium.com/@fuelgames",
         "reddit":"https://www.reddit.com/r/GodsUnchained/",
         "slack":"",
         "facebook":"https://www.facebook.com/godsunchained/",
         "twitter":"https://twitter.com/godsunchained",
         "bitcointalk":"",
         "github":"",
         "telegram":"",
         "wechat":"",
         "linkedin":"",
         "discord":"https://discordapp.com/invite/DKGr2pW",
         "whitepaper":"",
         "tokenPriceUSD":"0.000000000000000000"
      }
   ]
}
Get Address ERC20 Token Holding 
​
Returns the ERC-20 tokens and amount held by an address.
 Note : This endpoint is throttled to 2 calls/second regardless of API Pro tier.
https://api.etherscan.io/api
   ?module=account
   &action=addresstokenbalance
   &address=0x983e3660c0bE01991785F80f266A84B911ab59b0
   &page=1
   &offset=100
   &apikey=YourApiKeyToken
Try this endpoint in your browser 🔗
 
Request
Response
Query Parameters
Parameter
Description
address
the string representing the address to check for balance
page
the integer page number, if pagination is enabled
offset
the number of transactions displayed per page
Sample Response 
{
   "status":"1",
   "message":"OK",
   "result":[
      {
         "TokenAddress":"0xffffffff2ba8f66d4e51811c5190992176930278",
         "TokenName":"Furucombo",
         "TokenSymbol":"COMBO",
         "TokenQuantity":"1861606940000000000",
         "TokenDivisor":"18"
      },
      {
         "TokenAddress":"0x53a1e9912323b8016424d6287286e3b6de263f76",
         "TokenName":"PUTIN Token",
         "TokenSymbol":"PTT",
         "TokenQuantity":"3500000000000000000000",
         "TokenDivisor":"18"
      },
      {
         "TokenAddress":"0xb753428af26e81097e7fd17f40c88aaa3e04902c",
         "TokenName":"Spice",
         "TokenSymbol":"SFI",
         "TokenQuantity":"7",
         "TokenDivisor":"18"
      },
      {
         "TokenAddress":"0x1b40183efb4dd766f11bda7a7c3ad8982e998421",
         "TokenName":"VesperToken",
         "TokenSymbol":"VSP",
         "TokenQuantity":"962",
         "TokenDivisor":"18"
      },
      {
         "TokenAddress":"0x37e83a94c6b1bdb816b59ac71dd02cf154d8111f",
         "TokenName":"PhotoChromic",
         "TokenSymbol":"PHCR",
         "TokenQuantity":"4608452961264910063288",
         "TokenDivisor":"18"
      }
   ]
}
Get Address ERC721 Token Holding 
​
Returns the ERC-721 tokens and amount held by an address. 
 Note : This endpoint is throttled to 2 calls/second regardless of API Pro tier.
https://api.etherscan.io/api
   ?module=account
   &action=addresstokennftbalance
   &address=0x6b52e83941eb10f9c613c395a834457559a80114
   &page=1
   &offset=100
   &apikey=YourApiKeyToken 
Try this endpoint in your browser 🔗
 
Request
Response
Query Parameters
Parameter
Description
address
the string representing the address to check for balance
page
the integer page number, if pagination is enabled
offset
the number of transactions displayed per page
Sample Response 
{
   "status":"1",
   "message":"OK",
   "result":[
      {
         "TokenAddress":"0x49cf6f5d44e70224e2e23fdcdd2c053f30ada28b",
         "TokenName":"CloneX",
         "TokenSymbol":"CloneX",
         "TokenQuantity":"52"
      },
      {
         "TokenAddress":"0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
         "TokenName":"BoredApeYachtClub",
         "TokenSymbol":"BAYC",
         "TokenQuantity":"1"
      },
      {
         "TokenAddress":"0x60e4d786628fea6478f785a6d7e704777c86a7c6",
         "TokenName":"MutantApeYachtClub",
         "TokenSymbol":"MAYC",
         "TokenQuantity":"1"
      },
      {
         "TokenAddress":"0xed5af388653567af2f388e6224dc7c4b3241c544",
         "TokenName":"Azuki",
         "TokenSymbol":"AZUKI",
         "TokenQuantity":"1"
      },
      {
         "TokenAddress":"0x7bd29408f11d2bfc23c34f18275bbf23bb716bc7",
         "TokenName":"Meebits",
         "TokenSymbol":"⚇",
         "TokenQuantity":"1"
      }
   ]
}
Get Address ERC721 Token Inventory By Contract Address 
​
Returns the ERC-721 token inventory of an address, filtered by contract address. 
​📝
 Note : This endpoint is throttled to 2 calls/second regardless of API Pro tier.
https://api.etherscan.io/api
   ?module=account
   &action=addresstokennftinventory
   &address=0x123432244443b54409430979df8333f9308a6040
   &contractaddress=0xed5af388653567af2f388e6224dc7c4b3241c544
   &page=1
   &offset=100
   &apikey=YourApiKeyToken
Try this endpoint in your browser 🔗
​
Request
Response
Query Parameters
Parameter
Description
address
the string representing the address to check for inventory
contractaddress
the string representing the ERC-721 token contractaddress to check for inventory
page
the integer page number, if pagination is enabled
offset
the number of records displayed per page

limited to 1000 records per query, use the page parameter for subsequent records
Sample Response
{
   "status":"1",
   "message":"OK",
   "result":[
      {
         "TokenAddress":"0xed5af388653567af2f388e6224dc7c4b3241c544",
         "TokenId":"5401"
      },
      {
         "TokenAddress":"0xed5af388653567af2f388e6224dc7c4b3241c544",
         "TokenId":"7411"
      },
      {
         "TokenAddress":"0xed5af388653567af2f388e6224dc7c4b3241c544",
         "TokenId":"453"
      },
      {
         "TokenAddress":"0xed5af388653567af2f388e6224dc7c4b3241c544",
         "TokenId":"8080"
      },
      {
         "TokenAddress":"0xed5af388653567af2f388e6224dc7c4b3241c544",
         "TokenId":"4255"
      }
   ]
}