A python API for BSCScan (Binance Smart Chain Explorer), available on PyPI.

Related tags

Third-party APIs Wrappers python blockchain bsc blockchain-explorer binance binance-smart-chain
Overview

bscscan-python

Build Status codecov Codacy Badge Maintainability CodeFactor

PyPI PyPI - Downloads GitHub Python 3.8 DOI

A complete Python API for BscScan.com, available on PyPI. Powered by BscScan.com APIs.

This is a gently modified fork of the etherscan-python package.

Endpoints

The following endpoints are provided:

Accounts (source)

  • get_bnb_balance
  • get_bnb_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_bep20_token_transfer_events_by_address
  • get_bep20_token_transfer_events_by_contract_address_paginated
  • get_bep20_token_transfer_events_by_address_and_contract_paginated
  • get_validated_blocks_by_address
  • get_validated_blocks_by_address_paginated
Contracts (source)

  • get_contract_abi
  • get_contract_source_code
Transactions (source)

  • 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_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_circulating_supply_by_contract_address
  • get_acc_balance_by_token_contract_address
Stats (source)

  • get_total_bnb_supply
  • get_validators_list

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 BscScan.com and generate a personal API key to use.

Install from source:

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

Alternatively, install from PyPI:

pip install bscscan-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.

Usage

In python, create a client with your personal BscScan.com API key:

from bscscan import BscScan
bsc = BscScan(YOUR_API_KEY) # key in quotation marks

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

bsc.get_bnb_balance(address="0x0000000000000000000000000000000000001004")

> '167195709084498025431541166'

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_circulating_supply_by_contract_address, you can find the supported arguments and the format of its output in its respective JSON file:

{
  "method": "get_circulating_supply_by_contract_address",
  "module": "tokens",
  "kwargs": {
    "contract_address": "0xe9e7cea3dedca5984780bafc599bd69add087d56"
  },
  "log_timestamp": "2021-02-19-12:34:14",
  "res": "422504134592569820000000000"
}

where kwargs refer to the required named arguments and res refers to the expected result if you were to run:

bsc.get_circulating_supply_by_contract_address(contract_address="0xe9e7cea3dedca5984780bafc599bd69add087d56")

> '422504134592569820000000000'

Disclaimer: Those examples blindly use argument values (addresses, contracts, etc.) that were randomly chosen and do not reflect any personal preference.

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/bscscan-python: v1.0.0. https://github.com/pcko1/bscscan-python (2021). doi:10.5281/zenodo.4580473

or in bibtex:

@misc{Kotsias2020,
  author = {Kotsias, P.C.},
  title = {pcko1/bscscan-python},
  year = {2021},
  publisher = {Zenodo},
  url = {https://github.com/pcko1/bscscan-python},
  doi = {10.5281/zenodo.4580473}
}

Feel free to leave a ⭐ if you found this package useful.

Powered by Bscscan.com APIs.

Comments
  • AttributeError: 'AsyncClient' object has no attribute 'get_bnb_balance'

    AttributeError: 'AsyncClient' object has no attribute 'get_bnb_balance'

    This was working a few days ago and now it is throwing this error. I haven't changed anything on my end.

    The code is very simple. I set bscscankey and my_address variables and then it's two lines:

    bsc = BscScan(bscscankey) print(bsc.get_bnb_balance(address=my_address))

    wontfix 
    opened by chiwalfrm 10
  • how to figure out the number of decimals?

    how to figure out the number of decimals?

    Using the method get_acc_balance_by_token_contract_address(contract_address=value, address=my_address) to get the token balance for an address, the output does not take into account the number of decimals. For example: fetching MARSCAT (contract address 0xd31bad66aefa525b808ee569a514f6345b0bea2d) token balance returns a number is exact (no decimals):

    Result: {"status":"1","message":"OK","result":"20"} --> actual value = 20

    But for many other tokens, it needs to be divided by 1e+18: For example, for "ANYTOKEN" (contract address 0xF68C9Df95a18B2A5a5fa1124d79EEEffBaD0B6Fa):

    Result: {"status":"1","message":"OK","result":"1000000000000000000"} --> actual value = 1

    Question is how can we know the divisor / i.e. how many decimals is in the result?

    opened by chiwalfrm 8
  • get_bep20_token_transfer_events_by_address don't get last blocks [BUG]

    get_bep20_token_transfer_events_by_address don't get last blocks [BUG]

    When i use this piece of code

    
if __name__ == "__main__":
    bsc = BscScan("KEY") 
    transactions = bsc.get_bep20_token_transfer_events_by_address(address=WALLET_TO_WATCH",
                                                                  startblock=9512000,
                                                                  endblock=30000935,
                                                                  sort='desc')[:100]
    for transaction in transactions:
        print(int(transaction['blockNumber']) )

    I don't receive the last block of the address. The last block number i got is 10511293, but the last block number on the wallet i'm watching is 10512880

    Maybe it's blockchain slow to send data with the API ? and i got a delay to get last block ? I don't understand why there is such a difference between the blocks. By the way, this problem is happening right now, but I don't always have it. For example earlier today I have the last block correctly.

    System info (please complete the following information):

    • OS and version: ubuntu 18
    • Python version: 3.8
    • bscscan-python: 1.0.0
    bug 
    opened by mapapuche 4
  • [BUG] Circular import error

    [BUG] Circular import error

    Describe the bug A clear and concise description of what the bug is.

    Upon installing either via PyPI or git (master or stable branch) using pipenv the "from bscscan import BscScan" import fails with "ImportError: cannot import name 'BscScan' from partially initialized module 'bscscan' (most likely due to a circular import)". I am using python 3.8.10.

    To Reproduce In order to assist you with your problem, we need a minimal code snippet that replicates the bug. Avoid disclosing your API keys.

    Steps to reproduce the behavior:

    1. Run "pipenv install bscscan-python"
    2. Create script with single line from bscscan import BscScan as suggested from the docs
    3. Run script and get error

    Expected behavior A clear and concise description of what you expected to happen.

    The import should work based on the documentation.

    Screenshots If applicable, add screenshots to help explain your problem.

    N/A

    System info (please complete the following information):

    • OS and version: macOS 11.13.1
    • Python version: 3.8.10
    • bscscan-python version: 2.0.0

    Additional context Add any other context about the problem here.

    opened by molecularswords 4
  • How to How can I get the balance of a generated token?

    How to How can I get the balance of a generated token?

    Hello, I am trying to obtain for example the balance of Cake generated in Pancakeswap, I am using the function:

    get_acc_balance_by_token_contract_address(contract_address="0x0e09fabb73bd3ade0a17ecc321fd13a19e81ce82", address="MYADDRESS")

    Where "0x0e09fabb73bd3ade0a17ecc321fd13a19e81ce82", is the address of pancake, but the result is 0.

    Could you guide me to find my mistake?

    Thank you

    opened by cpfxcl 4
  • How to show decimal place?[bsc.get_bnb_balance]

    How to show decimal place?[bsc.get_bnb_balance]

    Almost certain this issue is with me, and not the API.
    Why is the decimal place not displaying when I use

    bsc.get_bnb_balance(address="0x0000000000000000000000000000000000001004")

    '167195709084498025431541166'

    I'm a noob....

    opened by doesntknowpython 4
  • Brython Integration [BUG]

    Brython Integration [BUG]

    Describe the bug Installed Bscscan-python and put it into a web using Brython, but the error shows like in the link

    To Reproduce In order to assist you with your problem, we need a minimal code snippet that replicates the bug. Avoid disclosing your API keys.

    Steps to reproduce the behavior:

    1. Install Python 3
    2. Embed Brython Script
    3. Test run for balance in