> Guveno API reference v1.10.0, last updated October 17, 2026. The whole reference is at https://www.guveno.com/llms-full.txt.

## 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.

[guvenoon PyPI→](https://pypi.org/project/guveno/)

### Install

```
pip install guveno
```

Requires Python 3.10+.

> The Python and Node.js SDKs are wire- and key-compatible: the same recovery phrase derives the same addresses, and secrets sealed by one SDK open in the other — mix them freely across services.

### 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](https://pypi.org/project/guveno/) for the full method list and worked examples.

Source: https://www.guveno.com/docs/python-sdk/