> ## 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.

# Integrate Qustody with Quantum Chain

> Wire the Qustody custody platform to a Quantum Chain RPC node end-to-end.

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](/qustody/deployment) and a synced [Quantum Chain node](/quantum-chain/quickstart-node).

## Architecture

```mermaid theme={null}
flowchart LR
    App[Your application] -->|HTTPS| API[Qustody API]
    API -->|JSON-RPC| Node[Quantum Chain RPC]
    API -->|gRPC mTLS| Signer[Post-quantum signing service]
    API -.->|Webhooks HMAC| App
    Node -->|Block import| QVM[(Quantum Chain ledger)]
```

Three independent components must reach each other:

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

## Step 1. Configure the RPC connection

Set the node endpoints in Qustody's environment:

```bash theme={null}
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:

```bash theme={null}
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)

```bash theme={null}
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)

```bash theme={null}
CUSTODY_SIGNER_TYPE=callback
```

Your signer polls `GET /v1/transactions?status=PENDING_SIGNATURE`, fetches signing payloads, and POSTs back signatures. See [External signing](/guides/external-signing).

### Option C — Remote HTTPS

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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.

## Step 5. Subscribe to webhooks

```bash theme={null}
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](/concepts/webhooks) for HMAC verification.

## Step 6. Send your first transaction

```bash theme={null}
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](/guides/transaction-lifecycle) for the full state diagram.

## Step 7. Verify on chain

When you receive `transaction.confirmed`:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Backup RPC" icon="server">
    Configure `CUSTODY_NODE_BACKUP_RPC_URLS` with at least one alternate node. The circuit breaker fails over automatically.
  </Card>

  <Card title="mTLS to signer" icon="lock">
    For gRPC mode, mutual TLS prevents stolen client tokens from leaking signing access.
  </Card>

  <Card title="Confirmation depth" icon="cube">
    Default 12 blocks (\~3 minutes) is good for most flows. Raise for very high-value transfers.
  </Card>

  <Card title="Monitor metrics" icon="chart-line">
    Watch `signer_circuit_breaker_state`, `node_rpc_errors_total`, `txpool/queued`. Alert on circuit breakers open longer than 1 minute.
  </Card>
</CardGroup>

## Where to go next

* [Configure a development network](/guides/configure-a-development-network)
* [Move from local signing to custody](/guides/move-from-local-signing-to-custody)
* [Transaction lifecycle](/guides/transaction-lifecycle)