The purpose of this page is to give you a sense of everything web3.py can do and to serve as a quick reference guide. You'll find a summary of each feature with links to learn more. You may also be interested in the Examples <examples>
page, which demonstrates some of these features in greater detail.
After installing web3.py (via pip install web3
), you'll need to configure a provider endpoint and any middleware you want to use beyond the defaults.
providers
are how web3.py connects to a blockchain. The library comes with the following built-in providers:
~web3.providers.ipc.IPCProvider
for connecting to ipc socket based JSON-RPC servers.~web3.providers.rpc.HTTPProvider
for connecting to http and https based JSON-RPC servers.~web3.providers.websocket.WebsocketProvider
for connecting to ws and wss websocket based JSON-RPC servers.~web3.providers.async_rpc.AsyncHTTPProvider
for connecting to http and https based JSON-RPC servers.
>>> from web3 import Web3, AsyncWeb3
# IPCProvider:
>>> w3 = Web3(Web3.IPCProvider('./path/to/geth.ipc'))
# HTTPProvider:
>>> w3 = Web3(Web3.HTTPProvider('http://127.0.0.1:8545'))
# WebsocketProvider:
>>> w3 = Web3(Web3.WebsocketProvider('ws://127.0.0.1:8546'))
>>> w3.is_connected()
True
# AsyncHTTPProvider:
>>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('http://127.0.0.1:8545'))
>>> await w3.is_connected()
True
For more context, see the providers
documentation.
Your web3.py instance may be further configured via middleware
.
web3.py middleware is described using an onion metaphor, where each layer of middleware may affect both the incoming request and outgoing response from your provider. The documentation includes a visualization <Modifying_Middleware>
of this idea.
Several middleware are included by default <default_middleware>
. You may add to (add <Web3.middleware_onion.add>
, inject <Web3.middleware_onion.inject>
, replace <Web3.middleware_onion.replace>
) or disable (remove <Web3.middleware_onion.remove>
, clear <Web3.middleware_onion.clear>
) any of these middleware.
Private keys are required to approve any transaction made on your behalf. The manner in which your key is secured will determine how you create and send transactions in web3.py.
A local node, like Geth, may manage your keys for you. You can reference those keys using the web3.eth.accounts <web3.eth.Eth.accounts>
property.
A hosted node, like Infura, will have no knowledge of your keys. In this case, you'll need to have your private key available locally for signing transactions.
Full documentation on the distinction between keys can be found here <eth-account>
. The separate guide to transactions
may also help clarify how to manage keys.
The Web3 <web3_base>
class includes a number of convenient utility functions:
Web3.is_encodable() <web3.w3.is_encodable>
Web3.to_bytes() <web3.Web3.to_bytes>
Web3.to_hex() <web3.Web3.to_hex>
Web3.to_int() <web3.Web3.to_int>
Web3.to_json() <web3.Web3.to_json>
Web3.to_text() <web3.Web3.to_text>
Web3.is_address() <web3.Web3.is_address>
Web3.is_checksum_address() <web3.Web3.is_checksum_address>
Web3.to_checksum_address() <web3.Web3.to_checksum_address>
Web3.from_wei() <web3.Web3.from_wei>
Web3.to_wei() <web3.Web3.to_wei>
Web3.keccak() <web3.Web3.keccak>
Web3.solidity_keccak() <web3.Web3.solidity_keccak>
The most commonly used APIs for interacting with Ethereum can be found under the web3.eth
namespace. As a reminder, the examples
page will demonstrate how to use several of these methods.
Viewing account balances (get_balance <web3.eth.Eth.get_balance>
), transactions (get_transaction <web3.eth.Eth.get_transaction>
), and block data (get_block <web3.eth.Eth.get_block>
) are some of the most common starting points in web3.py.
web3.eth.get_balance() <web3.eth.Eth.get_balance>
web3.eth.get_block() <web3.eth.Eth.get_block>
web3.eth.get_block_transaction_count() <web3.eth.Eth.get_block_transaction_count>
web3.eth.get_code() <web3.eth.Eth.get_code>
web3.eth.get_proof() <web3.eth.Eth.get_proof>
web3.eth.get_storage_at() <web3.eth.Eth.get_storage_at>
web3.eth.get_transaction() <web3.eth.Eth.get_transaction>
web3.eth.get_transaction_by_block() <web3.eth.Eth.get_transaction_by_block>
web3.eth.get_transaction_count() <web3.eth.Eth.get_transaction_count>
web3.eth.get_uncle_by_block() <web3.eth.Eth.get_uncle_by_block>
web3.eth.get_uncle_count() <web3.eth.Eth.get_uncle_count>
The most common use cases will be satisfied with send_transaction <web3.eth.Eth.send_transaction>
or the combination of sign_transaction <web3.eth.Eth.sign_transaction>
and send_raw_transaction <web3.eth.Eth.send_raw_transaction>
. For more context, see the full guide to transactions
.
Note
If interacting with a smart contract, a dedicated API exists. See the next section, Contracts <overview_contracts>
.
web3.eth.send_transaction() <web3.eth.Eth.send_transaction>
web3.eth.sign_transaction() <web3.eth.Eth.sign_transaction>
web3.eth.send_raw_transaction() <web3.eth.Eth.send_raw_transaction>
web3.eth.replace_transaction() <web3.eth.Eth.replace_transaction>
web3.eth.modify_transaction() <web3.eth.Eth.modify_transaction>
web3.eth.wait_for_transaction_receipt() <web3.eth.Eth.wait_for_transaction_receipt>
web3.eth.get_transaction_receipt() <web3.eth.Eth.get_transaction_receipt>
web3.eth.sign() <web3.eth.Eth.sign>
web3.eth.sign_typed_data() <web3.eth.Eth.sign_typed_data>
web3.eth.estimate_gas() <web3.eth.Eth.estimate_gas>
web3.eth.generate_gas_price() <web3.eth.Eth.generate_gas_price>
web3.eth.set_gas_price_strategy() <web3.eth.Eth.set_gas_price_strategy>
web3.py can help you deploy, read from, or execute functions on a deployed contract.
Deployment requires that the contract already be compiled, with its bytecode and ABI available. This compilation step can be done within Remix or one of the many contract development frameworks, such as Ape.
Once the contract object is instantiated, calling transact
on the constructor <web3.contract.Contract.constructor>
method will deploy an instance of the contract:
>>> ExampleContract = w3.eth.contract(abi=abi, bytecode=bytecode)
>>> tx_hash = ExampleContract.constructor().transact()
>>> tx_receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
>>> tx_receipt.contractAddress
'0x8a22225eD7eD460D7ee3842bce2402B9deaD23D3'
Once a deployed contract is loaded into a Contract object, the functions of that contract are available on the functions
namespace:
>>> deployed_contract = w3.eth.contract(address=tx_receipt.contractAddress, abi=abi)
>>> deployed_contract.functions.myFunction(42).transact()
If you want to read data from a contract (or see the result of transaction locally, without executing it on the network), you can use the ContractFunction.call <web3.contract.ContractFunction.call>
method, or the more concise ContractCaller <web3.contract.ContractCaller>
syntax:
# Using ContractFunction.call
>>> deployed_contract.functions.getMyValue().call()
42
# Using ContractCaller
>>> deployed_contract.caller().getMyValue()
42
For more, see the full Contracts
documentation.
web3.eth.contract() <web3.eth.Eth.contract>
Contract.address <web3.contract.Contract.address>
Contract.abi <web3.contract.Contract.abi>
Contract.bytecode <web3.contract.Contract.bytecode>
Contract.bytecode_runtime <web3.contract.Contract.bytecode_runtime>
Contract.functions <web3.contract.Contract.functions>
Contract.events <web3.contract.Contract.events>
Contract.fallback <web3.contract.Contract.fallback.call>
Contract.constructor() <web3.contract.Contract.constructor>
Contract.encodeABI() <web3.contract.Contract.encodeABI>
web3.contract.ContractFunction <web3.contract.ContractFunction>
web3.contract.ContractEvents <web3.contract.ContractEvents>
If you want to react to new blocks being mined or specific events being emitted by a contract, you can leverage web3.py filters.
# Use case: filter for new blocks
>>> new_filter = web3.eth.filter('latest')
# Use case: filter for contract event "MyEvent"
>>> new_filter = deployed_contract.events.MyEvent.create_filter(fromBlock='latest')
# retrieve filter results:
>>> new_filter.get_all_entries()
>>> new_filter.get_new_entries()
More complex patterns for creating filters and polling for logs can be found in the filters
documentation.
web3.eth.filter() <web3.eth.Eth.filter>
web3.eth.get_filter_changes() <web3.eth.Eth.get_filter_changes>
web3.eth.get_filter_logs() <web3.eth.Eth.get_filter_logs>
web3.eth.uninstall_filter() <web3.eth.Eth.uninstall_filter>
web3.eth.get_logs() <web3.eth.Eth.get_logs>
Contract.events.your_event_name.create_filter() <web3.contract.Contract.events.your_event_name.create_filter>
Contract.events.your_event_name.build_filter() <web3.contract.Contract.events.your_event_name.build_filter>
Filter.get_new_entries() <web3.utils.filters.Filter.get_new_entries>
Filter.get_all_entries() <web3.utils.filters.Filter.get_all_entries>
Filter.format_entry() <web3.utils.filters.Filter.format_entry>
Filter.is_valid_entry() <web3.utils.filters.Filter.is_valid_entry>
Some basic network properties are available on the web3.net
object:
web3.net.listening
web3.net.peer_count
web3.net.version
ethPM allows you to package up your contracts for reuse or use contracts from another trusted registry. See the full details here <ethpm>
.
Ethereum Name Service (ENS) provides the infrastructure for human-readable addresses. If an address is registered with the ENS registry, the domain name can be used in place of the address itself. For example, the registered domain name ethereum.eth
will resolve to the address 0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe
. web3.py has support for ENS, documented here <ens_overview>
.