python-sdk/pkg/hanzo-web3/README.md

Hanzo Web3 SDK

Enterprise blockchain infrastructure SDK for Python. Multi-chain RPC, Token APIs, NFT APIs, Smart Wallets, Webhooks, and more.

Installation

pip install hanzo-web3

# Or with uv
uv add hanzo-web3

Quick Start

from hanzo_web3 import Client

# Initialize client
client = Client(api_key="hz_live_...")

# Get latest block number
block = client.rpc.eth_block_number(chain="ethereum")
print(f"Latest block: {block}")

# Get token balances
balances = client.tokens.get_balances("0x...", chain="polygon")
for token in balances:
    print(f"{token['symbol']}: {token['balance_formatted']}")

# Get NFTs owned
nfts = client.nfts.get_owned("0x...", chain="ethereum")
for nft in nfts:
    print(f"{nft['name']} #{nft['token_id']}")

Async Client

import asyncio
from hanzo_web3 import AsyncClient

async def main():
    async with AsyncClient(api_key="hz_live_...") as client:
        # Parallel requests
        eth_block, polygon_block = await asyncio.gather(
            client.rpc.eth_block_number(chain="ethereum"),
            client.rpc.eth_block_number(chain="polygon"),
        )
        print(f"ETH: {eth_block}, Polygon: {polygon_block}")

asyncio.run(main())

Features

RPC API

Direct JSON-RPC access to 100+ chains:

# Any RPC method
result = client.rpc.call("eth_getBalance", ["0x...", "latest"], chain="ethereum")

# Convenience methods
balance = client.rpc.eth_get_balance("0x...", chain="ethereum")

Token API

ERC-20 token data:

# Get all token balances
balances = client.tokens.get_balances("0x...", chain="ethereum")

# Get token metadata
metadata = client.tokens.get_metadata("0xA0b8...", chain="ethereum")

NFT API

NFT collections and metadata:

# Get owned NFTs
nfts = client.nfts.get_owned("0x...", chain="ethereum")

# Get NFT metadata
metadata = client.nfts.get_metadata("0x...", "1234", chain="ethereum")

Smart Wallets (ERC-4337)

Account abstraction:

# Create smart wallet
wallet = client.wallets.create(owner="0x...", chain="base")
print(f"Smart wallet: {wallet['address']}")

# Get wallet details
info = client.wallets.get(wallet['address'], chain="base")

Webhooks

Real-time event notifications:

# Create webhook
webhook = client.webhooks.create(
    url="https://your-server.com/webhook",
    event_type="ADDRESS_ACTIVITY",
    chain="ethereum",
    filters={"addresses": ["0x..."]}
)

# List webhooks
webhooks = client.webhooks.list()

# Delete webhook
client.webhooks.delete(webhook["id"])

Supported Chains

Chain	Networks
Ethereum	mainnet, sepolia, holesky
Polygon	mainnet, amoy
Arbitrum	mainnet, sepolia
Optimism	mainnet, sepolia
Base	mainnet, sepolia
Avalanche	mainnet, fuji
BNB Chain	mainnet, testnet
Lux	mainnet, testnet
Solana	mainnet, devnet
+ 90 more	...

Environment Variables

# API Key (alternative to passing in code)
export HANZO_WEB3_API_KEY=hz_live_...

# Custom API URL (for white-label deployments)
export HANZO_WEB3_BASE_URL=https://api.lux.cloud

Error Handling

from hanzo_web3 import Client
from hanzo_web3.exceptions import (
    AuthenticationError,
    RateLimitError,
    ChainNotSupportedError,
)

try:
    client = Client(api_key="invalid")
    client.rpc.eth_block_number()
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ChainNotSupportedError as e:
    print(f"Chain {e.chain} not supported")

Links

• Documentation
• Dashboard
• API Reference
• GitHub

License

Apache 2.0 - See LICENSE for details.