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

# Policies

> Enforce spending limits, whitelists, and approval workflows

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

| 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

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

```mermaid theme={null}
flowchart TD
    A[Transaction SUBMITTED] --> B{MAX_AMOUNT}
    B -->|Pass| C{BLACKLIST_ADDRESS}
    B -->|Fail| X1[REJECTED - 1201]
    C -->|Pass| D{WHITELIST_ADDRESS}
    C -->|Fail| X2[REJECTED - 1203]
    D -->|Pass| E{DAILY_LIMIT}
    D -->|Fail| X3[REJECTED - 1202]
    E -->|Pass| F{TIME_WINDOW}
    E -->|Fail| X4[REJECTED - 1204]
    F -->|Pass| G{REQUIRE_APPROVAL}
    F -->|Fail| X5[REJECTED - 1205]
    G -->|No| H[PENDING_SIGNATURE]
    G -->|Yes| I[PENDING_AUTHORIZATION]
```

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:

1. The transaction enters `PENDING_AUTHORIZATION`.
2. A webhook event `approval.required` is sent.
3. An authorized user calls `POST /v1/transactions/{id}/approve` or `POST /v1/transactions/{id}/reject`.
4. 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

<CardGroup cols={2}>
  <Card title="Defense in depth" icon="layer-group">
    Combine multiple rule types. Use `MAX_AMOUNT` + `WHITELIST_ADDRESS` + `DAILY_LIMIT` together.
  </Card>

  <Card title="Start permissive" icon="unlock">
    Begin with high limits and tighten as you understand your transaction patterns.
  </Card>

  <Card title="Monitor violations" icon="chart-line">
    Policy violations emit webhook events. Monitor them for suspicious activity.
  </Card>

  <Card title="Separate by vault" icon="boxes-stacked">
    Apply stricter policies to hot wallets and relaxed policies to treasury vaults.
  </Card>
</CardGroup>