Etherscan API: A step-by-step Guide

What is Etherscan API?

Etherscan API is a way to interact with Etherscan features programmatically via code.

What is Etherscan?

Etherescan is the Ethereum blockchain explorer that is used for obtaining data on everything that is being transacted on top of the Ethereum blockchain.

What is Etherscan API used for?

Etherscan API is primarily used for obtaining transactions, blocks, wallet addresses, smart contracts, and other on-chain data via code.

Why should I use Etherscan API?

• Etherscan API is easy to use.
• Etherscan API provides many useful endpoints.
• Etherscan API is well-documented.
• Has several programming language wrappers.
• Is actively maintained.
• Is fast and accurate.

Why shouldn’t I use Etherscan API?

• Etherscan API might be too confusing for beginners.
• Its use is determined by your skills in finding patterns in the data.

Is Etherscan API free?

Etherscan API is completely free but it also offers premium subscription plans that give an extended rate limit, escalated customer support, and access to some “special” endpoints.

There are three possible premium subscription plans and you can deduce the main difference between them in the picture below:

What are the alternatives to Etherscan API?

Etherscan API can be replaced with some alternatives and they are the following:

• Etherchain
• Blockscout
• Ethplorer
• Blockchain.com
• EnjinX
• Bloxy
• Ethtective
• ETHStats
• Amber Data and more.

How to get started with Etherscan API?

How to get Ether balance for a single address with Etherscan API?

To get Ether balance for a single address with Etherscan API, you will need to issue a request to the account module and balance action endpoint with a provided address and API key.

For this, we will use the Python requests library, and to spice things up we will use a known whale address that can be found online:

requests.get('https://api.etherscan.io/api?module=account&action=balance&address=0x4976a4a02f38326660d17bf34b431dc6e2eb2327&tag=latest&apikey=A1C15S3AXQHQ7PVVDX63VVK2IBAECS448Z').json()

{'status': '1', 'message': 'OK', 'result':'29724721687169089009293'}

How to get a list of normal transactions by address with Etherscan API?

To get a list of normal transactions with the Etherscan API, you will need to send a request to the account module and txlist action endpoint that will return up to 10k records per call.

This endpoint will be used together with the pandas library to create a data frame. As the endpoints are a bit messy, I will showcase them in a cleaner way, and the way you call them is the same as in our previous example.

https://api.etherscan.io/api
   ?module=account
   &action=txlist
   &address=0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a
   &startblock=0
   &endblock=99999999
   &page=1
   &offset=10
   &sort=asc
   &apikey=YourApiKeyToken

This will be stored inside of the data variable and we will convert the response to a pandas data frame and print out the last 5 points in a transposed way to see all of the return parameters.

data = pd.DataFrame(data['result'])
data.tail().T

How to get a list of ERC20 token transfer events by address with Etherscan API?

To get a list of ERC20 token transfer events by address with Etherscan API, you will need to send a request to the account module and tokentx action endpoint. This endpoint requires a contract’s address and address endpoint.

https://api.etherscan.io/api
   ?module=account
   &action=tokentx
   &contractaddress=0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2
   &address=0x4e83362442b8d1bec281594cea3050c8eb01311c
   &page=1
   &offset=100
   &startblock=0
   &endblock=27025780
   &sort=asc
   &apikey=YourApiKeyToken

We put the response into the data frame as we did in our previous example.

How to get contracts with Etherscan API?

Etherscan API can get contracts data when the contracts module and getabi action endpoint is hit by a request. This endpoint also requires the API key and address parameters.

https://api.etherscan.io/api
   ?module=contract
   &action=getabi
   &address=0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413
   &apikey=YourApiKeyToken

How to check transaction status with Etherscan API?

To check a transaction status with the Etherscan API, the user will need to raise a request to the transaction module and gettxreceiptstatus action. The transaction hash code will also need to be sent as a parameter.

https://api.etherscan.io/api
   ?module=transaction
   &action=gettxreceiptstatus
   &txhash=0x513c1ba0bebf66436b5fed86ab668452b7805593c05073eb2d51d3a52f480a76
   &apikey=YourApiKeyToken

{'status': '1', 'message': 'OK', 'result': {'status': '1'}}

How to obtain block data with Etherscan API?

To obtain block data with the Etherscan API, you will need to access the block module and getblockreward action endpoint with a provided block number as the request parameter.

https://api.etherscan.io/api
   ?module=block
   &action=getblockreward
   &blockno=2165403
   &apikey=YourApiKeyToken

How to get logs with Etherscan API?

To get logs with Etherscan API, you will need to make an API request to the logs module and getLogs action endpoint. The parameters needed are the from/to blocks, address, topic, and API key. Here is an example request:

https://api.etherscan.io/api
   ?module=logs
   &action=getLogs
   &fromBlock=379224
   &toBlock=latest
   &address=0x33990122638b9132ca29c723bdf037f1a891a70c
   &topic0=0xf63780e752c6a54a94fc52715dbc5518a3b4c3c2833d301a204226548a2a8545
   &apikey=YourApiKeyToken

How to use the Geth/Parity Proxy with Etherscan API?

to use the Geth/Parity Proxy with Etherscan API, you will need to access the proxy module endpoints. There are several endpoints under this module like eth_blockNumber, eth_getBlockByNumber, eth_call, and more.

For example, we will obtain the eth_getStorageAt endpoint that will return the value from a storage position for the specified address:

https://api.etherscan.io/api
   ?module=proxy
   &action=eth_getStorageAt
   &address=0x6e03d9cce9d60f3e9f2597e13cd4c54c55330cfd
   &position=0x0
   &tag=latest
   &apikey=YourApiKeyToken

{'jsonrpc': '2.0',
 'id': 1,
 'result': '0x0000000000000000000000003d0768da09ce77d25e2d998e6a7b6ed4b9116c2d'}

How to get tokens data with Etherscan API?

To get tokens data with the Etherscan API, you will have the possibility to access multiple endpoints that can return things like the ERC20-Token supply, account balance, historical data, and more.

To obtain the token supply we do the following:

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

{'status': '1', 'message': 'OK', 'result': '21265524714464'}

How to use the gas tracker with Etherscan API?

To use the gas tracker with Etherscan API, you will have to go through the list of available gas endpoints. The endpoints that Etherscan API offers are gas estimation, gas oracle, daily gas limit, total gas used, gas price, and more.

For example, let us obtain the estimation of gas confirmation time:

https://api.etherscan.io/api
   ?module=gastracker
   &action=gasestimate
   &gasprice=2000000000
   &apikey=YourApiKeyToken

{'status': '1', 'message': 'OK', 'result': '3615'}

How to obtain stats with Etherscan API?

Etherscan API can obtain various stats like the total supply of Ether, last price, total nodes, node size, average network hash rate, historical market cap, transaction count, new address count, transaction fee, and more.

For example, we will take a look at the total supply of Ether 2.0:

https://api.etherscan.io/api
   ?module=stats
   &action=ethsupply2
   &apikey=YourApiKeyToken

{'status': '1',
 'message': 'OK',
 'result': {'EthSupply': '118194367499000000000000000',
  'Eth2Staking': '309618220365297000000000',
  'BurntFees': '738514872810670998934509'}}

Full code