# etherscan-python
[](https://github.com/pcko1/etherscan-python)
[](https://codecov.io/gh/pcko1/etherscan-python)
[](https://app.codacy.com/gh/pcko1/etherscan-python?utm_source=github.com&utm_medium=referral&utm_content=pcko1/etherscan-python&utm_campaign=Badge_Grade)
[](https://codeclimate.com/github/pcko1/etherscan-python)
[](https://codeclimate.com/github/pcko1/etherscan-python/maintainability)
[](https://www.codefactor.io/repository/github/pcko1/etherscan-python)
[](https://badge.fury.io/py/etherscan-python)
[](https://www.python.org/downloads/release/python-385/)
[](https://zenodo.org/badge/latestdoi/298646404)
A minimal, yet complete, Python API for [Etherscan.io](https://etherscan.io/).
All standard and pro endpoints are provided. Kovan, Rinkeby and Ropsten testnets are also supported.
Available on [PyPI](https://pypi.org/project/etherscan-python/). Powered by [Etherscan.io APIs](https://etherscan.io/apis#misc).
___
## Endpoints
The following endpoints are provided:
<details><summary>Accounts <a href="https://etherscan.io/apis#accounts">(source)</a></summary>
<p>
* `get_eth_balance`
* `get_eth_balance_multiple`
* `get_normal_txs_by_address`
* `get_normal_txs_by_address_paginated`
* `get_internal_txs_by_address`
* `get_internal_txs_by_address_paginated`
* `get_internal_txs_by_txhash`
* `get_internal_txs_by_block_range_paginated`
* `get_erc20_token_transfer_events_by_address`
* `get_erc20_token_transfer_events_by_contract_address_paginated`
* `get_erc20_token_transfer_events_by_address_and_contract_paginated`
* `get_erc721_token_transfer_events_by_address`
* `get_erc721_token_transfer_events_by_contract_address_paginated`
* `get_erc721_token_transfer_events_by_address_and_contract_paginated`
* `get_mined_blocks_by_address`
* `get_mined_blocks_by_address_paginated`
</details>
<details><summary>Contracts <a href="https://etherscan.io/apis#contracts">(source)</a></summary>
<p>
* `get_contract_abi`
* `get_contract_source_code`
</details>
</details>
<details><summary>Transactions <a href="https://etherscan.io/apis#transactions">(source)</a></summary>
<p>
* `get_contract_execution_status`
* `get_tx_receipt_status`
</details>
<details><summary>Blocks <a href="https://etherscan.io/apis#blocks">(source)</a></summary>
<p>
* `get_block_reward_by_block_number`
* `get_est_block_countdown_time_by_block_number`
* `get_block_number_by_timestamp`
</details>
<details><summary>GETH/Parity Proxy <a href="https://etherscan.io/apis#proxy">(source)</a></summary>
<p>
* `get_proxy_block_number`
* `get_proxy_block_by_number`
* `get_proxy_uncle_by_block_number_and_index`
* `get_proxy_block_transaction_count_by_number`
* `get_proxy_transaction_by_hash`
* `get_proxy_transaction_by_block_number_and_index`
* `get_proxy_transaction_count`
* `get_proxy_transaction_receipt`
* `get_proxy_call`
* `get_proxy_code_at`
* `get_proxy_storage_position_at`
* `get_proxy_gas_price`
* `get_proxy_est_gas`
</details>
<details><summary>Tokens <a href="https://etherscan.io/apis#tokens">(source)</a></summary>
<p>
* `get_total_supply_by_contract_address`
* `get_acc_balance_by_token_and_contract_address`
</details>
<details><summary>Gas Tracker <a href="https://etherscan.io/apis#gastracker">(source)</a></summary>
<p>
* `get_est_confirmation_time`
* `get_gas_oracle`
</details>
<details><summary>Stats <a href="https://etherscan.io/apis#stats">(source)</a></summary>
<p>
* `get_total_eth_supply`
* `get_eth_last_price`
* `get_eth_nodes_size`
</details>
<details><summary>Pro (PRO API key needed) <a href="https://etherscan.io/apis#APIpro">(source)</a></summary>
<p>
* `get_hist_eth_balance_for_address_by_block_no`
* `get_daily_average_block_size`
* `get_daily_block_count_and_rewards`
* `get_daily_block_rewards`
* `get_daily_average_block_time`
* `get_daily_uncle_block_count_and_rewards`
* `get_hist_erc20_token_total_supply_by_contract_address_and_block_no`
* `get_hist_erc20_token_account_balance_for_token_contract_address_by_block_no`
* `get_token_info_by_contract_address`
* `get_daily_average_gas_limit`
* `get_eth_daily_total_gas_used`
* `get_eth_daily_average_gas_price`
* `get_eth_daily_network_tx_fee`
* `get_daily_new_address_count`
* `get_daily_network_utilization`
* `get_daily_average_network_hash_rate`
* `get_daily_tx_count`
* `get_daily_average_network_difficulty`
* `get_eth_hist_daily_market_cap`
* `get_eth_hist_price`
</details>
*If you think that a newly-added method is missing, kindly open an [issue](https://github.com/pcko1/etherscan-python/issues) as a feature request and I will do my best to add it.*
## Installation
Before proceeding, you should register an account on [Etherscan.io](https://etherscan.io/) and [generate a personal API key](https://etherscan.io/myapikey) 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.git
```
Alternatively, install from [PyPI](https://pypi.org/project/etherscan-python/):
```bash
pip install etherscan-python
```
## Unit tests
In `bash`, test that everything looks OK on your end using your `YOUR_API_KEY` (without quotation marks) before proceeding:
``` bash
bash run_tests.sh YOUR_API_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](https://etherscan.io/) API key:
``` python
from etherscan import Etherscan
eth = Etherscan(YOUR_API_KEY) # key in quotation marks
```
Then you can call all available methods, e.g.:
``` python
eth.get_eth_balance(address="0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a")
> '40891631566070000000000'
```
You can also choose one of the other testnets:
``` python
eth = Etherscan(YOUR_API_KEY, net="ropsten") # net name is case-insensitive, default is main
```
## Examples
Examples (arguments and results) for all methods may be found as JSON files [here](https://github.com/pcko1/etherscan-python/tree/master/logs). For example, if you want to use the method `get_block_number_by_timestamp`, you can find the supported arguments and the format of its output in its respective [JSON file](logs/standard/get_block_number_by_timestamp.json):
``` json
{
"method": "get_block_number_by_timestamp",
"module": "blocks",
"kwargs": {
"timestamp": "1578638524",
"closest": "before"
},
"log_timestamp": "2020-10-28-12:34:44",
"res": "9251482"
}
```
where `kwargs` refer to the required named arguments and `res` refers to the expected result if you were to run:
``` python
eth.get_block_number_by_timestamp(timestamp="1578638524", closest="before")
> '9251482'
```
**Disclaimer**: Those examples blindly use the arguments originally showcased [here](https://api.etherscan.io/apis) 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](https://github.com/pcko1/etherscan-python/issues). 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 ```bibtex```:
```bibtex
@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](https://etherscan.io/apis).
Raw data
{
"_id": null,
"home_page": null,
"name": "rstms-etherscan-python",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "etherscan,api,fork",
"author": null,
"author_email": "Panagiotis-Christos Kotsias <kotsias.pan@gmail.com>, Matt Krueger <mkrueger@rstms.net>",
"download_url": "https://files.pythonhosted.org/packages/82/0d/43a012bc6c90cd043f6e85ce92642fd2a2a4d7bb695898871a9b63aff232/rstms-etherscan-python-2.1.11.tar.gz",
"platform": null,
"description": "# etherscan-python\n\n[](https://github.com/pcko1/etherscan-python) \n[](https://codecov.io/gh/pcko1/etherscan-python)\n[](https://app.codacy.com/gh/pcko1/etherscan-python?utm_source=github.com&utm_medium=referral&utm_content=pcko1/etherscan-python&utm_campaign=Badge_Grade)\n[](https://codeclimate.com/github/pcko1/etherscan-python)\n[](https://codeclimate.com/github/pcko1/etherscan-python/maintainability)\n[](https://www.codefactor.io/repository/github/pcko1/etherscan-python)\n\n[](https://badge.fury.io/py/etherscan-python)\n\n\n[](https://www.python.org/downloads/release/python-385/)\n[](https://zenodo.org/badge/latestdoi/298646404)\n\n\nA minimal, yet complete, Python API for [Etherscan.io](https://etherscan.io/). \n\nAll standard and pro endpoints are provided. Kovan, Rinkeby and Ropsten testnets are also supported.\n\nAvailable on [PyPI](https://pypi.org/project/etherscan-python/). Powered by [Etherscan.io APIs](https://etherscan.io/apis#misc).\n\n\n___\n\n\n## Endpoints\n\nThe following endpoints are provided:\n\n<details><summary>Accounts <a href=\"https://etherscan.io/apis#accounts\">(source)</a></summary>\n<p>\n\n* `get_eth_balance`\n* `get_eth_balance_multiple`\n* `get_normal_txs_by_address`\n* `get_normal_txs_by_address_paginated`\n* `get_internal_txs_by_address`\n* `get_internal_txs_by_address_paginated`\n* `get_internal_txs_by_txhash`\n* `get_internal_txs_by_block_range_paginated`\n* `get_erc20_token_transfer_events_by_address`\n* `get_erc20_token_transfer_events_by_contract_address_paginated`\n* `get_erc20_token_transfer_events_by_address_and_contract_paginated`\n* `get_erc721_token_transfer_events_by_address`\n* `get_erc721_token_transfer_events_by_contract_address_paginated`\n* `get_erc721_token_transfer_events_by_address_and_contract_paginated`\n* `get_mined_blocks_by_address`\n* `get_mined_blocks_by_address_paginated`\n\n</details>\n\n<details><summary>Contracts <a href=\"https://etherscan.io/apis#contracts\">(source)</a></summary>\n<p>\n \n* `get_contract_abi`\n* `get_contract_source_code`\n\n</details>\n\n</details>\n\n<details><summary>Transactions <a href=\"https://etherscan.io/apis#transactions\">(source)</a></summary>\n<p>\n \n* `get_contract_execution_status`\n* `get_tx_receipt_status`\n\n</details>\n\n<details><summary>Blocks <a href=\"https://etherscan.io/apis#blocks\">(source)</a></summary>\n<p>\n \n* `get_block_reward_by_block_number`\n* `get_est_block_countdown_time_by_block_number`\n* `get_block_number_by_timestamp`\n\n</details>\n\n<details><summary>GETH/Parity Proxy <a href=\"https://etherscan.io/apis#proxy\">(source)</a></summary>\n<p>\n\n* `get_proxy_block_number`\n* `get_proxy_block_by_number`\n* `get_proxy_uncle_by_block_number_and_index`\n* `get_proxy_block_transaction_count_by_number`\n* `get_proxy_transaction_by_hash`\n* `get_proxy_transaction_by_block_number_and_index`\n* `get_proxy_transaction_count`\n* `get_proxy_transaction_receipt`\n* `get_proxy_call`\n* `get_proxy_code_at`\n* `get_proxy_storage_position_at`\n* `get_proxy_gas_price`\n* `get_proxy_est_gas`\n\n</details>\n\n<details><summary>Tokens <a href=\"https://etherscan.io/apis#tokens\">(source)</a></summary>\n<p>\n \n* `get_total_supply_by_contract_address`\n* `get_acc_balance_by_token_and_contract_address`\n\n</details>\n\n<details><summary>Gas Tracker <a href=\"https://etherscan.io/apis#gastracker\">(source)</a></summary>\n<p>\n \n* `get_est_confirmation_time`\n* `get_gas_oracle`\n\n</details>\n\n<details><summary>Stats <a href=\"https://etherscan.io/apis#stats\">(source)</a></summary>\n<p>\n \n* `get_total_eth_supply`\n* `get_eth_last_price`\n* `get_eth_nodes_size`\n\n</details>\n\n<details><summary>Pro (PRO API key needed) <a href=\"https://etherscan.io/apis#APIpro\">(source)</a></summary>\n<p>\n\n* `get_hist_eth_balance_for_address_by_block_no`\n* `get_daily_average_block_size`\n* `get_daily_block_count_and_rewards`\n* `get_daily_block_rewards`\n* `get_daily_average_block_time`\n* `get_daily_uncle_block_count_and_rewards`\n* `get_hist_erc20_token_total_supply_by_contract_address_and_block_no`\n* `get_hist_erc20_token_account_balance_for_token_contract_address_by_block_no`\n* `get_token_info_by_contract_address`\n* `get_daily_average_gas_limit`\n* `get_eth_daily_total_gas_used`\n* `get_eth_daily_average_gas_price`\n* `get_eth_daily_network_tx_fee`\n* `get_daily_new_address_count`\n* `get_daily_network_utilization`\n* `get_daily_average_network_hash_rate`\n* `get_daily_tx_count`\n* `get_daily_average_network_difficulty`\n* `get_eth_hist_daily_market_cap`\n* `get_eth_hist_price`\n\n</details>\n\n*If you think that a newly-added method is missing, kindly open an [issue](https://github.com/pcko1/etherscan-python/issues) as a feature request and I will do my best to add it.*\n\n## Installation\n\nBefore proceeding, you should register an account on [Etherscan.io](https://etherscan.io/) and [generate a personal API key](https://etherscan.io/myapikey) to use. \n\nIf you wish to have access to the PRO endpoints, you should obtain elevated privileges via Etherscan's subscription service.\n\nInstall from source:\n\n``` bash\npip install git+https://github.com/pcko1/etherscan-python.git\n```\n\nAlternatively, install from [PyPI](https://pypi.org/project/etherscan-python/):\n\n```bash\npip install etherscan-python\n```\n\n## Unit tests\n\nIn `bash`, test that everything looks OK on your end using your `YOUR_API_KEY` (without quotation marks) before proceeding:\n\n``` bash\nbash run_tests.sh YOUR_API_KEY\n````\n\nThis will regenerate the logs under `logs/` with the most recent results and the timestamp of the execution.\n\nThe tests also include the PRO endpoints so if your key is not PRO, the correspondings tests are expected to fail.\n\n## Usage\n\nIn `python`, create a client with your personal [Etherscan.io](https://etherscan.io/) API key:\n\n``` python\nfrom etherscan import Etherscan\neth = Etherscan(YOUR_API_KEY) # key in quotation marks\n```\n\nThen you can call all available methods, e.g.:\n\n``` python\neth.get_eth_balance(address=\"0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a\")\n\n> '40891631566070000000000'\n```\nYou can also choose one of the other testnets:\n``` python\neth = Etherscan(YOUR_API_KEY, net=\"ropsten\") # net name is case-insensitive, default is main\n```\n\n## Examples\n\nExamples (arguments and results) for all methods may be found as JSON files [here](https://github.com/pcko1/etherscan-python/tree/master/logs). For example, if you want to use the method `get_block_number_by_timestamp`, you can find the supported arguments and the format of its output in its respective [JSON file](logs/standard/get_block_number_by_timestamp.json):\n\n``` json\n{\n \"method\": \"get_block_number_by_timestamp\",\n \"module\": \"blocks\",\n \"kwargs\": {\n \"timestamp\": \"1578638524\",\n \"closest\": \"before\"\n },\n \"log_timestamp\": \"2020-10-28-12:34:44\",\n \"res\": \"9251482\"\n}\n```\n\nwhere `kwargs` refer to the required named arguments and `res` refers to the expected result if you were to run:\n\n``` python\neth.get_block_number_by_timestamp(timestamp=\"1578638524\", closest=\"before\")\n\n> '9251482'\n```\n\n**Disclaimer**: Those examples blindly use the arguments originally showcased [here](https://api.etherscan.io/apis) 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.\n\n## Issues\n\nFor problems regarding installing or using the package please open an [issue](https://github.com/pcko1/etherscan-python/issues). Kindly avoid disclosing potentially sensitive information such as your API keys or your wallet addresses.\n\n## Cite\n\nKotsias, P. C., pcko1/etherscan-python. *https://github.com/pcko1/etherscan-python (2020)*. doi:10.5281/zenodo.4306855\n\nor in ```bibtex```:\n\n```bibtex\n@misc{Kotsias2020,\n author = {Kotsias, P.C.},\n title = {pcko1/etherscan-python},\n year = {2020},\n publisher = {Zenodo},\n url = {https://github.com/pcko1/etherscan-python},\n doi = {10.5281/zenodo.4306855}\n}\n```\n\nFeel free to leave a :star: if you found this package useful.\n\n___\n\n Powered by [Etherscan.io APIs](https://etherscan.io/apis).\n",
"bugtrack_url": null,
"license": null,
"summary": "etherscan-python",
"version": "2.1.11",
"split_keywords": [
"etherscan",
"api",
"fork"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8084a3f7328e3c49feafe3c8b8bdbb9a960aa6fe0130c51f1354f4f2b74680c3",
"md5": "c2b616f3dcc8c191efac91296974ee88",
"sha256": "bc9b4a062418c01a4b5604269ed4c5c31c73020d117ac389a4c8aa90e8489819"
},
"downloads": -1,
"filename": "rstms_etherscan_python-2.1.11-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2b616f3dcc8c191efac91296974ee88",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 26802,
"upload_time": "2023-04-19T01:36:19",
"upload_time_iso_8601": "2023-04-19T01:36:19.464736Z",
"url": "https://files.pythonhosted.org/packages/80/84/a3f7328e3c49feafe3c8b8bdbb9a960aa6fe0130c51f1354f4f2b74680c3/rstms_etherscan_python-2.1.11-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "820d43a012bc6c90cd043f6e85ce92642fd2a2a4d7bb695898871a9b63aff232",
"md5": "660e785cf3d18434412bfbe8ce7a3cf7",
"sha256": "49e53df42c8507ccf808c4052c000ee2ebe31f9b0eea5a7fbfd9919b263f64c6"
},
"downloads": -1,
"filename": "rstms-etherscan-python-2.1.11.tar.gz",
"has_sig": false,
"md5_digest": "660e785cf3d18434412bfbe8ce7a3cf7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 849983,
"upload_time": "2023-04-19T01:36:21",
"upload_time_iso_8601": "2023-04-19T01:36:21.440885Z",
"url": "https://files.pythonhosted.org/packages/82/0d/43a012bc6c90cd043f6e85ce92642fd2a2a4d7bb695898871a9b63aff232/rstms-etherscan-python-2.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-19 01:36:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "rstms-etherscan-python"
}
JSON