Every transaction submitted to Qustody flows through a deterministic state machine with 14 states. The machine is enforced server-side: only legal transitions are accepted, and every transition emits a webhook event you can subscribe to.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.
State diagram
All 14 states
SUBMITTED
Accepted by the API; awaiting policy and screening evaluation.
QUEUED
Held briefly because of an idempotency conflict or rate limit.
PENDING_AUTHORIZATION
A policy rule of type
REQUIRE_APPROVAL matched. A human approver must decide.PENDING_AML_SCREENING
Compliance screening is in flight; the transaction is paused.
APPROVED
Authorization granted; about to enter signing.
PENDING_SIGNATURE
Awaiting an external post-quantum signature over the signing payload.
SIGNED
Signature received and verified against the registered wallet’s public key.
BROADCASTING
Raw transaction assembled and being broadcast to Quantum Chain nodes.
CONFIRMING
Included on-chain; counting confirmations to the configured depth.
COMPLETED
Confirmed with sufficient depth. Terminal.
FAILED
Permanent failure during signing, broadcast, or confirmation. Terminal.
REJECTED
Denied by the policy engine or by an approver. Terminal.
CANCELLED
Cancelled by the caller before broadcast. Terminal.
BLOCKED
Compliance screening flagged or blocked the transaction. Terminal.
Active vs terminal
- Active (9):
SUBMITTED,QUEUED,PENDING_AUTHORIZATION,PENDING_AML_SCREENING,APPROVED,PENDING_SIGNATURE,SIGNED,BROADCASTING,CONFIRMING. - Terminal (5):
COMPLETED,FAILED,REJECTED,CANCELLED,BLOCKED. Once a transaction reaches a terminal state it never changes again.
Transition table
| From | To | Trigger | Actor |
|---|---|---|---|
| — | SUBMITTED | POST /v1/transactions | API caller |
SUBMITTED | QUEUED | Idempotency conflict or rate limit | System |
QUEUED | SUBMITTED | Slot available | System |
SUBMITTED | REJECTED | Policy engine denies (e.g. BLACKLIST_ADDRESS, MAX_AMOUNT) | System |
SUBMITTED | PENDING_AUTHORIZATION | Policy rule of type REQUIRE_APPROVAL matched | System |
SUBMITTED | PENDING_AML_SCREENING | AML provider screening required | System |
SUBMITTED | PENDING_SIGNATURE | Policy auto-approved and no screening required | System |
PENDING_AUTHORIZATION | APPROVED | POST /v1/transactions/{id}/approve | Approver |
PENDING_AUTHORIZATION | REJECTED | POST /v1/transactions/{id}/reject | Approver |
PENDING_AUTHORIZATION | CANCELLED | POST /v1/transactions/{id}/cancel | API caller |
APPROVED | PENDING_SIGNATURE | Automatic after authorization | System |
APPROVED | CANCELLED | POST /v1/transactions/{id}/cancel | API caller |
PENDING_AML_SCREENING | PENDING_SIGNATURE | Screening cleared | System |
PENDING_AML_SCREENING | BLOCKED | Screening flagged or blocked | System |
PENDING_SIGNATURE | SIGNED | POST /v1/transactions/{id}/signature with valid post-quantum signature | External signer |
PENDING_SIGNATURE | FAILED | Signature verification failed | System |
PENDING_SIGNATURE | CANCELLED | POST /v1/transactions/{id}/cancel | API caller |
SIGNED | BROADCASTING | Raw transaction assembled | System |
SIGNED | FAILED | Assembly error | System |
BROADCASTING | CONFIRMING | Node accepted the transaction | System |
BROADCASTING | FAILED | Node rejected (bad nonce, insufficient gas, etc.) | System |
CONFIRMING | COMPLETED | Confirmation depth reached | System |
CONFIRMING | FAILED | Reverted or dropped from mempool | System |
POST /v1/transactions/{id}/cancel is only valid from SUBMITTED,
PENDING_AUTHORIZATION, APPROVED, or PENDING_SIGNATURE. Once a transaction
is SIGNED, BROADCASTING, or CONFIRMING, it cannot be cancelled.Webhook events per state
| State entered | Webhook event |
|---|---|
SUBMITTED | transaction.created |
QUEUED | transaction.status_changed |
PENDING_AUTHORIZATION | approval.required + transaction.status_changed |
PENDING_AML_SCREENING | screening.submitted + transaction.status_changed |
APPROVED | approval.decision + transaction.status_changed |
REJECTED | approval.decision (if from approver) + transaction.status_changed |
PENDING_SIGNATURE | transaction.status_changed |
SIGNED | transaction.status_changed |
BROADCASTING | transaction.status_changed |
CONFIRMING | transaction.status_changed |
COMPLETED | transaction.completed |
FAILED | transaction.failed |
CANCELLED | transaction.status_changed |
BLOCKED | screening.blocked + transaction.status_changed |