Vault and wallet lifecycle

The base vault and wallet endpoints (create, list, get) are documented under API Reference → Vaults and Wallets. This page covers lifecycle operations.

Update vault

PUT /v1/vault/accounts/{vaultAccountId}

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

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)

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"}'

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.

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.

POST /v1/vault/accounts/{vaultAccountId}/wallets/generate

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

{
  "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 and supply the public key from your local keygen.

Archive wallet

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`

Overview

Health

Tenants

Vaults

Wallets

Transactions

Assets

Tokens

Webhooks

Administration

Vault and wallet lifecycle

Update vault

Archive vault

Generate a wallet (Qey-side keygen only)

Archive wallet

Required permissions

​Update vault

​Archive vault

​Generate a wallet (Qey-side keygen only)

​Archive wallet

​Required permissions

Update vault

Archive vault

Generate a wallet (Qey-side keygen only)

Archive wallet

Required permissions