Policies

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

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

Rule types

Type	Description	Example
`MAX_AMOUNT`	Blocks transactions above a threshold	Max 100 QUANTUM per transfer
`DAILY_LIMIT`	Caps total daily outflow	Max 1,000 QUANTUM per day
`WHITELIST_ADDRESS`	Only allows transfers to approved addresses	Known exchange addresses
`BLACKLIST_ADDRESS`	Blocks transfers to specific addresses	Sanctioned addresses
`REQUIRE_APPROVAL`	Requires manual approval before signing	All transfers above 50 QUANTUM
`TIME_WINDOW`	Restricts transfers to specific hours	Business 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": "QUANTUM"
      }
    ]
  }'

Policy evaluation flow

All rules are evaluated. If any non-approval rule fails:

The transaction is moved to REJECTED with an error code in the 1200 range.
If the failing rule is REQUIRE_APPROVAL, the transaction enters PENDING_AUTHORIZATION instead.

Approval workflow

When a REQUIRE_APPROVAL rule matches:

The transaction enters PENDING_AUTHORIZATION.
A webhook event approval.required is sent.
An authorized user calls POST /v1/transactions/{id}/approve or POST /v1/transactions/{id}/reject.
Approved transactions transition to APPROVED and then automatically to PENDING_SIGNATURE. Rejected transactions move to REJECTED.

Error codes

Code	Meaning
`1200`	Policy violation (general)
`1201`	Amount exceeds `MAX_AMOUNT` limit
`1202`	Destination not in whitelist
`1203`	Destination is blacklisted
`1204`	Daily limit exceeded
`1205`	Transfer outside allowed time window

Best practices

Defense in depth

Combine multiple rule types. Use MAX_AMOUNT + WHITELIST_ADDRESS + 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.

Getting started

Concepts

Qustody platform

Token management

Reference

Development

How policies work

Rule types

Creating a policy

Policy evaluation flow

Approval workflow

Error codes

Best practices

Defense in depth

Start permissive

Monitor violations

Separate by vault

​How policies work

​Rule types

​Creating a policy

​Policy evaluation flow

​Approval workflow

​Error codes

​Best practices

Defense in depth

Start permissive

Monitor violations

Separate by vault

How policies work

Rule types

Creating a policy

Policy evaluation flow

Approval workflow

Error codes

Best practices