Custody API

Signing & EnQlave

Qustody never holds signing keys and never signs on your behalf. When a transaction clears policy and screening it parks in PENDING_SIGNATURE and waits for approval in EnQlave — the Qustody signer that generates, stores, and uses your keys entirely on your side.

Signing is EnQlave-only The signing protocol between EnQlave and Qustody is deliberately not publicly specified, and signature submissions are only accepted from keys enrolled through EnQlave. You cannot build a third-party signer against the API — these docs cover the integration surface (REST + webhooks); the signing surface is EnQlave.

How signing works

sequenceDiagram
    autonumber
    participant A as Your app
    participant Q as Qustody API
    participant E as EnQlave (your side)
    participant C as Quantum Chain
    A->>Q: POST /v1/transactions
    Note over Q: policy · screening · quotas
    Q-->>A: status PENDING_SIGNATURE
    E->>Q: detects pending transaction
    Note over E: operator reviews and approves — keys never leave EnQlave
    E->>Q: signed approval
    Note over Q: verify against the wallet's enrolled key, fail-closed re-check
    Q->>C: broadcast
    Q-->>A: webhooks: SIGNED → BROADCASTING → CONFIRMING → COMPLETED

Your system creates the transaction over the REST API (see Transactions).
Each team member connects an independent EnQlave to their Qustody user. A signing queue includes only transactions for wallets that user has proved they hold.
On approval, EnQlave signs locally and submits to Qustody. Submissions are verified against the wallet's enrolled key — anything else is rejected with SIGNATURE_MISMATCH (1302).
Qustody independently rebuilds the transaction from the stored intent and re-verifies the result before broadcast. Any mismatch fails closed — a tampered record cannot redirect funds.

Signing requests expire A pending signature must be produced within 10 minutes. After that the transaction fails with signing request expired — create a new transaction rather than retrying the old one. EnQlave surfaces the countdown.

What your integration sees

From the API side, signing is entirely observable and entirely hands-off:

GET /v1/transactions/{id} — status moves PENDING_SIGNATURE → SIGNED → BROADCASTING → CONFIRMING → COMPLETED.
Webhooks — transaction.status_changed fires on every transition; no polling needed.
Signing in a state other than PENDING_SIGNATURE is impossible — attempts surface as 409 INVALID_TX_STATE (1301).

Key enrollment

Every wallet's key is enrolled through EnQlave before it can sign:

Generate — …/wallets/generate creates a wallet whose key material is created and kept in EnQlave.
Register — EnQlave's Register Wallet flow proves ownership of an existing address and enrolls it (see Vaults & Wallets).

Only the enrolled key can authorize transactions for its wallet. WATCH_ONLY wallets have no enrolled key and can never be a source.

Qustody records proof-backed wallet holders. Signing requires the exact wallet Qey plus an active user, EnQlave identity, connection, and user-mapped credential; tenant administrator access alone does not grant signing authority.

Programmatic & unattended signing

Today EnQlave is a desktop app with a human in the loop — the right default for treasury operations. For automated workflows, the roadmap is:

Option	Status
EnQlave CLI / SDK — drive EnQlave programmatically next to your Qustody API integration (headless approval under your own policy)	In development
EnQlave Enterprise (hosted) — a managed EnQlave signer operated for your tenant	Planned

If you need unattended signing now, talk to us — early access is arranged per tenant.