Skip to main content
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

EndpointPermission
PUT /v1/vault/accounts/{id}vaults:update
POST /v1/vault/accounts/{id}/archivevaults:delete
POST /v1/vault/accounts/{id}/wallets/generatewallets:create
POST /v1/wallets/{id}/archivewallets:delete