Python SDK

The official guveno package for Python mirrors the Node.js SDK feature-for-feature: the REST API, wallet key derivation, signing and encryption — with an API key for auth.

Install

pip install guveno

Requires Python 3.10+.

Using an API key

Construct the client with your API key. The base URL defaults to the production API, so you only set it for a self-hosted server.

import os
from guveno import Guveno

guveno = Guveno(api_key=os.environ["GUVENO_API_KEY"])  # gv_live_...

wallets = guveno.list_wallets()

Creating & deriving wallets

The server is the source of truth: a recovery phrase is generated locally, sealed to your encryption key, and stored on the server; the SDK re-fetches and unseals it on demand. Pass your encryption password (the one you set during dashboard onboarding) when you create or load a wallet; that's what unseals the phrase locally.

import os
from guveno import Guveno

guveno = Guveno(api_key=os.environ["GUVENO_API_KEY"])

# Generates a phrase, seals it to your encryption key, and stores it on the server.
created = guveno.create_wallet(
    name="treasury-eth",
    chain="ethereum",
    network="mainnet",
    encryption_password=os.environ["GUVENO_ENCRYPTION_PASSWORD"],
)
print(created.wallet.id, created.first_address["address"])
print("Back up:", created.mnemonic)

# The returned wallet is already loaded — derive the next address (server index).
next_addr = created.wallet.derive_address(label="deposits")

created.wallet.lock()

If key file protection is enabled, pass the original bytes when creating, importing, or loading:

from pathlib import Path
key_file = Path("/secure/original-photo.png").read_bytes()
wallet = guveno.load_wallet(10, encryption_password, key_file=key_file)
del key_file
# Use wallet, then wallet.lock() when finished.

Vaults: one phrase, many chains

create_wallet and import_wallet create a vault for the phrase, or join the vault that already holds it when you have key access. add_wallet_to_vault adds another chain wallet to an existing vault without generating anything new. Pass derivation_path_prefix to put a second wallet for the same chain in the same vault.

treasury = guveno.list_vaults()[0]   # metadata only, no password

eth = guveno.add_wallet_to_vault(
    treasury.id, "treasury-eth", "ethereum", "mainnet",
    encryption_password=os.environ["GUVENO_ENCRYPTION_PASSWORD"],
)

# A second Ethereum wallet in the same vault needs its own derivation path.
ops = guveno.add_wallet_to_vault(
    treasury.id, "ops-eth", "ethereum", "mainnet",
    derivation_path_prefix="m/44'/60'/1'/0",
    encryption_password=os.environ["GUVENO_ENCRYPTION_PASSWORD"],
)

Reading balances

Balances need only the API key, no encryption password. A loaded wallet exposes getters, or call guveno.client directly with a wallet id. Amounts are decimal strings in the asset's main unit and carry the full asset metadata.

wallet = guveno.load_wallet(wallet_id, password)

by_address = wallet.get_balances()  # per-address, per-asset
totals = wallet.get_totals()        # aggregated per asset
stats = wallet.get_stats()          # holdings, flows, top addresses

# Or via the low-level client, by wallet id:
guveno.client.get_wallet_balance_totals(wallet_id)

# Company-wide totals per asset (optionally scoped to a chain/network):
guveno.client.get_company_balance_summary(chain="ethereum", network="mainnet")

Signing locally

Withdrawals follow prepare → sign → broadcast with signing in your process; see Hot wallets. The mnemonic is unsealed locally (or supplied by a FileKeyProvider / KmsKeyProvider) and never leaves your environment — including fully offline Polkadot extrinsic building. See the package README on PyPI for the full method list and worked examples.