Transaction lifecycle

Overview

Every transfer in Qustody follows a deterministic state machine of 14 states. Understanding these states is critical for reliable integrations. Your system should handle each transition and respond to webhook events accordingly.

State machine diagram

States explained

Active states

SUBMITTED

Transaction has been accepted, validated, gas estimated, and a nonce assigned. Policy and screening evaluation happens immediately. The transaction transitions to PENDING_SIGNATURE, PENDING_AUTHORIZATION, PENDING_AML_SCREENING, or REJECTED.Webhook event: transaction.created

QUEUED

Held briefly because of an idempotency conflict (a duplicate Idempotency-Key) or a tenant rate limit. The transaction returns to SUBMITTED once a slot is available.

PENDING_AUTHORIZATION

A policy rule of type REQUIRE_APPROVAL matched. The transaction stays here until an authorized user calls POST /v1/transactions/{id}/approve or POST /v1/transactions/{id}/reject.Webhook event: approval.required

PENDING_AML_SCREENING

Compliance screening was submitted to the AML provider. The transaction is paused until the provider returns a result.Webhook event: screening.submitted

APPROVED

An approver has approved the transaction. It immediately transitions to PENDING_SIGNATURE.Webhook event: approval.decision

PENDING_SIGNATURE

The transaction is ready for external signing. Call GET /v1/transactions/{id}/signing_payload to retrieve the digest, sign it with your post-quantum private key, and submit via POST /v1/transactions/{id}/signature.Webhook event: transaction.status_changedThis is the key integration point. See the External signing guide.

SIGNED

The signature has been validated against the registered wallet’s public key. The service is assembling the raw signed transaction.

BROADCASTING

The signed transaction is being sent to the Quantum Chain network via the node pool.

CONFIRMING

The transaction has been broadcast and is awaiting on-chain confirmation. The service polls for the transaction receipt and tracks the confirmation depth.

Terminal states

COMPLETED

The transaction has reached the required confirmation depth. The chainTxHash, blockNumber, and confirmedAt fields are populated.Webhook event: transaction.completed

REJECTED

A policy denied the transaction (e.g., amount exceeds limit, destination blacklisted) or an approver explicitly rejected it. Check failureReason for details.

FAILED

The transaction failed during signing (invalid signature), broadcast (node rejected), or confirmation (reverted on-chain or dropped from mempool). Check failureReason.Webhook event: transaction.failed

CANCELLED

The transaction was cancelled by the integrator before signing and broadcast. Cancel is only valid from SUBMITTED, PENDING_AUTHORIZATION, APPROVED, or PENDING_SIGNATURE.

BLOCKED

Compliance screening flagged or blocked the transaction. The transaction never reaches the chain.Webhook event: screening.blocked

Happy path timeline

Here’s what a typical successful transfer looks like (auto-approved, no screening hold):

Step	State	Who	Duration
1	`SUBMITTED`	API caller	Instant
2	`PENDING_SIGNATURE`	Auto (policy engine)	< 100ms
3	`SIGNED`	External signer	Depends on your infra
4	`BROADCASTING`	Qustody service	< 1s
5	`CONFIRMING`	Qustody service	Network block time
6	`COMPLETED`	Qustody service	Confirmation depth reached

Polling vs. webhooks

You can track transaction status two ways:

Polling

Call GET /v1/transactions/{id} periodically. Simple but adds latency and load.

curl https://api.quantumchain.io/v1/transactions/{id} \
  -H "Authorization: Bearer $API_KEY"

Webhooks (recommended)

Filtering transactions

List transactions with filters for monitoring:

# All confirming transactions
curl "https://api.quantumchain.io/v1/transactions?status=CONFIRMING" \
  -H "Authorization: Bearer $API_KEY"

# All transactions for a specific vault
curl "https://api.quantumchain.io/v1/transactions?vaultId=vault-uuid" \
  -H "Authorization: Bearer $API_KEY"

# All transactions for a specific wallet and asset
curl "https://api.quantumchain.io/v1/transactions?walletId=wallet-uuid&assetId=asset-uuid" \
  -H "Authorization: Bearer $API_KEY"

Error handling

Always check failureReason on terminal states (FAILED, REJECTED, CANCELLED, BLOCKED). It contains a human-readable explanation of what went wrong.

Common failure reasons:

Reason	State	Resolution
`amount exceeds max`	REJECTED	Lower the amount or adjust the `MAX_AMOUNT` policy
`destination is blacklisted`	REJECTED	Remove the address from the `BLACKLIST_ADDRESS` policy
`screening blocked`	BLOCKED	Review the screening report; remediate or contact compliance
`nonce too low`	FAILED	The nonce was already used. Retry creates a new nonce
`insufficient funds`	FAILED	Fund the source wallet with enough QUANTUM for amount + gas
`signature verification failed`	FAILED	Verify you’re signing the correct payload with the correct registered key

Integration

Operations

Tokens

Transaction lifecycle

Overview

State machine diagram

States explained

Active states

Terminal states

Happy path timeline

Polling vs. webhooks

Polling

Webhooks (recommended)

Filtering transactions

Error handling

​Overview

​State machine diagram

​States explained

​Active states

​Terminal states

​Happy path timeline

​Polling vs. webhooks

Polling

Webhooks (recommended)

​Filtering transactions

​Error handling

Overview

State machine diagram

States explained

Active states

Terminal states

Happy path timeline

Polling vs. webhooks

Filtering transactions

Error handling