Skip to main content

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 urllib3 with 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)

Source distribution for micro-web3 0.1.0
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)

Table of built distributions (wheels) for micro-web3 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page