Skip to content

web3.py

Introduction

web3.py is a Python library for interacting with the Ethereum blockchain, officially maintained by the Ethereum Foundation. As the primary Python tool library in the Ethereum ecosystem, web3.py provides Python developers with a complete Ethereum API interface, enabling them to perform blockchain development using familiar Python syntax.

web3.py provides full-featured capabilities including connecting to Ethereum nodes, managing accounts, sending transactions, interacting with smart contracts, querying blocks and events. It is particularly well-suited for data analysis, automation scripts, backend services, quantitative trading, and similar scenarios. Python's powerful data processing capabilities (pandas, numpy) and machine learning ecosystem (scikit-learn, TensorFlow) combined with web3.py make on-chain data analysis and AI-driven blockchain application development simple and efficient.

Core Features

Provider System

web3.py supports multiple ways to connect to Ethereum nodes: - HTTPProvider: Connects to nodes via HTTP/HTTPS - WebsocketProvider: Uses WebSocket for persistent connections, supporting subscriptions and filters - IPCProvider: Connects to local nodes via IPC for faster speeds - AsyncHTTPProvider: Asynchronous HTTP Provider supporting asyncio - Auto Provider Detection: Web3.auto automatically detects available Providers

Providers can be flexibly configured with custom middleware for processing requests and responses.

Middleware System

web3.py's middleware system provides powerful extensibility: - Geth POA Middleware: Compatible with PoA consensus chains (such as BSC, Polygon) - Signing Middleware: Automatically signs transactions using local private keys - Gas Price Middleware: Automatically fetches and sets Gas prices - Nonce Middleware: Automatically manages transaction nonces - Cache Middleware: Caches certain request results to reduce network calls - Custom Middleware: Developers can write custom middleware to handle specific logic

The middleware uses an onion model, flexibly combining to implement complex functionality.

Smart Contract Interaction

web3.py provides a Pythonic contract interaction interface: - Contract Instantiation: Create contract objects via ABI and address 

contract = w3.eth.contract(address=contract_address, abi=abi)
- Calling Read-Only Functions: Use call() for view/pure functions 
balance = contract.functions.balanceOf(address).call()
- Sending Transactions: Use transact() to change contract state 
tx_hash = contract.functions.transfer(to, amount).transact({'from': account})
- Building Transactions: Use build_transaction() to build unsigned transactions 
tx = contract.functions.transfer(to, amount).build_transaction({...})
- Event Filtering: createFilter() and getLogs() for querying events 
event_filter = contract.events.Transfer.create_filter(fromBlock='latest')
logs = event_filter.get_all_entries()

ENS (Ethereum Name Service) Support

web3.py has built-in ENS support for transparently resolving ENS domain names: 

# Automatically resolves vitalik.eth to an address
balance = w3.eth.get_balance('vitalik.eth')

# Reverse resolve an address to an ENS name
ens_name = w3.ens.name('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')

ENS integration makes code more readable and improves user experience.

Account Management

web3.py provides complete account management functionality: - Create Account: Account.create() generates a new account - Recover from Private Key: Account.from_key(private_key) - Mnemonic Support: Recover from mnemonics via Account.from_mnemonic() - Transaction Signing: Account.sign_transaction() signs transactions - Message Signing: Account.sign_message() signs arbitrary messages - Signature Verification: Account.recover_message() recovers the signer - HD Wallet: Supports hierarchical deterministic wallets and derivation paths

Utility Functions

The web3.utils module provides rich utility functions: - Unit Conversion: to_wei(), from_wei() for converting between wei and ether - Address Operations: to_checksum_address(), is_address() for address validation - Hash Functions: keccak(), solidity_keccak() and other hash functions - Encoding/Decoding: encode_hex(), decode_hex() for hex conversion - ABI Encoding/Decoding: encode_abi(), decode_abi() for ABI processing - Event Signatures: event_signature_to_log_topic() for generating event topics

Key Characteristics

Python Ecosystem Integration: web3.py fully leverages Python's powerful ecosystem, seamlessly integrating with pandas, numpy, matplotlib, scikit-learn, and other libraries, making it particularly suitable for data analysis and machine learning applications.

Easy to Learn and Use: Python's concise and intuitive syntax, combined with web3.py's Pythonic API design, enables rapid onboarding with highly readable code.

Officially Maintained: As a library officially maintained by the Ethereum Foundation, web3.py holds an authoritative position and keeps up with Ethereum protocol updates promptly.

Type Hints: Complete type annotations (Type Hints) enable static type checking with tools like mypy, reducing errors.

Async Support: Supports asyncio for writing high-performance asynchronous applications that handle large volumes of concurrent requests.

Test-Friendly: Python's powerful testing frameworks (pytest, unittest) work well with web3.py for writing unit and integration tests.

Script Automation: Python is the preferred language for automation scripts, and web3.py makes Ethereum-related automation tasks straightforward.

Cross-Platform: Python's cross-platform nature allows web3.py to run seamlessly on Windows, Linux, and macOS.

Basic Usage Examples

Connecting to an Ethereum Node: 

from web3 import Web3

# Connect to a local node
w3 = Web3(Web3.HTTPProvider('http://127.0.0.1:8545'))

# Connect to Infura
w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/YOUR_PROJECT_ID'))

# Check connection
print(w3.is_connected())

Querying Account Balance: 

# Query balance (returns wei)
balance = w3.eth.get_balance('0x...')

# Convert to ether
balance_eth = w3.from_wei(balance, 'ether')
print(f"Balance: {balance_eth} ETH")

Sending a Transaction: 

from eth_account import Account

# Create or load an account
account = Account.from_key('YOUR_PRIVATE_KEY')

# Build a transaction
transaction = {
    'to': '0x...',
    'value': w3.to_wei(0.1, 'ether'),
    'gas': 21000,
    'gasPrice': w3.eth.gas_price,
    'nonce': w3.eth.get_transaction_count(account.address),
    'chainId': 1
}

# Sign the transaction
signed = account.sign_transaction(transaction)

# Send the transaction
tx_hash = w3.eth.send_raw_transaction(signed.rawTransaction)
print(f"Transaction hash: {tx_hash.hex()}")

# Wait for confirmation
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)

Interacting with Smart Contracts: 

# Contract ABI and address
abi = [...]
contract_address = '0x...'

# Create contract instance
contract = w3.eth.contract(address=contract_address, abi=abi)

# Call a read-only function
balance = contract.functions.balanceOf('0x...').call()

# Send a transaction
tx_hash = contract.functions.transfer('0x...', 1000).transact({
    'from': account.address
})

# Listen for events
event_filter = contract.events.Transfer.create_filter(fromBlock='latest')
for event in event_filter.get_new_entries():
    print(event)

Use Cases

On-Chain Data Analysis: Python's powerful data analysis capabilities (pandas, numpy, matplotlib) combined with web3.py make it convenient to extract, process, and visualize on-chain data. Researchers and analysts use web3.py for market analysis, behavioral research, and more.

Quantitative Trading: Quantitative traders use web3.py to develop trading bots for DeFi arbitrage, DEX trading, MEV strategies, and more. Python's rich quantitative libraries (such as backtrader, zipline) integrate seamlessly with web3.py.

Backend Services: Web application backends (Django, Flask, FastAPI) use web3.py to process on-chain data and provide APIs for the frontend, including listening for on-chain events, processing deposits and withdrawals, and managing user assets.

Automation Scripts: Developers write Python scripts for batch operations such as bulk transfers, token airdrops, data migration, contract deployment, and more. web3.py makes script writing simple and efficient.

Data Indexing and Crawling: Building blockchain data indexing services, crawling on-chain data and storing it in databases. Web scraping tools like Scrapy and Beautiful Soup can be used alongside web3.py.

Machine Learning and AI: Training blockchain-related machine learning models for price prediction, anomaly detection, smart contract vulnerability detection, and more. TensorFlow, PyTorch combined with web3.py enable development of AI-driven blockchain applications.

Testing and Auditing: Smart contract testing frameworks (Brownie, Ape) are built on top of web3.py. Security researchers use web3.py to analyze contract behavior and discover vulnerabilities.

Education and Research: Python is easy to learn, and web3.py is an ideal tool for learning blockchain development. Many blockchain courses and tutorials use Python and web3.py.

Comparison with Other Libraries

web3.py vs Web3.js: - web3.py uses Python, Web3.js uses JavaScript - web3.py is better suited for data analysis, backend services, and script automation - Web3.js is better suited for browser environments and DApp frontends - API design is similar, making migration relatively easy - Functionality is largely equivalent; the choice depends on language preference and use case

web3.py vs ethers.py: - ethers.py is a Python port of ethers.js but is not very mature - web3.py is officially maintained with a more complete ecosystem - web3.py has richer documentation and a more active community - Currently web3.py is the top choice for Python Ethereum development

web3.py vs Brownie/Ape: - Brownie and Ape are smart contract development frameworks built on web3.py - They provide higher-level abstractions such as contract testing, deployment scripts, console, etc. - web3.py is a lower-level library, more flexible but requires more code - For smart contract development, Brownie or Ape is recommended - For data analysis, scripting, etc., use web3.py directly

Version History

web3.py v4 (2017-2018): Early version that established the foundational architecture.

web3.py v5 (2019-2022): Major update introducing the middleware system, improved Provider, and enhanced ENS support. Became the most widely used version.

web3.py v6 (2023-present): Latest version with complete type annotations, improved async support, and performance optimizations. Supports EIP-1559, EIP-4844, and other new features. Better error handling and logging system.

New projects are recommended to use v6 to enjoy the latest features and improvements.

  • Web3.js - The JavaScript version of web3.py
  • ethers.py - A Python port of ethers.js (not very mature)
  • Brownie - A smart contract development framework built on web3.py
  • Ape - A next-generation development framework built on web3.py
  • Vyper - A Python-style smart contract language
  • pandas - Can be combined with web3.py for on-chain data analysis
  • pytest - A testing framework for web3.py contract testing
  • Official Documentation: https://web3py.readthedocs.io
  • GitHub: https://github.com/ethereum/web3.py
  • PyPI: https://pypi.org/project/web3/
  • Discord: https://discord.gg/GHryRvPB84
  • Gitter: https://gitter.im/ethereum/web3.py
  • Example Code: https://github.com/ethereum/web3.py/tree/master/examples
  • Ethereum.org: https://ethereum.org/en/developers/docs/programming-languages/python/
  • Brownie Framework: https://eth-brownie.readthedocs.io
  • Ape Framework: https://docs.apeworx.io