> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault and wallet lifecycle

> Update, archive, and generate wallets within vaults.

The base vault and wallet endpoints (create, list, get) are documented under [API Reference → Vaults](/api-reference/endpoint/create-vault) and [Wallets](/api-reference/endpoint/register-wallet). This page covers lifecycle operations.

## Update vault

```http theme={null}
PUT /v1/vault/accounts/{vaultAccountId}
```

```bash theme={null}
curl -X PUT https://api.qustody.io/v1/vault/accounts/vault_01HXYZ \
  -H "Authorization: Bearer $QUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Treasury — Renamed", "metadata": {"team": "fin-ops"}}'
```

Updatable fields: `name`, `metadata`. The vault's wallets and policies are unaffected.

## Archive vault

```http theme={null}
POST /v1/vault/accounts/{vaultAccountId}/archive
```

Marks the vault `archived`. Archived vaults:

* Reject new transaction submissions (`1301 TX_INVALID_STATE`)
* Remain readable via `GET` for audit/compliance
* Retain their wallets in archived state — no further wallets can be created
* Cannot be unarchived (currently)

```bash theme={null}
curl -X POST https://api.qustody.io/v1/vault/accounts/vault_01HXYZ/archive \
  -H "Authorization: Bearer $QUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "team disbanded"}'
```

<Warning>
  Archive is a soft-delete. The wallet's on-chain address is still reachable; if anyone holds the private key (or signer access), they can still produce signatures off-platform. Archive Qustody-side, then ensure your signer revokes the corresponding key.
</Warning>

## Generate a wallet (Qey-side keygen only)

When `CUSTODY_SIGNER_KEYGEN_MODE=qey`, Qustody can ask the signer to generate a new keypair and register the public half automatically. The private half never leaves the signer.

```http theme={null}
POST /v1/vault/accounts/{vaultAccountId}/wallets/generate
```

```bash theme={null}
curl -X POST https://api.qustody.io/v1/vault/accounts/vault_01HXYZ/wallets/generate \
  -H "Authorization: Bearer $QUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "treasury-hot-3"}'
```

**Response 201**

```json theme={null}
{
  "id": "wal_01HXYZ...",
  "vault_id": "vault_01HXYZ...",
  "address": "0x...",
  "public_key": "0x...",
  "label": "treasury-hot-3",
  "created_at": "2026-04-27T10:15:00Z"
}
```

If `CUSTODY_SIGNER_KEYGEN_MODE=local`, this endpoint returns `1100 VALIDATION` — use [`POST /v1/vault/accounts/{id}/wallets`](/api-reference/endpoint/register-wallet) and supply the public key from your local keygen.

## Archive wallet

```http theme={null}
POST /v1/wallets/{id}/archive
```

Same semantics as vault archive: read-only after archive, in-flight transactions complete normally, no new submissions.

## Required permissions

| Endpoint                                        | Permission       |
| ----------------------------------------------- | ---------------- |
| `PUT /v1/vault/accounts/{id}`                   | `vaults:update`  |
| `POST /v1/vault/accounts/{id}/archive`          | `vaults:delete`  |
| `POST /v1/vault/accounts/{id}/wallets/generate` | `wallets:create` |
| `POST /v1/wallets/{id}/archive`                 | `wallets:delete` |