How wallets work

Guveno is non-custodial: you hold the keys, and Guveno holds none of the spendable secrets. It watches your addresses and prepares transactions, but it can never move funds on its own.

The short version

Guveno watches your on-chain addresses, tracks balances and transactions, and assembles unsigned transactions for you. The private keys that actually authorize spending are generated on your side and never leave your control in a form Guveno can use. Moving funds always requires a signature only you can produce.

Vaults, wallets and addresses

Everything you hold in Guveno sits in a three-level hierarchy:

• A vault is the key-management boundary: one recovery phrase, identified by its fingerprint, with a name, an optional team scope, and a list of the members who hold a sealed copy of the phrase. Who can see a vault and who can sign for it are decided here.
• A wallet is one chain and network inside a vault, derived from the vault's phrase at an account-level derivation path (for example m/44'/60'/0'/0 for Ethereum). A treasury vault might hold a Bitcoin wallet, an Ethereum wallet and an XRP wallet, all from the same phrase. A vault can hold two wallets on the same chain only at different derivation paths, so two wallets never derive the same address.
• An address is one receiving address inside a wallet, at <prefix>/<accountIndex>. Bitcoin wallets typically hold many; account-based chains often need just one.

Treasury vault (one recovery phrase, shared with the finance team)
├── Bitcoin wallet      m/84'/0'/0'/0
│   ├── bc1q...123      /0
│   ├── bc1q...456      /1
│   └── bc1q...789      /2
├── Ethereum wallet     m/44'/60'/0'/0
│   └── 0xabc...        /0
└── XRP wallet          m/44'/144'/0'/0
    └── r9Hk...         /0

Wallets inherit their vault's team scope and key access. Re-scoping a vault moves every wallet in it at once, and sharing a vault with a member gives them every wallet in it. See Vaults in the API reference.

Where keys live

• Each wallet is a standard hierarchical-deterministic (HD) wallet derived from a BIP39 recovery phrase that is generated in your environment: the dashboard in your browser, the SDK, or the CLI.
• Before that secret is ever sent anywhere, it is encrypted to your own public key. Guveno's servers only ever receive ciphertext they cannot open.

What the server stores

The server keeps wallet metadata (names, chains, networks, and the derived public addresses it needs to watch) together with an encrypted copy of each wallet secret that it cannot decrypt. Every member has a personal encryption keypair whose private half is protected by a passphrase only that person knows, so the encrypted secret can only be opened on a member's own device.

Optional key file

In encryption setup or Profile → Wallet encryption, you can also require a private file of any format, including an image (non-empty, up to 20 MiB). Setup asks you to enter the password and select the file again to prove you can unlock before saving. Both are then required to unlock and recover your wallet secrets through Guveno; neither is uploaded. Keep a separate backup of the exact original file. Copying and renaming work; editing, resizing, recompressing, or changing image metadata does not. Public or shared files add little protection.

Guveno cannot reset or recover either credential. Independently backed-up recovery phrases can still recover their wallets. This protects your access across all wallets; other members keep their own access. Changing protection preserves addresses and recovery phrases. Previously saved encrypted backups retain their original credentials, and already unlocked sessions remain usable until locked.

The dashboard saves only an encrypted envelope of your key, and your public key never changes once it is set. Setting up or changing this protection is done in the dashboard; API keys cannot do it. Never put passwords, file contents, or file hashes in an API request.

Signing a withdrawal

The spend flow is split so the secret never reaches the server:

• 1. Prepare: the server builds an unsigned transaction from the wallet's public data.
• 2. Sign: you decrypt the wallet secret locally and sign the transaction in your own environment.
• 3. Broadcast: you return the signed transaction; the server submits it on-chain and tracks it.

At no point does Guveno hold a key that can spend. That is also why API keys can prepare and broadcast but never sign (see Withdrawals).

Sharing with your team

To give a teammate access to a vault (and so to every wallet in it), an existing member re-encrypts the vault's recovery phrase to the new member's public key, on their own device. Guveno relays the resulting ciphertext but never sees the secret itself. Access is per-member and per-vault, and can be revoked (see Vaults and Permissions & scoping).

What this means for you

• Guveno, or anyone who compromised it, cannot move your funds, because there are no spendable keys to steal.
• You are responsible for your recovery phrase and passphrase. If they are lost, the funds cannot be recovered by anyone, including Guveno. Keep secure, offline backups.