Vaults

A vault is one recovery phrase and everything derived from it: its chain wallets, its team scope, and the members who hold a sealed copy of the phrase.

The vault object

{
  "id": "3e2b7c8a-0f65-4f7f-9a83-2e33cbe0d1a4",
  "name": "Treasury",
  "fingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "status": "active",          // active | archived
  "access": "full",            // full = the caller holds a sealed copy of the phrase; watch_only otherwise
  "walletCount": 3,            // active wallets in the vault
  "visibleWalletCount": 2,     // of those, the ones the caller can see
  "archivedAt": null,
  "createdAt": "2026-09-01T09:12:44.000Z",
  "updatedAt": "2026-09-01T09:12:44.000Z"
}

fingerprint is a hash of the recovery phrase, so two systems can agree they mean the same seed without exchanging it. access is computed per caller: an API key reads full when the member who created it holds the vault; members and viewers always read watch_only because they can never hold a vault's key. A vault decides who can sign, not who can see: its wallets can belong to different teams, and a vault is visible to you when it holds a wallet you can reach, or when you hold its key.

walletCount counts every active wallet in the vault; visibleWalletCount counts the ones the caller can see (an API key: the ones it was granted wallets:read on). Holding the key signs only the visible ones, so full access with a visibleWalletCount of 0 signs nothing through Guveno.

List vaults

Returns the vaults the caller can see. An API key sees the vaults of the wallets it was granted wallets:read on. Query param: status (active, the default; archived; or all).

curl https://api.guveno.com/v1/vaults   -H "Authorization: Bearer gv_live_your_key_here"

{ "items": [ { "id": "3e2b7c8a-...", "name": "Treasury", "walletCount": 3, ... } ] }

To list the wallets inside one vault, filter the wallet list: GET /wallets?vaultId=….

Get a vault

curl https://api.guveno.com/v1/vaults/3e2b7c8a-0f65-4f7f-9a83-2e33cbe0d1a4   -H "Authorization: Bearer gv_live_your_key_here"

Create a vault

Registers a new recovery phrase as an empty vault. You send the phrase's fingerprint and your own sealed copy of it (encryptedSecretJson, encrypted to your public key on your device); Guveno never receives the phrase itself. Wallets are then added with POST /wallets and vaultId. Most integrations skip this step: creating a wallet with a fingerprint creates its vault on the fly. Requires the wallets:create action.

curl -X POST https://api.guveno.com/v1/vaults   -H "Authorization: Bearer gv_live_your_key_here"   -H "Content-Type: application/json"   -d '{
    "name": "Treasury",
    "keyFingerprint": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "encryptedSecretJson": { "version": 2, "type": "x25519-sealed-box", "ciphertext": "..." }
  }'

A fingerprint already registered in your company is rejected with 409: a phrase backs exactly one vault. Vault names are unique per company.

Rename, archive

Vaults are renamed and archived in the dashboard, not through the API. Who can see a vault's wallets is set per wallet (PATCH /wallets/:id with teamIds), not on the vault — custody and access are separate controls. A vault can't be archived while it still has active wallets or any address holding a balance, and archiving keeps the key-access records so the history stays auditable.

Who holds the key

Who holds a copy of a vault's phrase is managed in the dashboard, under the vault's key holders page, and has no API. A copy is the phrase itself: it is produced by decrypting the sharer's own copy in their browser and re-encrypting it to the recipient, so only someone who already holds the key can pass it on. It is then an offer — the recipient accepts it before it becomes theirs, so nobody is made responsible for a vault without saying yes. Every step re-authenticates and emails the people who hold that key. Read Roles and teams for who may hold one.