pyetherscan package

Module contents

Package containing core pyetherscan functionality.

class pyetherscan.Client(apikey='YourApiKeyToken', timeout=5)[source]

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:

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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....'
    }, {
        ...
    }, {
        ...
    }
]
exception pyetherscan.EtherscanDataError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for data related errors (e.g. if result is []).

exception pyetherscan.EtherscanInitializationError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Initialization related errors.

exception pyetherscan.EtherscanConnectionError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Connection related errors.

exception pyetherscan.EtherscanRequestError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Request related errors.

exception pyetherscan.EtherscanAddressError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Address related errors.

exception pyetherscan.EtherscanContractError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Contract related errors.

exception pyetherscan.EtherscanTransactionError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Transaction related errors.

exception pyetherscan.EtherscanBlockError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Block related errors.

exception pyetherscan.EtherscanEventLogError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for EventLog related errors.

exception pyetherscan.EtherscanGethProxyError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for GethProxy related errors.

exception pyetherscan.EtherscanWebsocketError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Websocket related errors.

exception pyetherscan.EtherscanTokenError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Token related errors.

exception pyetherscan.EtherscanStatsError[source]

Bases: pyetherscan.error.EtherscanBaseError

An abstract error class for Stats related errors.

class pyetherscan.Transaction(data)[source]

Bases: object

Represents a generic ethereum transaction. The object is built to lazily parse transactions. Attributes are only evaluated when called for the first time.

Public Attributes:

  • nonce
  • contract_address
  • cumulative_gas_used
  • hash
  • block_hash
  • time_stamp
  • gas
  • gas_price
  • value
  • block_number
  • block
  • to
  • from_
  • confirmations
  • input
  • transaction_index
  • type
  • datetime_executed
  • gas_used

Initializes the Transaction object.

Parameters:data (dict) – The dictionary of data that makes up the transaction.
block
block_hash
block_number
confirmations
contract_address
cumulative_gas_used
datetime_executed
from_
gas
gas_price
gas_used
hash
input
nonce
time_stamp
to
transaction_index
type
value
class pyetherscan.Address(address)[source]

Bases: object

Represents a base address.

This uses the Client object to retrieve information about, and construct, the Address.

Public Attributes:
  • address
  • balance
  • blocks_mined
Public Methods:

Example Usage:

In [1]: address = '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'

In [2]: ethereum_address = Address(address)

In [3]: ethereum_address.balance
Out[3]: 748997604382925139479303.0

In [4]: for txn in ethereum_address.transactions:
   ...:     print(txn.value)

Initializes an ethereum address object.

balance

The balance in ether for this address.

blocks_mined
token_balance(contract_address)[source]

Obtains an address’s ERC-20 compliant token balance given a token contract address.

Parameters:contract_address (str) – The address of the token contract.
Returns:The balance of the token as a float.
transactions

returns a ethereum.TransactionContainer object. This object can be treated as a sequence object containing transactions this address was involved in.

class pyetherscan.Block(block_number)[source]

Bases: object

Represents an ethereum block.

This uses the Client object to retrieve information about, and construct, the Block.

Public Attributes:
  • time_stamp
  • block_miner
  • block_reward
  • uncles
  • datetime_mined
  • uncle_inclusion_reward

Example Usage:

In [1]: address = '0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae'

In [2]: ethereum_address = Address(address)

In [3]: ethereum_address.balance
Out[3]: 748997604382925139479303.0

In [4]: for txn in ethereum_address.transactions:
   ...:     print(txn.value)
block_miner
block_reward
datetime_mined
time_stamp
uncle_inclusion_reward
uncles
class pyetherscan.Token(contract_address)[source]

Bases: object

Represents an ERC-20 compliant token.

Parameters:contract_address (str) – The address of the Token contract
supply
token_balance(address)[source]

The user balance of this token for a given address.

Parameters:address (str) – An ethereum address.
Returns:The balance as a float.
class pyetherscan.SingleAddressBalanceResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

Represents a response object for a single address account balance call within the Etherscan Accounts endpoint.

Available attributes:
  • balance: The balance of the address returned as a float.

Example:

parse_response()[source]

Parses a single balance request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":"40807168564070000000000"
}
class pyetherscan.MultiAddressBalanceResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

Represents a response object for a multi address account balance call within the Etherscan Accounts endpoint.

Available attributes:
  • balances: The balances of the addresses returned as a dict.

Example:

parse_response()[source]

Parses a multi balance request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":[
        {
            "account":"0xddbd2b932c763ba5b1b7ae3b362eac3e8d40121a",
            "balance":"40807168564070000000000"
        }, {
            "account":"0x63a9975ba31b0b9626b34300f7f627147df1f526",
            "balance":"332567136222827062478"
        }, {
            "account":"0x198ef1ec325a96cc354c7266a038be8b5c558f67",
            "balance":"12005264493462223951724"
        }
    ]
}
class pyetherscan.TransactionsByAddressResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

parse_response()[source]

Parses a transactions by address request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":[
        {
            "blockNumber":"54092",
            "timeStamp":"1439048640",
            "hash":"0x9c81f44c29ff0226f83...",
            "nonce":"0",
            "blockHash":"0xd3cabad6adab0b5...",
            "transactionIndex":"0",
            "from":"0x5abfec25f74cd88437631a7731906932776356f9",
            "to":"",
            "value":"11901464239480000000000000",
            "gas":"2000000",
            "gasPrice":"10000000000000",
            "isError":"0",
            "input":"0x6060b91f525b5ae7a03d...",
            "contractAddress":"0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
            "cumulativeGasUsed":"1436963",
            "gasUsed":"1436963",
            "confirmations":"3921024"
        }, {
            ...
        }
    ]
}
class pyetherscan.TransactionsByHashResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

parse_response()[source]

Parses a transactions by hash request response. Example API response output:
{

“status”:”1”, “message”:”OK”, “result”:[

{
“blockNumber”:”1743059”, “timeStamp”:”1466489498”, “from”:”0x2cac6e4b11d6b58f6d3c1c9d5fe8faa89f60e5a2”, “to”:”0x66a1c3eaf0f1ffc28d209c0763ed0ca614f3b002”, “value”:”7106740000000000”, “contractAddress”:””, “input”:””, “type”:”call”, “gas”:”2300”, “gasUsed”:”0”, “isError”:”0”, “errCode”:”“

}

]

}

class pyetherscan.BlocksMinedByAddressResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

parse_response()[source]

Parses a blocks mined by address request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":[
        {
            "blockNumber":"3462296",
            "timeStamp":"1491118514",
            "blockReward":"5194770940000000000"
        }, {
            ...
        }
    ]
}
class pyetherscan.ContractABIByAddressResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

parse_response()[source]

Parses a contract abi by address request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":[
        {
            'constant': True,
            'inputs': [
                {
                    'name': '',
                    'type': 'uint256'
                }
            ],
            'name': 'proposals',
            'outputs': [
                {'name': 'recipient', 'type': 'address'},
                {'name': 'amount', 'type': 'uint256'},
                {'name': 'description', 'type': 'string'},
                {'name': 'votingDeadline', 'type': 'uint256'},
                {'name': 'open', 'type': 'bool'},
                {'name': 'proposalPassed', 'type': 'bool'},
                {'name': 'proposalHash', 'type': 'bytes32'},
                {'name': 'proposalDeposit', 'type': 'uint256'},
                {'name': 'newCurator', 'type': 'bool'},
                {'name': 'yea', 'type': 'uint256'},
                {'name': 'nay', 'type': 'uint256'},
                {'name': 'creator', 'type': 'address'}
            ],
            'type': 'function'
        }, {
            ...
        }
    ]
}
class pyetherscan.ContractStatusResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

Represents a response object for a contract status call within the Etherscan Contracts endpoint.

Available attributes:
  • contract_status: The status of the contract returned as a json object.

Example:

parse_response()[source]

Parses a transaction status by hash request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":{
        "isError":"1",
        "errDescription":"Bad jump destination"
    }
}
class pyetherscan.TokenSupplyResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

Represents a response object for a token supply call within the Etherscan Tokens endpoint.

Available attributes:
  • total_supply: The total supply of the token returned as a float.

Example:

parse_response()[source]

Parses a token supply by address request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":"21265524714464"
}
class pyetherscan.TokenAccountBalanceResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

Represents a response object for a token account balance call within the Etherscan Tokens endpoint.

Available attributes:
  • balance: The account balance of a token (by contract address)

returned as a float.

Example:

parse_response()[source]

Parses a token account balance request response. Example API response output:

{
    "status":"1",
    "message":"OK",
    "result":"135499"
}
class pyetherscan.BlockRewardsResponse(resp)[source]

Bases: pyetherscan.response.EtherscanResponse

Represents a response object for a block / uncle rewards API call to the Etherscan Blocks endpoint.

Available attributes:
  • rewards_data: A dict of the rewards for the block and any uncles mined.

Example:

parse_response()[source]

Parses a token account balance request response. Example API response output:

{
    "status": "1",
    "message": "OK",
    "result": {
        "blockNumber": "2165403",
        "timeStamp": "1472533979",
        "blockMiner": "0x13a06d3dfe21e0db5c016c03ea7d2509f7f8d1e3",
        "blockReward": "5314181600000000000",
        "uncles": [
            {
                "miner": "0xbcdfc35b86bedf72f0cda046a3c16829a2ef41d1",
                "unclePosition": "0",
                "blockreward": "3750000000000000000"
            }, {
                "miner": "0x0d0c9855c722ff0c78f21e43aa275a5b8ea60dce",
                "unclePosition": "1",
                "blockreward": "3750000000000000000"
            }
        ],
        "uncleInclusionReward": "312500000000000000"
    }
}