Integrate Qustody with Quantum Chain

This guide walks through pointing a Qustody deployment at a Quantum Chain RPC endpoint and sending a first transaction through the platform. It assumes you already have a running Qustody API and a synced Quantum Chain node.

Architecture

Three independent components must reach each other:

Qustody API → Quantum Chain RPC (HTTP and optionally WebSocket)
Qustody API → Post-quantum signing service (HTTPS or gRPC mTLS)
Qustody API → Your webhook endpoint

Step 1. Configure the RPC connection

Set the node endpoints in Qustody’s environment:

CUSTODY_NODE_RPC_URL=http://quantum-chain-rpc.internal:8545
CUSTODY_NODE_WS_URL=ws://quantum-chain-rpc.internal:8546
CUSTODY_NODE_BACKUP_RPC_URLS=https://rpc.alt.example,https://rpc.alt2.example
CUSTODY_CHAIN_ID=20803
CUSTODY_CONFIRMATION_DEPTH=12

WebSocket is required if you want Qustody to monitor incoming deposits in real time. Verify reachability from the Qustody host:

curl -s -X POST "$CUSTODY_NODE_RPC_URL" \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_chainId","id":1,"params":[]}'
# expect "result":"0x5143"   (20803)

Step 2. Configure the signing service

Pick the signer mode that matches your operations model.

Option A — gRPC (recommended for production)

CUSTODY_SIGNER_TYPE=grpc
CUSTODY_SIGNER_BACKEND=enqlave        # or "qey"
CUSTODY_SIGNER_GRPC_TARGET=signer.internal:443
CUSTODY_SIGNER_GRPC_CLIENT_CERT=/etc/qustody/client.crt
CUSTODY_SIGNER_GRPC_CLIENT_KEY=/etc/qustody/client.key
CUSTODY_SIGNER_GRPC_CA_CERT=/etc/qustody/ca.crt
CUSTODY_SIGNER_GRPC_TIMEOUT=30s

Option B — Callback (signer pushes signatures)

CUSTODY_SIGNER_TYPE=callback

Your signer polls GET /v1/transactions?status=PENDING_SIGNATURE, fetches signing payloads, and POSTs back signatures. See External signing.

Option C — Remote HTTPS

CUSTODY_SIGNER_TYPE=remote
CUSTODY_SIGNER_ENDPOINT=https://signer.example/sign
CUSTODY_SIGNER_API_KEY=<bearer>

Restart the API and check /readyz returns 200.

Step 3. Bootstrap a tenant and admin user

# Tenant
TENANT_ID=$(curl -s -X POST "$BASE_URL/v1/tenants" \
  -H "Authorization: Bearer $BOOTSTRAP_KEY" \
  -d '{"name":"acme","display_name":"Acme Inc"}' | jq -r .id)

# Admin user
USER_ID=$(curl -s -X POST "$BASE_URL/v1/users" \
  -H "Authorization: Bearer $BOOTSTRAP_KEY" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -d '{"email":"alice@acme.example","name":"Alice"}' | jq -r .id)

# Assign admin role
curl -X POST "$BASE_URL/v1/users/$USER_ID/roles" \
  -H "Authorization: Bearer $BOOTSTRAP_KEY" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -d '{"roleId":"admin"}'

Step 4. Create a vault and wallet

# Vault
VAULT_ID=$(curl -s -X POST "$BASE_URL/v1/vaults" \
  -H "Authorization: Bearer $TENANT_KEY" \
  -d '{"name":"treasury"}' | jq -r .id)

# Wallet — register the post-quantum public key your signer will use
WALLET_ID=$(curl -s -X POST "$BASE_URL/v1/wallets" \
  -H "Authorization: Bearer $TENANT_KEY" \
  -d "{
    \"vault_id\": \"$VAULT_ID\",
    \"public_key\": \"0xa288bd50d4d48a02...\",
    \"address\": \"0xfF81E5c74E14DB5B4EE407d66B1B063C8F305c51\"
  }" | jq -r .id)

If CUSTODY_SIGNER_KEYGEN_MODE=qey, omit public_key — Qustody asks the signer to mint one and registers it automatically.

WEBHOOK_RESPONSE=$(curl -s -X POST "$BASE_URL/v1/webhooks" \
  -H "Authorization: Bearer $TENANT_KEY" \
  -d '{
    "url": "https://app.example.com/webhooks/qustody",
    "events": ["transaction.broadcast","transaction.confirmed","transaction.failed"]
  }')

echo "Secret: $(echo $WEBHOOK_RESPONSE | jq -r .secret)"

Store the secret immediately — it is shown only once. See Webhooks for HMAC verification.

Step 6. Send your first transaction

curl -X POST "$BASE_URL/v1/transactions" \
  -H "Authorization: Bearer $TENANT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"wallet_id\": \"$WALLET_ID\",
    \"to_address\": \"0x1865476914c85900110Ffc6B092436366E98Db55\",
    \"value\": \"1000000000000000000\",
    \"asset\": \"QRC\"
  }"

The transaction transitions through SUBMITTED → PENDING_AUTHORIZATION → APPROVED → PENDING_SIGNATURE → BROADCASTING → BROADCAST → CONFIRMED. Each transition fires a webhook. See Transaction lifecycle for the full state diagram.

Step 7. Verify on chain

When you receive transaction.confirmed:

TX_HASH=$(curl -s "$BASE_URL/v1/transactions/$TX_ID" \
  -H "Authorization: Bearer $TENANT_KEY" | jq -r .tx_hash)

curl -s -X POST "$CUSTODY_NODE_RPC_URL" \
  -H 'Content-Type: application/json' \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionReceipt\",\"id\":1,\"params\":[\"$TX_HASH\"]}"

The receipt’s status should be 0x1 (success).

Operational checklist

Backup RPC

Configure CUSTODY_NODE_BACKUP_RPC_URLS with at least one alternate node. The circuit breaker fails over automatically.

mTLS to signer

For gRPC mode, mutual TLS prevents stolen client tokens from leaking signing access.

Confirmation depth

Default 12 blocks (~3 minutes) is good for most flows. Raise for very high-value transfers.

Monitor metrics

Watch signer_circuit_breaker_state, node_rpc_errors_total, txpool/queued. Alert on circuit breakers open longer than 1 minute.

Integration

Operations

Tokens

Integrate Qustody with Quantum Chain

Architecture

Step 1. Configure the RPC connection

Step 2. Configure the signing service

Option A — gRPC (recommended for production)

Option B — Callback (signer pushes signatures)

Option C — Remote HTTPS

Step 3. Bootstrap a tenant and admin user

Step 4. Create a vault and wallet

Step 6. Send your first transaction

Step 7. Verify on chain

Operational checklist

Backup RPC

mTLS to signer

Confirmation depth

Monitor metrics

Where to go next

​Architecture

​Step 1. Configure the RPC connection

​Step 2. Configure the signing service

​Option A — gRPC (recommended for production)

​Option B — Callback (signer pushes signatures)

​Option C — Remote HTTPS

​Step 3. Bootstrap a tenant and admin user

​Step 4. Create a vault and wallet

​Step 5. Subscribe to webhooks

​Step 6. Send your first transaction

​Step 7. Verify on chain

​Operational checklist

Backup RPC

mTLS to signer

Confirmation depth

Monitor metrics

​Where to go next

Architecture

Step 1. Configure the RPC connection

Step 2. Configure the signing service

Option A — gRPC (recommended for production)

Option B — Callback (signer pushes signatures)

Option C — Remote HTTPS

Step 3. Bootstrap a tenant and admin user

Step 4. Create a vault and wallet

Step 5. Subscribe to webhooks

Step 6. Send your first transaction

Step 7. Verify on chain

Operational checklist

Where to go next