Transactions

Transactions are the core operation of the Custody API. Every transfer moves through a deterministic state machine from creation to on-chain confirmation.

Creating a transaction

Submit a transfer with source, destination, amount, and asset:

curl -X POST "$BASE_URL/transactions" \
  -H "Authorization: Bearer $CUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "QUANTUM",
    "source": {
      "type": "VAULT_ACCOUNT",
      "id": "va_def456"
    },
    "destination": {
      "type": "ONE_TIME_ADDRESS",
      "one_time_address": {
        "address": "0x5678...efgh"
      }
    },
    "amount": "10.0",
    "note": "Payment"
  }'

Source and destination types

Type	Description
`VAULT_ACCOUNT`	A vault account managed by the Custody API
`ONE_TIME_ADDRESS`	An external address used for a single transfer

State machine

Transactions move through a deterministic state machine of 14 states. The diagram below shows the most common path; see Transaction state machine for the full transition table.

States

State	Description	Duration
`SUBMITTED`	Accepted by the API; awaiting policy and screening evaluation	Instant
`QUEUED`	Held briefly because of an idempotency conflict or rate limit	Seconds
`PENDING_AUTHORIZATION`	Awaiting manual approval per policy	Until approved/rejected
`PENDING_AML_SCREENING`	Compliance screening in flight	Until provider responds
`APPROVED`	Authorization granted, transitioning to signing	Instant
`PENDING_SIGNATURE`	Awaiting external post-quantum signature	Until you sign
`SIGNED`	Signature received and verified	Seconds
`BROADCASTING`	Submitted to Quantum Chain nodes	Seconds
`CONFIRMING`	In a block, waiting for confirmation depth	~15–60 seconds
`COMPLETED`	Confirmed with sufficient block depth	Final
`FAILED`	Reverted, broadcast failure, or invalid signature	Final
`REJECTED`	Denied by policy or approver	Final
`CANCELLED`	Cancelled by the caller before broadcast	Final
`BLOCKED`	Compliance screening flagged or blocked the transaction	Final

Signing flow

Get the signing payload

curl "$BASE_URL/transactions/{id}/signing_payload" \
  -H "Authorization: Bearer $CUSTODY_API_KEY"

Returns a hex-encoded byte array representing the unsigned transaction digest.

Sign with your quantum-safe key

Use your external key management system to produce a post-quantum signature over the digest bytes.

Submit the signature

curl -X POST "$BASE_URL/transactions/{id}/signature" \
  -H "Authorization: Bearer $CUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "<base64-signature>",
    "signer_public_key": "<base64-public-key>"
  }'

The API verifies the signature against the registered wallet’s public key before accepting it.

Approval and rejection

If a policy requires manual approval, the transaction enters a PENDING_AUTHORIZATION state.

# Approve
curl -X POST "$BASE_URL/transactions/{id}/approve" \
  -H "Authorization: Bearer $CUSTODY_API_KEY"

# Reject
curl -X POST "$BASE_URL/transactions/{id}/reject" \
  -H "Authorization: Bearer $CUSTODY_API_KEY"

Cancellation

Cancel a transaction before it has been broadcast:

curl -X POST "$BASE_URL/transactions/{id}/cancel" \
  -H "Authorization: Bearer $CUSTODY_API_KEY"

You can only cancel transactions in SUBMITTED, PENDING_AUTHORIZATION, APPROVED, or PENDING_SIGNATURE. Once a transaction is SIGNED, BROADCASTING, or CONFIRMING, it cannot be cancelled.

Idempotency

Include an Idempotency-Key header to safely retry requests without creating duplicate transactions:

curl -X POST "$BASE_URL/transactions" \
  -H "Authorization: Bearer $CUSTODY_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Idempotency keys expire after 24 hours.

Listing and filtering

# List all transactions
curl "$BASE_URL/transactions" \
  -H "Authorization: Bearer $CUSTODY_API_KEY"

# Get a specific transaction
curl "$BASE_URL/transactions/{id}" \
  -H "Authorization: Bearer $CUSTODY_API_KEY"

Getting started

Concepts

Qustody platform

Token management

Reference

Development

Creating a transaction

Source and destination types

State machine

States

Signing flow

Approval and rejection

Cancellation

Idempotency

Listing and filtering

​Creating a transaction

​Source and destination types

​State machine

​States

​Signing flow

​Approval and rejection

​Cancellation

​Idempotency

​Listing and filtering

Creating a transaction

Source and destination types

State machine

States

Signing flow

Approval and rejection

Cancellation

Idempotency

Listing and filtering