ep

etherscan-python

A minimal, yet complete, python API for Etherscan.io.

Showing:

Popularity

Downloads/wk

0

GitHub Stars

113

Maintenance

Last Commit

6mos ago

Contributors

5

Package

Dependencies

1

License

MIT

Categories

Readme

etherscan-python

Build Status codecov Codacy Badge Maintainability CodeFactor

PyPI PyPI - Downloads GitHub Python 3.8 DOI

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)

  • 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
Contracts (source)

* `get_contract_abi` * `get_contract_source_code`

Transactions (source)

* `get_contract_execution_status` * `get_tx_receipt_status`

Blocks (source)

* `get_block_reward_by_block_number` * `get_est_block_countdown_time_by_block_number` * `get_block_number_by_timestamp`

GETH/Parity Proxy (source)

  • 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
Tokens (source)

* `get_total_supply_by_contract_address` * `get_acc_balance_by_token_and_contract_address`

Gas Tracker (source)

* `get_est_confirmation_time` * `get_gas_oracle`

Stats (source)

* `get_total_eth_supply` * `get_eth_last_price` * `get_eth_nodes_size`

Pro (PRO API key needed) (source)

  • 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

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:

pip install git+https://github.com/pcko1/etherscan-python.git

Alternatively, install from PyPI:

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 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 API key:

from etherscan import Etherscan
eth = Etherscan(YOUR_API_KEY) # key in quotation marks

Then you can call all available methods, e.g.:

eth.get_eth_balance(address="0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a")

> '40891631566070000000000'

You can also choose one of the other testnets:

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. 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:

{
  "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:

eth.get_block_number_by_timestamp(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 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 ⭐ if you found this package useful.


Powered by Etherscan.io APIs.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial