Skip to main content
The WAX Python SDK is distributed as hiveio-wax on PyPI. It provides native performance through Cython bindings to the C++ Hive protocol implementation.

​
Requirements

Before installing, ensure you have:
  • Python 3.12 or higher - The SDK requires modern Python features
  • pip - Python package installer (included with Python)
  • Operating system - Linux, macOS, or Windows with WSL
The SDK includes compiled native extensions. Pre-built wheels are available for common platforms. If a wheel isn’t available for your platform, pip will attempt to build from source (requires a C++ compiler).

​
Install from PyPI

Install the latest stable version: 
pip install hiveio-wax
Install a specific version: 
pip install hiveio-wax==1.2.3

​
Install with Beekeeper

For transaction signing with wallet integration, also install the Beekeeper Python client: 
pip install hiveio-wax beekeepy
This enables secure key management through the Beekeeper wallet system.

​
Verify installation

Confirm the SDK is installed correctly: 
import wax

print(f"WAX version: {wax.__version__}")

# Test basic functionality
foundation = wax.create_wax_foundation()
print(f"Chain ID: {foundation.chain_id}")
print(f"Address prefix: {foundation.address_prefix}")
Expected output: 
WAX version: 1.2.3
Chain ID: beeab0de00000000000000000000000000000000000000000000000000000000
Address prefix: STM

​
Development installation

For contributing or testing unreleased features, install from source:

​
Clone the repository

git clone https://gitlab.syncad.com/hive/wax.git
cd wax
git submodule update --init --recursive

​
Install Poetry

The project uses Poetry for dependency management: 
curl -sSL https://install.python-poetry.org | python3 -

​
Build and install

From the repository root: 
./python/wax/scripts/install_wax.sh
This script:
  1. Sets up a Python virtual environment
  2. Installs build dependencies
  3. Compiles the Cython extensions
  4. Installs the package in development mode

​
Run tests

./python/tests/wax/run_tests.sh

​
Configuration

The SDK supports configuration through options objects.

​
Offline mode (wax foundation)

from wax import create_wax_foundation, WaxOptions

# Default configuration (mainnet)
wax = create_wax_foundation()

# Custom chain ID (e.g., testnet)
options = WaxOptions(
    chain_id="18dcf0a285365fc58b71f18b3d3fec954aa0c141c44e4e5cb4cf777b9eab274e"
)
wax = create_wax_foundation(options)

​
Online mode (hive chain)

from wax import create_hive_chain, WaxChainOptions

# Default configuration (mainnet via hive.blog)
wax = create_hive_chain()

# Custom endpoint
options = WaxChainOptions(
    endpoint_url="https://api.deathwing.me"
)
wax = create_hive_chain(options)

# Custom chain and endpoint (e.g., testnet)
options = WaxChainOptions(
    chain_id="18dcf0a285365fc58b71f18b3d3fec954aa0c141c44e4e5cb4cf777b9eab274e",
    endpoint_url="https://testnet.openhive.network"
)
wax = create_hive_chain(options)

​
Virtual environments

It’s recommended to use virtual environments for project isolation.

​
Using venv

# Create virtual environment
python -m venv .venv

# Activate (Linux/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install SDK
pip install hiveio-wax

​
Using Poetry

# Create project
poetry new my-hive-app
cd my-hive-app

# Add dependency
poetry add hiveio-wax

# Activate virtual environment
poetry shell

​
Dependencies

The SDK automatically installs required dependencies:
  • protobuf - Protocol Buffer message handling
  • httpx - Async HTTP client for API calls (with HTTP/2 support)
  • python-dateutil - Date/time parsing and manipulation
  • typing-extensions - Extended type hints
  • hiveio-api - Generated API client definitions

​
Optional dependencies

  • beekeepy - Beekeeper wallet integration for transaction signing
  • pytest - For running tests
  • mypy - For type checking
  • ruff - For linting

​
Troubleshooting

​
Import errors

If you encounter import errors: 
ImportError: cannot import name 'create_hive_chain' from 'wax'
Ensure you’re importing from the correct package: 
# Correct
from wax import create_hive_chain

# Incorrect - different package
from wax_chain import create_hive_chain

​
Build failures

If building from source fails:
  1. Ensure you have a C++ compiler:
    • Linux: sudo apt-get install build-essential
    • macOS: Install Xcode Command Line Tools
    • Windows: Use WSL or install Visual Studio Build Tools
  2. Ensure submodules are initialized: 
    git submodule update --init --recursive

​
Version conflicts

If you experience dependency version conflicts: 
# Clear pip cache
pip cache purge

# Reinstall
pip install --no-cache-dir --force-reinstall hiveio-wax

​
Next steps

Offline operations

Learn about create_wax_foundation for offline mode

Online operations

Learn about create_hive_chain for full blockchain access

Build docs developers (and LLMs) love

Get started for freeTalk to us