micro-web3
A small Ethereum client: JSON-RPC over urllib3, a hand-rolled Solidity ABI codec, EIP-55 checksums, and Multicall3 batching.
Built to replace the slice of web3.py that a backend actually uses, without
pulling in web3, eth-abi, eth-utils, eth-typing, or their transitive
dependencies. Two runtime dependencies: pycryptodome for Keccak-256 and
urllib3 for HTTP.
- Python 3.13+
- HTTP via
urllib3with one connection pool per node; no retries, no redirects, and proxy environment variables are not read - No ABI/type/hex-byte libraries
py.typed
Install
uv add micro-web3
Quickstart
from micro_web3 import Contract, RpcNode
node = RpcNode("https://ethereum-rpc.publicnode.com", timeout=4)
node.endpoint_uri # 'https://ethereum-rpc.publicnode.com'
node.is_connected() # web3_clientVersion probe; False instead of raising
node.close() # optional: release pooled connections (pool size: RpcNode(uri, pool_maxsize=10))
erc20 = Contract("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", abi)
erc20.call(node, "decimals") # 6
erc20.call(node, "balanceOf", [holder]) # int
erc20.encode("balanceOf", [holder]) # '0x70a08231...' (hex, selector included)
Contract.call performs one eth_call and decodes the result: a single
output is unwrapped, multiple outputs come back as a tuple.
Logs
from micro_web3 import get_logs
logs = get_logs(node, address=token, topics=[transfer_topic], from_block=0, to_block="latest")
logs[0]["blockNumber"] # '0x...' — raw JSON-RPC, never normalised
logs[0]["data"] # '0x...'
Raw hex is deliberate: it matches the Etherscan/Blockscout shapes, so one
consumer can handle every indexer identically. Block filters accept int,
decimal strings, hex strings or tags; they are emitted as JSON-RPC quantities.
Multicall
from micro_web3 import try_aggregate
results = try_aggregate(
node,
[
(token_a, erc20.encode("balanceOf", [holder])),
(token_b, erc20.encode("balanceOf", [holder])),
],
)
# [b'...', None] — one entry per call, None where that call reverted
try_aggregate uses Multicall3's tryAggregate(false, calls).
ABI
from micro_web3 import decode_outputs, encode_call, to_checksum_address
data = encode_call(abi, "transfer", [to, amount])
values = decode_outputs(["uint256"], "0x" + "00" * 31 + "2a")
Supported types: address, bool, uintN, intN, bytesN, bytes,
string, function, fixed and dynamic arrays, tuples, and nested
combinations ((bool,bytes)[], uint256[2][], ...).
Decoding matches eth_abi 6: addresses are lower-case hex strings, arrays and
tuples are tuples, bytesN is bytes. Use to_checksum_address when you need
EIP-55 form.
Errors
Every failure derives from RpcError:
| Class | Raised for |
|---|---|
RpcConnectionError |
unreachable node, timeout, non-JSON HTTP response |
RpcResponseError |
JSON-RPC error object; .code, .message, .data |
AbiError |
unknown type, bad value, undecodable payload |
Reverts arrive as RpcResponseError with execution reverted in the message
and the revert payload in .data. Looking up a function that the ABI does not
contain raises AttributeError, which callers can use to fall back to another
indexer.
What replaces what
| web3.py | micro-web3 |
|---|---|
Web3(Web3.HTTPProvider(uri, request_kwargs={'timeout': 4})) |
RpcNode(uri, timeout=4) |
node.is_connected() |
node.is_connected() |
web3.manager.request_blocking(method, params) |
node.request(method, params) |
contract.encode_abi(name, args=) |
contract.encode(name, args) |
contract._find_matching_fn_abi(name, *args) |
contract.function(name, args) |
contract.caller().fn(*args) |
contract.call(node, name, args) |
web3.codec.decode(types, data) |
decode_outputs(types, data) |
node.eth.get_logs(options) |
get_logs(node, ...) |
node.eth.get_block('latest')['number'] |
get_block_number(node) |
Web3.to_checksum_address |
to_checksum_address |
web3.exceptions.Web3Exception |
RpcError |
Development
uv sync --all-groups
uv run pytest
MICRON_RPC_URL=https://ethereum-rpc.publicnode.com uv run pytest tests/test_live.py
uv run ruff check .
uv run ruff format --check .
uv run pyrefly check
The ABI tests run against vectors generated with eth_abi 6 (tests/vectors.json),
so the hand-rolled codec is checked against the reference implementation
without depending on it.
Metadata
Release files for micro-web3 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| micro_web3-0.1.0.tar.gz | 15.6 kB | Without provenance | Details for micro_web3-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| micro_web3-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for micro_web3-0.1.0-py3-none-any.whl |
Total release size: 34.5 kB
Release files / micro_web3-0.1.0.tar.gz
| Download URL | micro_web3-0.1.0.tar.gz |
|---|---|
| Size | 15.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4801c3101e6d17bc557da83bffe5f2279359c43901e9109ccbc128305513c18b
|
|
BLAKE2b-256 checksum How to use checksums |
27d49819d3c1ce4195bd8e7af2c905d5c3aec64eb8465b3e004dfa5d6fede753
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / micro_web3-0.1.0-py3-none-any.whl
| Download URL | micro_web3-0.1.0-py3-none-any.whl |
|---|---|
| Size | 18.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
613cdc30c8a68aea67d57290efd937314fad553f923a4e880f402bf22f6f7894
|
|
BLAKE2b-256 checksum How to use checksums |
6d3d6e33774a3d2dfdb1aba978559afc7aa43a1af0d13987a799b0df476639cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for micro-web3 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.