A minimal, yet complete, python API for Etherscan.io.
etherscan-python
A minimal, yet complete, Python API for Etherscan.io.
All standard and pro endpoints are provided. Kovan, Rinkeby and Ropsten testnets are also supported.
Available on PyPI. Powered by Etherscan.io APIs.
Endpoints
The following endpoints are provided:
Accounts (source)
getethbalancegetethbalance_multiplegetnormaltxsbyaddressgetnormaltxsbyaddress_paginatedgetinternaltxsbyaddressgetinternaltxsbyaddress_paginatedgetinternaltxsbytxhashgetinternaltxsbyblockrangepaginatedgeterc20tokentransfereventsbyaddressgeterc20tokentransfereventsbycontractaddresspaginatedgeterc20tokentransfereventsbyaddressandcontract_paginatedgeterc721tokentransfereventsbyaddressgeterc721tokentransfereventsbycontractaddresspaginatedgeterc721tokentransfereventsbyaddressandcontract_paginatedgetminedblocksbyaddressgetminedblocksbyaddress_paginated
Blocks (source)
getblockrewardbyblock_numbergetestblockcountdowntimebyblock_numbergetblocknumberbytimestamp
GETH/Parity Proxy (source)
getproxyblock_numbergetproxyblockbynumbergetproxyunclebyblocknumberand_indexgetproxyblocktransactioncountbynumbergetproxytransactionbyhashgetproxytransactionbyblocknumberand_indexgetproxytransaction_countgetproxytransaction_receiptgetproxycallgetproxycode_atgetproxystoragepositionatgetproxygas_pricegetproxyest_gas
Pro (PRO API key needed) (source)
gethistethbalanceforaddressbyblocknogetdailyaverageblocksizegetdailyblockcountand_rewardsgetdailyblock_rewardsgetdailyaverageblocktimegetdailyuncleblockcountandrewardsgethisterc20tokentotalsupplybycontractaddressandblock_nogethisterc20tokenaccountbalancefortokencontractaddressbyblocknogettokeninfobycontract_addressgetdailyaveragegaslimitgetethdailytotalgas_usedgetethdailyaveragegas_pricegetethdailynetworktx_feegetdailynewaddresscountgetdailynetwork_utilizationgetdailyaveragenetworkhash_rategetdailytx_countgetdailyaveragenetworkdifficultygetethhistdailymarket_capgetethhist_price
If you think that a newly-added method is missing, kindly open an issue as a feature request and I will do my best to add it.
Installation
Before proceeding, you should register an account on Etherscan.io and generate a personal API key to use.
If you wish to have access to the PRO endpoints, you should obtain elevated privileges via Etherscan's subscription service.
Install from source:
bash
pip install git+https://github.com/pcko1/etherscan-python.gitAlternatively, install from PyPI:
pip install etherscan-pythonUnit tests
In bash, test that everything looks OK on your end using your YOURAPIKEY (without quotation marks) before proceeding:
bash
bash runtests.sh YOURAPI_KEY
This will regenerate the logs under
logs/ with the most recent results and the timestamp of the execution.
The tests also include the PRO endpoints so if your key is not PRO, the correspondings tests are expected to fail.
Usage
In
python, create a client with your personal Etherscan.io API key:
<pre><code class="lang-">python from etherscan import Etherscan eth = Etherscan(YOURAPIKEY) # key in quotation marks</code></pre>
Then you can call all available methods, e.g.:
<pre><code class="lang-">python eth.getethbalance(address="0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a")
> '40891631566070000000000'</code></pre> You can also choose one of the other testnets: <pre><code class="lang-">python eth = Etherscan(YOURAPIKEY, net="ropsten") # net name is case-insensitive, default is main</code></pre>
Examples
Examples (arguments and results) for all methods may be found as JSON files here. For example, if you want to use the method
getblocknumberbytimestamp, you can find the supported arguments and the format of its output in its respective JSON file:
<pre><code class="lang-">json { "method": "getblocknumberbytimestamp", "module": "blocks", "kwargs": { "timestamp": "1578638524", "closest": "before" }, "log_timestamp": "2020-10-28-12:34:44", "res": "9251482" }</code></pre>
where
kwargs refer to the required named arguments and res` refers to the expected result if you were to run:
python
eth.getblocknumberbytimestamp(timestamp="1578638524", closest="before")
> '9251482'
Disclaimer: Those examples blindly use the arguments originally showcased here and the selected wallets/contracts do not reflect any personal preference. You should refer to the same source for additional information regarding specific argument values.
Issues
For problems regarding installing or using the package please open an issue. Kindly avoid disclosing potentially sensitive information such as your API keys or your wallet addresses.
Cite
Kotsias, P. C., pcko1/etherscan-python. https://github.com/pcko1/etherscan-python (2020). doi:10.5281/zenodo.4306855
or in
@misc{Kotsias2020,
author = {Kotsias, P.C.},
title = {pcko1/etherscan-python},
year = {2020},
publisher = {Zenodo},
url = {https://github.com/pcko1/etherscan-python},
doi = {10.5281/zenodo.4306855}
}Feel free to leave a :star: if you found this package useful.
Powered by Etherscan.io APIs.
