Web3 API

class web3.Web3(provider)

Each Web3 instance exposes the following APIs.

Providers

Web3.HTTPProvider

Convenience API to access web3.providers.rpc.HTTPProvider

Web3.IPCProvider

Convenience API to access web3.providers.ipc.IPCProvider

Attributes

Web3.api

Returns the current Web3 version.

>>> web3.api
"4.7.0"
Web3.client_version
  • Delegates to web3_clientVersion RPC Method

Returns the current client version.

>>> web3.client_version
'Geth/v1.4.11-stable-fed692f6/darwin/go1.7'
Web3.clientVersion

Warning

Deprecated: This property is deprecated in favor of client_version()

Encoding and Decoding Helpers

Web3.to_hex(primitive=None, hexstr=None, text=None)

Takes a variety of inputs and returns it in its hexadecimal representation. It follows the rules for converting to hex in the JSON-RPC spec

>>> Web3.to_hex(0)
'0x0'
>>> Web3.to_hex(1)
'0x1'
>>> Web3.to_hex(0x0)
'0x0'
>>> Web3.to_hex(0x000F)
'0xf'
>>> Web3.to_hex(b'')
'0x'
>>> Web3.to_hex(b'\x00\x0F')
'0x000f'
>>> Web3.to_hex(False)
'0x0'
>>> Web3.to_hex(True)
'0x1'
>>> Web3.to_hex(hexstr='0x000F')
'0x000f'
>>> Web3.to_hex(hexstr='000F')
'0x000f'
>>> Web3.to_hex(text='')
'0x'
>>> Web3.to_hex(text='cowmö')
'0x636f776dc3b6'
Web3.toHex(primitive=None, hexstr=None, text=None)

Warning

Deprecated: This method is deprecated in favor of to_hex()

Web3.to_text(primitive=None, hexstr=None, text=None)

Takes a variety of inputs and returns its string equivalent. Text gets decoded as UTF-8.

>>> Web3.to_text(0x636f776dc3b6)
'cowmö'
>>> Web3.to_text(b'cowm\xc3\xb6')
'cowmö'
>>> Web3.to_text(hexstr='0x636f776dc3b6')
'cowmö'
>>> Web3.to_text(hexstr='636f776dc3b6')
'cowmö'
>>> Web3.to_text(text='cowmö')
'cowmö'
Web3.toText(primitive=None, hexstr=None, text=None)

Warning

Deprecated: This method is deprecated in favor of to_text()

Web3.to_bytes(primitive=None, hexstr=None, text=None)

Takes a variety of inputs and returns its bytes equivalent. Text gets encoded as UTF-8.

>>> Web3.to_bytes(0)
b'\x00'
>>> Web3.to_bytes(0x000F)
b'\x0f'
>>> Web3.to_bytes(b'')
b''
>>> Web3.to_bytes(b'\x00\x0F')
b'\x00\x0f'
>>> Web3.to_bytes(False)
b'\x00'
>>> Web3.to_bytes(True)
b'\x01'
>>> Web3.to_bytes(hexstr='0x000F')
b'\x00\x0f'
>>> Web3.to_bytes(hexstr='000F')
b'\x00\x0f'
>>> Web3.to_bytes(text='')
b''
>>> Web3.to_bytes(text='cowmö')
b'cowm\xc3\xb6'
Web3.toBytes(primitive=None, hexstr=None, text=None)

Warning

Deprecated: This method is deprecated in favor of to_bytes()

Web3.to_int(primitive=None, hexstr=None, text=None)

Takes a variety of inputs and returns its integer equivalent.

>>> Web3.to_int(0)
0
>>> Web3.to_int(0x000F)
15
>>> Web3.to_int(b'\x00\x0F')
15
>>> Web3.to_int(False)
0
>>> Web3.to_int(True)
1
>>> Web3.to_int(hexstr='0x000F')
15
>>> Web3.to_int(hexstr='000F')
15
Web3.toInt(primitive=None, hexstr=None, text=None)

Warning

Deprecated: This method is deprecated in favor of to_int()

Web3.to_json(obj)

Takes a variety of inputs and returns its JSON equivalent.

>>> Web3.to_json(3)
'3'
>>> Web3.to_json({'one': 1})
'{"one": 1}'
Web3.toJSON(obj)

Warning

Deprecated: This method is deprecated in favor of to_json()

Currency Conversions

Web3.to_wei(value, currency)

Returns the value in the denomination specified by the currency argument converted to wei.

>>> Web3.to_wei(1, 'ether')
1000000000000000000
Web3.toWei(value, currency)

Warning

Deprecated: This method is deprecated in favor of to_wei()

Web3.from_wei(value, currency)

Returns the value in wei converted to the given currency. The value is returned as a Decimal to ensure precision down to the wei.

>>> Web3.from_wei(1000000000000000000, 'ether')
Decimal('1')
Web3.fromWei(value, currency)

Warning

Deprecated: This method is deprecated in favor of from_wei()

Addresses

Web3.is_address(value)

Returns True if the value is one of the recognized address formats.

  • Allows for both 0x prefixed and non-prefixed values.
  • If the address contains mixed upper and lower cased characters this function also checks if the address checksum is valid according to EIP55
>>> Web3.is_address('0xd3CdA913deB6f67967B99D67aCDFa1712C293601')
True
Web3.isAddress(value)

Warning

Deprecated: This method is deprecated in favor of is_address()

Web3.is_checksum_address(value)

Returns True if the value is a valid EIP55 checksummed address

>>> Web3.is_checksum_address('0xd3CdA913deB6f67967B99D67aCDFa1712C293601')
True
>>> Web3.is_checksum_address('0xd3cda913deb6f67967b99d67acdfa1712c293601')
False
Web3.isChecksumAddress(value)

Warning

Deprecated: This method is deprecated in favor of is_checksum_address()

Web3.to_checksum_address(value)

Returns the given address with an EIP55 checksum.

>>> Web3.to_checksum_address('0xd3cda913deb6f67967b99d67acdfa1712c293601')
'0xd3CdA913deB6f67967B99D67aCDFa1712C293601'
Web3.toChecksumAddress(value)

Warning

Deprecated: This method is deprecated in favor of to_checksum_address()

Cryptographic Hashing

classmethod Web3.keccak(primitive=None, hexstr=None, text=None)

Returns the Keccak-256 of the given value. Text is encoded to UTF-8 before computing the hash, just like Solidity. Any of the following are valid and equivalent:

>>> Web3.keccak(0x747874)
>>> Web3.keccak(b'\x74\x78\x74')
>>> Web3.keccak(hexstr='0x747874')
>>> Web3.keccak(hexstr='747874')
>>> Web3.keccak(text='txt')
HexBytes('0xd7278090a36507640ea6b7a0034b69b0d240766fa3f98e3722be93c613b29d2e')
classmethod Web3.sha3(primitive=None, hexstr=None, text=None)

Warning

This method has been deprecated and is an alias for keccak(). See new method description above for details.

classmethod Web3.solidity_keccak(abi_types, value)

Returns the Keccak-256 as it would be computed by the solidity keccak function on the provided value and abi_types. The abi_types value should be a list of solidity type strings which correspond to each of the provided values.

>>> Web3.solidity_keccak(['bool'], [True])
HexBytes("0x5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2")

>>> Web3.solidity_keccak(['uint8', 'uint8', 'uint8'], [97, 98, 99])
HexBytes("0x4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45")

>>> Web3.solidity_keccak(['uint8[]'], [[97, 98, 99]])
HexBytes("0x233002c671295529bcc50b76a2ef2b0de2dac2d93945fca745255de1a9e4017e")

>>> Web3.solidity_keccak(['address'], ["0x49EdDD3769c0712032808D86597B84ac5c2F5614"])
HexBytes("0x2ff37b5607484cd4eecf6d13292e22bd6e5401eaffcc07e279583bc742c68882")

>>> Web3.solidity_keccak(['address'], ["ethereumfoundation.eth"])
HexBytes("0x913c99ea930c78868f1535d34cd705ab85929b2eaaf70fcd09677ecd6e5d75e9")

Comparable solidity usage:

bytes32 data1 = keccak256(abi.encodePacked(true));
assert(data1 == hex"5fe7f977e71dba2ea1a68e21057beebb9be2ac30c6410aa38d4f3fbe41dcffd2");
bytes32 data2 = keccak256(abi.encodePacked(uint8(97), uint8(98), uint8(99)));
assert(data2 == hex"4e03657aea45a94fc7d47ba826c8d667c0d1e6e33a64a036ec44f58fa12d6c45");
classmethod Web3.solidityKeccak(abi_types, value)

Warning

This method has been deprecated and is an alias for solidity_keccak(). See new method description above for details.

classmethod Web3.soliditySha3(abi_types, value)

Warning

This method has been deprecated and is an alias for solidity_keccak(). See new method above description for details.

Check Encodability

w3.is_encodable(_type, value)

Returns True if a value can be encoded as the given type. Otherwise returns False.

>>> from web3.auto.gethdev import w3
>>> w3.is_encodable('bytes2', b'12')
True
>>> w3.is_encodable('bytes2', b'1')
True
>>> w3.is_encodable('bytes2', '0x1234')
True
>>> w3.is_encodable('bytes2', b'123')
False
w3.enable_strict_bytes_type_checking()

Enables stricter bytes type checking. For more examples see Enabling Strict Checks for Bytes Types

>>> from web3.auto.gethdev import w3
>>> w3.enable_strict_bytes_type_checking()
>>> w3.is_encodable('bytes2', b'12')
True
>>> w3.is_encodable('bytes2', b'1')
False

RPC API Modules

Each Web3 instance also exposes these namespaced API modules.

Web3.eth

See web3.eth API

Web3.miner

See Miner API

Web3.pm

See Package Manager API

Web3.geth

See Geth API

Web3.parity

See Parity API

These internal modules inherit from the web3.module.Module class which give them some configurations internal to the web3.py library.

External Modules

External modules can be used to introduce custom or third-party APIs to your Web3 instance. External modules are simply classes whose methods and properties can be made available within the Web3 instance. Optionally, the external module may make use of the parent Web3 instance by accepting it as the first argument within the __init__ function:

>>> class ExampleModule:
...     def __init__(self, w3):
...         self.w3 = w3
...
...     def print_balance_of_shaq(self):
...         print(self.w3.eth.get_balance('shaq.eth'))

Warning

Given the flexibility of external modules, use caution and only import modules from trusted third parties and open source code you’ve vetted!

Configuring external modules can occur either at instantiation of the Web3 instance or by making use of the attach_modules() method. To instantiate the Web3 instance with external modules use the external_modules keyword argument:

>>> from web3 import Web3, HTTPProvider
>>> from external_module_library import (
...     ModuleClass1,
...     ModuleClass2,
...     ModuleClass3,
...     ModuleClass4,
...     ModuleClass5,
... )
>>> w3 = Web3(
...     HTTPProvider(provider_uri),
...     external_modules={
...         'module1': ModuleClass1,
...         'module2': (ModuleClass2, {
...             'submodule1': ModuleClass3,
...             'submodule2': (ModuleClass4, {
...                 'submodule2a': ModuleClass5,  # submodule children may be nested further if necessary
...             })
...         })
...     }
... )

# `return_zero`, in this case, is an example attribute of the `ModuleClass1` object
>>> w3.module1.return_zero()
0
>>> w3.module2.submodule1.return_one()
1
>>> w3.module2.submodule2.submodule2a.return_two()
2
w3.attach_modules(modules)

The attach_modules() method can be used to attach external modules after the Web3 instance has been instantiated.

Modules are attached via a dict with module names as the keys. The values can either be the module classes themselves, if there are no submodules, or two-item tuples with the module class as the 0th index and a similarly built dict containing the submodule information as the 1st index. This pattern may be repeated as necessary.

>>> from web3 import Web3, HTTPProvider
>>> from external_module_library import (
...     ModuleClass1,
...     ModuleClass2,
...     ModuleClass3,
...     ModuleClass4,
...     ModuleClass5,
... )
>>> w3 = Web3(HTTPProvider(provider_uri))

>>> w3.attach_modules({
...     'module1': ModuleClass1,  # the module class itself may be used for a single module with no submodules
...     'module2': (ModuleClass2, {  # a tuple with module class and corresponding submodule dict may be used for modules with submodules
...         'submodule1': ModuleClass3,
...         'submodule2': (ModuleClass4, {  # this pattern may be repeated as necessary
...             'submodule2a': ModuleClass5,
...         })
...     })
... })
>>> w3.module1.return_zero()
0
>>> w3.module2.submodule1.return_one()
1
>>> w3.module2.submodule2.submodule2a.return_two()
2