start_rpc_proxy

Documentation for eth_defi.provider.rpc_proxy.start_rpc_proxy function.

start_rpc_proxy(rpc_urls, port=None, config=None, **kwargs)

Start a JSON-RPC failover proxy on a background thread.

The proxy listens on localhost and forwards incoming JSON-RPC POST requests to the given upstream RPC URLs with automatic failover, retry, and statistics collection.

Parameters

  • rpc_urls (list[str]) – Upstream RPC endpoint URLs to cycle through. At least one URL is required.

  • port (Optional[int]) –

    Local port to bind on 127.0.0.1.

    If None (the default), the server binds to port 0 which tells the operating system to assign a free ephemeral port atomically. The actual port is read back from the socket after binding and stored in RPCProxy.port. This avoids the TOCTOU race condition that occurs with find_free_port(): that function checks availability via connect(), but under heavy parallel test execution (pytest -n auto) another process can grab the same port between the check and the bind() call, resulting in OSError: [Errno 98] Address already in use.

    Pass an explicit port number only when you need a deterministic address (e.g. for debugging or firewall rules).

  • config (Optional[eth_defi.provider.rpc_proxy.RPCProxyConfig]) – Proxy configuration. If None, a default RPCProxyConfig is used. Individual fields can be overridden via **kwargs.

  • kwargs – Override individual RPCProxyConfig fields. For example start_rpc_proxy(urls, timeout=10.0) is equivalent to start_rpc_proxy(urls, config=RPCProxyConfig(timeout=10.0)). When both config and kwargs are provided, kwargs win.

Returns

A running RPCProxy instance. Call RPCProxy.close() when done.

Return type

eth_defi.provider.rpc_proxy.RPCProxy