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

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

**GET** `/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

**GET** `/vaults/:id`

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

### Create a vault

**POST** `/vaults`

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.

Source: https://www.guveno.com/docs/vaults/