Custody API

Vaults & Wallets

A vault is a network-specific organizational container. A wallet is one on-chain address/Qey identity that may have explicit placements in more than one network vault. Wallets are generated with keys held in a user's EnQlave or registered from an existing EnQlave key with an ownership proof.

Vaults

POST/v1/vault/accounts

{"name": "Treasury", "networkCode": "QUANTUM_SANDBOX", "metadata": {"team": "finance"}}
// 201 →
{"id": "…", "tenantId": "…", "networkCode": "QUANTUM_SANDBOX", "name": "Treasury", "status": "ACTIVE",
 "metadata": {"team": "finance"}, "createdAt": "…", "updatedAt": "…"}

Endpoint	Purpose
GET`/v1/vault/accounts?cursor=…`	List — `{"vaults":[…],"page":{"nextCursor","hasMore"}}`
GET`/v1/vault/accounts/{vaultAccountId}`	Fetch one
PUT`/v1/vault/accounts/{vaultAccountId}`	Rename / update metadata
POST`/v1/vault/accounts/{vaultAccountId}/archive`	Archive (status → `ARCHIVED`)

Generate a wallet

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

Creates a new address whose key is generated and held inside your EnQlave signer — never by Qustody.

{"assetIds": ["20804000-0000-4000-8000-000000000001"], "label": "ops-hot"}
// 201 →
{"id": "…", "vaultId": "…", "tenantId": "…", "assetIds": ["…"], "networkLinks": [{"networkCode":"QUANTUM_SANDBOX","vaultId":"…"}],
 "address": "0x…", "publicKey": "<hex>", "label": "ops-hot",
 "status": "ACTIVE", "createdAt": "…"}

Register an external wallet (ownership proof)

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

Brings an existing address under management. Registration requires a cryptographic proof that you control the key — produced by EnQlave's Register Wallet flow, which signs a per-address challenge and calls this endpoint for you:

{
  "assetIds":  ["20804000-0000-4000-8000-000000000001"],
  "address":   "0xAb5801a7D398351b8bE11C439e05C5b3259aeC9B",  // required
  "publicKey": "<hex>",                    // produced by EnQlave
  "signature": "<hex>",                    // produced by EnQlave
  "label":     "cold-1"
}

Verification is strict: the address must match the key and the proof must verify. Valid address input is exactly 40 hexadecimal digits with optional 0x; Qustody canonicalizes it and never pads or truncates. Failures return 400 INVALID_OWNERSHIP_PROOF (code 1105).

Register from EnQlave The proof format is not publicly specified — use EnQlave's Register Wallet flow rather than constructing the request by hand. See Key enrollment.

Wallet types

Type	Behavior
`ENQLAVE_MANAGED`	Key lives in EnQlave; can sign and send
`REGISTERED`	External key registered with ownership proof; can sign and send
`WATCH_ONLY`	Monitored address; can never be a transaction source

Read endpoints

Endpoint	Purpose
GET`/v1/vault/accounts/{vaultAccountId}/wallets`	List wallets in a vault (paginated)
GET`/v1/wallets/{walletId}`	Fetch one wallet
POST`/v1/wallets/{walletId}/archive`	Archive a wallet
GET`/v1/wallets/{walletId}/balance`	Live on-chain balance

// GET /v1/wallets/{walletId}/balance →
{"walletId": "…", "assetId": "20804000-0000-4000-8000-000000000001", "balance": "42000000000000000000",
 "blockNumber": 3392847, "queriedAt": "2026-08-06T12:00:00Z"}