Skip to main content
The policy engine evaluates configurable rules before any transaction is broadcast to the Quantum Chain network. Policies provide compliance controls, spending protection, and operational guardrails.

​
How policies work

  1. You create policy rules on a vault account or tenant
  2. When a transaction is created, the policy engine evaluates all applicable rules
  3. If any rule is violated, the transaction is blocked or requires approval
  4. Only transactions that pass all policies proceed to signing

​
Rule types

TypeDescriptionExample
MAX_AMOUNTBlocks transactions above a thresholdMax 100 QC per transfer
DAILY_LIMITCaps total daily outflowMax 1,000 QC per day
WHITELISTOnly allows transfers to approved addressesKnown exchange addresses
BLACKLISTBlocks transfers to specific addressesSanctioned addresses
REQUIRE_APPROVALRequires manual approval before signingAll transfers above 50 QC
TIME_WINDOWRestricts transfers to specific hoursBusiness hours only (UTC)

​
Creating a policy

curl -X POST "$BASE_URL/policies" \
  -H "Authorization: Bearer $CUSTODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Max transfer limit",
    "vault_account_id": "va_def456",
    "rules": [
      {
        "type": "MAX_AMOUNT",
        "amount": "100.0",
        "asset_id": "QC_NATIVE"
      }
    ]
  }'

​
Policy evaluation flow

All rules are evaluated. If any rule fails:
  • The transaction is blocked with an error code in the 1200 range
  • If the failing rule is REQUIRE_APPROVAL, the transaction enters PENDING_APPROVAL instead

​
Approval workflow

When a REQUIRE_APPROVAL policy triggers:
  1. The transaction enters PENDING_APPROVAL status
  2. A webhook event transaction.approval_required is sent
  3. An authorized user calls POST /v1/transactions/{id}/approve or POST /v1/transactions/{id}/reject
  4. Approved transactions proceed to PENDING_SIGNATURE; rejected transactions move to REJECTED

​
Error codes

CodeMeaning
1200Policy violation — general
1201Amount exceeds MAX_AMOUNT limit
1202Destination not in whitelist
1203Destination is blacklisted
1204Daily limit exceeded
1205Transfer outside allowed time window

​
Best practices

Defense in depth

Combine multiple rule types — use MAX_AMOUNT AND WHITELIST AND DAILY_LIMIT together.

Start permissive

Begin with high limits and tighten as you understand your transaction patterns.

Monitor violations

Policy violations emit webhook events — monitor them for suspicious activity.

Separate by vault

Apply stricter policies to hot wallets and relaxed policies to treasury vaults.