Providers

The provider is how web3 talks to the blockchain. Providers take JSON-RPC requests and return the response. This is normally done by submitting the request to an HTTP or IPC socket based server.

Note

web3.py supports one provider per instance. If you have an advanced use case that requires multiple providers, create and configure a new web3 instance per connection.

If you are already happily connected to your Ethereum node, then you can skip the rest of the Providers section.

Choosing How to Connect to Your Node

Most nodes have a variety of ways to connect to them. If you have not decided what kind of node to use, head on over to How do I choose which node to use?

The most common ways to connect to your node are:

IPC (uses local filesystem: fastest and most secure)
Websockets (works remotely, faster than HTTP)
HTTP (more nodes support it)

If you’re not sure how to decide, choose this way:

If you have the option of running web3.py on the same machine as the node, choose IPC.
If you must connect to a node on a different computer, use Websockets.
If your node does not support Websockets, use HTTP.

Most nodes have a way of “turning off” connection options. We recommend turning off all connection options that you are not using. This provides a safer setup: it reduces the number of ways that malicious hackers can try to steal your ether.

Once you have decided how to connect, you specify the details using a Provider. Providers are web3.py classes that are configured for the kind of connection you want.

See:

IPCProvider
WebsocketProvider
HTTPProvider
AsyncHTTPProvider

Once you have configured your provider, for example:

from web3 import Web3
my_provider = Web3.IPCProvider('/my/node/ipc/path')

Then you are ready to initialize your Web3 instance, like so:

w3 = Web3(my_provider)

Finally, you are ready to get started with web3.py.

Provider via Environment Variable

Alternatively, you can set the environment variable WEB3_PROVIDER_URI before starting your script, and web3 will look for that provider first.

Valid formats for this environment variable are:

file:///path/to/node/rpc-json/file.ipc
http://192.168.1.2:8545
https://node.ontheweb.com
ws://127.0.0.1:8546

Auto-initialization Provider Shortcuts

Geth dev Proof of Authority

To connect to a geth --dev Proof of Authority instance with defaults:

>>> from web3.auto.gethdev import w3

# confirm that the connection succeeded
>>> w3.is_connected()
True

Built In Providers

Web3 ships with the following providers which are appropriate for connecting to local and remote JSON-RPC servers.

HTTPProvider

class web3.providers.rpc.HTTPProvider(endpoint_uri[, request_kwargs, session])

This provider handles interactions with an HTTP or HTTPS based JSON-RPC server.

endpoint_uri should be the full URI to the RPC endpoint such as 'https://localhost:8545'. For RPC servers behind HTTP connections running on port 80 and HTTPS connections running on port 443 the port can be omitted from the URI.
request_kwargs should be a dictionary of keyword arguments which will be passed onto each http/https POST request made to your node.
session allows you to pass a requests.Session object initialized as desired.

>>> from web3 import Web3
>>> w3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545"))

Note that you should create only one HTTPProvider per python process, as the HTTPProvider recycles underlying TCP/IP network connections, for better performance.

Under the hood, the HTTPProvider uses the python requests library for making requests. If you would like to modify how requests are made, you can use the request_kwargs to do so. A common use case for this is increasing the timeout for each request.

>>> from web3 import Web3
>>> w3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545", request_kwargs={'timeout': 60}))

To tune the connection pool size, you can pass your own requests.Session.

>>> from web3 import Web3
>>> adapter = requests.adapters.HTTPAdapter(pool_connections=20, pool_maxsize=20)
>>> session = requests.Session()
>>> session.mount('http://', adapter)
>>> session.mount('https://', adapter)
>>> w3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545", session=session))

IPCProvider

class web3.providers.ipc.IPCProvider(ipc_path=None, testnet=False, timeout=10)

This provider handles interaction with an IPC Socket based JSON-RPC server.

ipc_path is the filesystem path to the IPC socket:

>>> from web3 import Web3
>>> w3 = Web3(Web3.IPCProvider("~/Library/Ethereum/geth.ipc"))

If no ipc_path is specified, it will use the first IPC file it can find from this list:

On Linux and FreeBSD:
- ~/.ethereum/geth.ipc
- ~/.local/share/io.parity.ethereum/jsonrpc.ipc
- ~/.local/share/trinity/mainnet/ipcs-eth1/jsonrpc.ipc
On Mac OS:
- ~/Library/Ethereum/geth.ipc
- ~/Library/Application Support/io.parity.ethereum/jsonrpc.ipc
- ~/.local/share/trinity/mainnet/ipcs-eth1/jsonrpc.ipc
On Windows:
- \\\.\pipe\geth.ipc
- \\\.\pipe\jsonrpc.ipc

WebsocketProvider

class web3.providers.websocket.WebsocketProvider(endpoint_uri[, websocket_timeout, websocket_kwargs])

This provider handles interactions with an WS or WSS based JSON-RPC server.

endpoint_uri should be the full URI to the RPC endpoint such as 'ws://localhost:8546'.
websocket_timeout is the timeout in seconds, used when receiving or sending data over the connection. Defaults to 10.
websocket_kwargs this should be a dictionary of keyword arguments which will be passed onto the ws/wss websocket connection.

>>> from web3 import Web3
>>> w3 = Web3(Web3.WebsocketProvider("ws://127.0.0.1:8546"))

Under the hood, the WebsocketProvider uses the python websockets library for making requests. If you would like to modify how requests are made, you can use the websocket_kwargs to do so. See the websockets documentation for available arguments.

Unlike HTTP connections, the timeout for WS connections is controlled by a separate websocket_timeout argument, as shown below.

>>> from web3 import Web3
>>> w3 = Web3(Web3.WebsocketProvider("ws://127.0.0.1:8546", websocket_timeout=60))

AutoProvider

AutoProvider is the default used when initializing web3.Web3 without any providers. There’s rarely a reason to use it explicitly.

AsyncHTTPProvider

class web3.providers.async_rpc.AsyncHTTPProvider(endpoint_uri[, request_kwargs])

This provider handles interactions with an HTTP or HTTPS based JSON-RPC server asynchronously.

endpoint_uri should be the full URI to the RPC endpoint such as 'https://localhost:8545'. For RPC servers behind HTTP connections running on port 80 and HTTPS connections running on port 443 the port can be omitted from the URI.
request_kwargs should be a dictionary of keyword arguments which will be passed onto each http/https POST request made to your node.
the cache_async_session() method allows you to use your own aiohttp.ClientSession object. This is an async method and not part of the constructor

>>> from aiohttp import ClientSession
>>> from web3 import AsyncWeb3, AsyncHTTPProvider

>>> w3 = AsyncWeb3(AsyncHTTPProvider(endpoint_uri))

>>> # If you want to pass in your own session:
>>> custom_session = ClientSession()
>>> await w3.provider.cache_async_session(custom_session) # This method is an async method so it needs to be handled accordingly

Under the hood, the AsyncHTTPProvider uses the python aiohttp library for making requests.

Supported Methods

Net

Contract

Contract is fully implemented for the Async provider. The only documented exception to this at the moment is where ENS is needed for address lookup. All addresses that are passed to Async contract should not be ENS addresses.

ENS

ENS is fully implemented for the Async provider.

Supported Middleware

EthereumTesterProvider

Warning

Experimental: This provider is experimental. There are still significant gaps in functionality. However it is being actively developed and supported.

class web3.providers.eth_tester.EthereumTesterProvider(eth_tester=None)

This provider integrates with the eth-tester library. The eth_tester constructor argument should be an instance of the EthereumTester or a subclass of BaseChainBackend class provided by the eth-tester library. If you would like a custom eth-tester instance to test with, see the eth-tester library documentation for details.

>>> from web3 import Web3, EthereumTesterProvider
>>> w3 = Web3(EthereumTesterProvider())