pyetherscan.client module

Library for connecting to the Etherscan API using a self contained client.

class pyetherscan.client.Client(apikey='YourApiKeyToken', timeout=5)

Bases: object

Represents an Etherscan API client.

Initialized using the ETHERSCAN_API_KEY environment variable (or you may pass the API key as an argument).

You can use this object to query the Etherscan database for raw data for each endpoint (see Public Methods below). An example is shown in the Example Usage section below.

Public Attributes:

• apikey
• timeout

Public Methods:

• get_single_balance()
• get_multi_balance()
• get_transactions_by_address()
• get_transaction_by_hash()
• get_blocks_mined_by_address()
• get_contract_abi()

Example Usage:

In [1]: client = Client()

In [2]: address = '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'

In [3]: address_balance = client.get_single_balance(address)

In [4]: address_balance.response_status_code
Out[4]: 200

In [5]: address_balance.message
Out[5]: 'OK'

In [6]: address_balance.balance
Out[6]: 748997604382925139479303

get_block_and_uncle_rewards_by_block_number(block_number)

Retrieves block and uncle rewards by block number.

Parameters:block_number (str or int) – The address of the token contract Returns:A response.TokenAccountBalanceResponse instance

Example Usage:

In [1]: client = Client()

In [2]: block_number = 2165403

In [3]: block_data = client.get_block_and_uncle_rewards_by_block_number(
    block_number
)

In [4]: block_data.rewards_data
Out[4]: {
    "blockNumber": "2165403",
    "timeStamp": "1472533979",
    "blockMiner": "0x13a06d3dfe21e0db5c016c03ea7d2509f7f8d1e3",
    "blockReward": "5314181600000000000",
    "uncles": [
        {
            "miner": "0xbcdfc35b86bedf72f0cda046a3c16829a2ef41d1",
            "unclePosition": "0",
            "blockreward": "3750000000000000000"
        }, {
            "miner": "0x0d0c9855c722ff0c78f21e43aa275a5b8ea60dce",
            "unclePosition": "1",
            "blockreward": "3750000000000000000"
        }
    ],
    "uncleInclusionReward": "312500000000000000"
}

get_blocks_mined_by_address(address, startblock=None, endblock=None, sort='asc', offset=None, page=None)

Obtains blocks mined by a single ethereum address.

Parameters:address (str) – The ethereum address Returns:A response.BlocksMinedByAddressResponse instance

Example Usage:

In [1]: client = Client()

In [2]: address = '0x9dd134d14d1e65f84b706d6f205cd5b1cd03a46b'

In [3]: blocks = client.get_blocks_mined_by_address(address)

In [4]: blocks.blocks
Out[4]: [
    {
        u'timeStamp': u'1491118514',
        u'blockReward': u'5194770940000000000',
        u'blockNumber': u'3462296'
    }, {
        u'timeStamp': u'1480072029',
        u'blockReward': u'5086562212310617100',
        u'blockNumber': u'2691400'
    }, ...
]

get_contract_abi(address)

Obtains contract details by address.

Parameters:address (str) – The ethereum address of the contract Returns:A response.ContractABIByAddressResponse instance

Example Usage:

In [1]: client = Client()

In [2]: address = '0xBB9bc244D798123fDe783fCc1C72d3Bb8C189413'

In [3]: contract = client.get_contract_abi(address)

In [4]: contract.contract_abi
Out[4]: [
    {
        "constant":true,
        "inputs": [
            {
                "name":"",
                "type":"uint256"
            }
        ],
        "name":"proposals",
        "outputs": [
            {
                "name":"recipient",
                "type":"address"
            }, {
                "name":"amount",
                "type":"uint256"
            }, {
                "name":"description",
                "type":"string"
            }, {
                ...
            }
        ]
    }

get_contract_execution_status(transaction_hash)

Retrieves contract status data by tx hash. Obtains whether or not there was an error during contract execution.

Parameters:transaction_hash (str) – The hash of the contract Returns:A response.ContractStatusResponse instance

Example Usage:

In [1]: client = Client()

In [2]: hash = '0x15f8e5ea1079d9a0bb04a4c58ae5fe7654b5b2b4463375ff7ffb490aa0032f3a'

In [3]: contract = client.get_contract_execution_status(hash)

In [4]: contract.contract_status
Out[4]: {
    u'status': u'1',
    u'message': u'OK',
    u'result': {
        u'isError': u'1',
        u'errDescription': u'Bad jump destination'
    }
}

get_multi_balance(addresses)

Obtains the balance for multiple addresses.

Parameters:addresses (list) – A list of ethereum addresses, each address should be a string Returns:A response.MultiAddressBalanceResponse instance

Example Usage:

In [1]: client = Client()

In [2]: addresses = addresses = [
    '0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a',
    '0x63a9975ba31b0b9626b34300f7f627147df1f526',
    '0x198ef1ec325a96cc354c7266a038be8b5c558f67'
]

In [3]: address_balances = client.get_multi_balance(addresses)

In [4]: address_balances.balances
Out[4]: {
    u'0x198ef1ec325a96cc354c7266a038be8b5c558f67': 1.2005264493462224e+22,
    u'0x63a9975ba31b0b9626b34300f7f627147df1f526': 3.3256713622282705e+20,
    u'0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a': 4.080716856407e+22
}

get_single_balance(address)

Obtains the balance for a single address.

Parameters:address (str) – The ethereum address Returns:A response.SingleAddressBalanceResponse instance

Example Usage:

In [1]: client = Client()

In [2]: address = '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'

In [3]: address_balance = client.get_single_balance(address)

In [4]: address_balance.balance
Out[4]: 748997604382925139479303

get_token_balance_by_address(contract_address, account_address)

Retrieves ERC-20 compliant token balance for an account given a contract account address.

Parameters:

• contract_address (str) – The address of the token contract
• account_address (str) – The address of the user account for which the token balance is being queried

Returns:

A response.TokenAccountBalanceResponse instance

Example Usage:

In [1]: client = Client()

In [2]: contract_address = '0x57d90b64a1a57749b0f932f1a3395792e12e7055'

In [3]: account_address = '0xe04f27eb70e025b78871a2ad7eabe85e61212761'

In [4]: token_balance = client.get_token_balance_by_address(
    contract_address,
    account_address
)

In [4]: token_balance.balance
Out[4]: 135499.0

get_token_supply_by_address(address)

Retrieves total token supply for an ERC-20 compliant token given a contract address.

Parameters:address (str) – The address of the token contract Returns:A response.TokenSupplyResponse instance

Example Usage:

In [1]: client = Client()

In [2]: contract_address = '0x57d90b64a1a57749b0f932f1a3395792e12e7055'

In [3]: contract = client.get_token_supply_by_address(
    contract_address
)

In [4]: contract.total_supply
Out[4]: 21265524714464.0

get_transaction_by_hash(transaction_hash, startblock=None, endblock=None, sort='asc', offset=None, page=None)

Obtains transaction details for a single transaction.

Parameters:hash (hash) – The ethereum transaction hash Returns:A response.TransactionsByHashResponse instance

Example Usage:

In [1]: client = Client()

In [2]: hash = '0x40eb908387324f2b575b4879cd9d7188f69c8fc9d87c901b9e2daaea4b442170'

In [3]: transaction_details = client.get_transactions_by_hash(hash)

In [4]: transaction_details.transaction
Out[4]: {
    u'contractAddress': u'',
    u'from': u'0x2cac6e4b11d6b58f6d3c1c9d5fe8faa89f60e5a2',
    u'timeStamp': u'1466489498',
    u'gas': u'2300',
    u'errCode': u'',
    u'value': u'7106740000000000',
    u'blockNumber': u'1743059',
    u'to': u'0x66a1c3eaf0f1ffc28d209c0763ed0ca614f3b002',
    u'input': u'',
    u'type': u'call',
    u'isError': u'0',
    u'gasUsed': u'0'
}

get_transactions_by_address(address, startblock=None, endblock=None, sort='asc', offset=None, page=None, internal=False)

Obtains a list of transactions for an ethereum address.

Parameters:

• address (str) – The ethereum address
• startblock (int) – An optional start block to limit transactions (defaults to None)
• endblock (int) – An optional end block to limit transactions (defaults to None)
• sort (str) – Sort result set (defaults to asc)
• offset (int) – The max number of results (must be used with page)
• page (int) – The page number of the result set to pull (must be used with max_results)
• internal (bool) – Whether or not to limit transactions to internal transactions (between contracts) - defaults to False

Returns:

A response.TransactionsByAddressResponse instance

Example Usage:

In [1]: client = Client()

In [2]: address = '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'

In [3]: address_transactions = client.get_transactions_by_address(address)

In [4]: address_transactions.transactions
Out[4]: [
    {
        u'nonce': u'0',
        u'contractAddress': u'0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae',
        u'cumulativeGasUsed': u'1436963',
        u'hash': u'0x9c81f44c29ff0226f835cd0a8a2f2a7eca6db52a711f8211b566fd15d3e0e8d4',
        u'blockHash': u'0xd3cabad6adab0b52eb632c386ea194036805713682c62cb589b5abcd76de2159',
        u'timeStamp': u'1439048640',
        u'gas': u'2000000',
        u'value': u'11901464239480000000000000',
        u'blockNumber': u'54092',
        u'to': u'',
        u'confirmations': u'3921579',
        u'input': u'0x606060405260....'
    }, {
        ...
    }, {
        ...
    }
]

pyetherscan.client.check_exception_for_retry(exception)

Prevent retrying if an etherscan response status is not 1.