Policies

​

Anatomy of a Policy

1. A signer group that governs the policy itself. Future mutations of the policy — adding rules, deleting it, updating limits — must be signed by members of this group via the endorsed-request flow. It can be the same group attached to the wallet, or a separate admin group for stricter compartmentalization. A policy’s approval_threshold and amount_threshold rules count signatures only from its own signer group, and only while that group is also attached to the wallet. If a separate admin group is not attached to the wallet, those rules see no signatures, so an allow threshold rule is never met and denies the transactions it covers.
2. One or more rules. Each rule has a rule_type, an action (allow or deny), and a definition whose shape depends on the rule type.
3. Metadata. A human-readable name and optional description.

{
  "id": "pol_2LfQm5KMnRvLFtRP7nJJug4zJEP",
  "client_id": "1NFHrqBHb3cTfLVkFSGmHZqdDPi",
  "signer_group_id": "grp_2LfPqT9VmQzKDvQP9rGHth3yHCN",
  "version": 1,
  "name": "Treasury default policy",
  "description": "Single-signature for transfers under $10k; two signatures otherwise",
  "rules": [
    { "rule_type": "approval_threshold", "action": "allow",
      "definition": { "threshold": 1 } },
    { "rule_type": "amount_threshold",   "action": "allow",
      "definition": {
        "min_amount": 10000000000,
        "threshold": 2,
        "asset": { "id": "USDC" }
      } }
  ],
  "created_at": 1640995200,
  "updated_at": 1640995200
}

​

Rule Types

​

approval_threshold

{
  "rule_type": "approval_threshold",
  "action": "allow",
  "definition": { "threshold": 2, "description": "Requires 2-of-N approval" }
}

• threshold — minimum number of signers required.
• The rule always applies to every transaction (it’s a count check, not a conditional).
• If the threshold is met → emit the rule’s action (allow or deny). If not met → emit the inverted action.

​

amount_threshold

{
  "rule_type": "amount_threshold",
  "action": "allow",
  "definition": {
    "min_amount": 10000000000,
    "threshold": 2,
    "asset": { "id": "USDC" }
  }
}

• asset — required; there is no way to omit it. id is the asset symbol — USDC, USDT, or RD — and is stored upper case. A missing asset, or an id that is empty or any, is rejected with 400. You may also pass name, a display label that plays no part in matching and can be left out entirely.
• min_amount — integer, 0 or greater, in the asset’s smallest unit. USDC has 6 decimals, so the 10000000000 above is 10,000 USDC.
• threshold: number of approvals required, 0 or greater. 0 is valid only on deny rules and makes the rule unconditional (see Hard cap). An allow rule with threshold: 0 returns 400.
• The rule applies only when the transaction moves asset and its amount is at or above min_amount. Below min_amount the rule does not apply (does not contribute allow or deny).
• The rule matches on the asset symbol, so it governs that asset on every network unless the stored asset names one. Amounts are compared in the asset’s smallest unit.
• When the rule applies: if the transaction carries at least threshold approvals → emit the rule’s action. If it carries fewer → emit the inverted action. So the example above allows a transfer of 10,000 USDC or more only when two signers approve, and denies it otherwise.

​

Hard cap

{
  "rule_type": "amount_threshold",
  "action": "deny",
  "definition": {
    "min_amount": 50000000000,
    "threshold": 0,
    "asset": { "id": "USDC" }
  }
}

• The rule denies every transaction in its asset at or above min_amount, regardless of approvals. Every approval count, zero included, meets a threshold of 0, so the rule always emits its own action. The example denies any transfer of 50,000 USDC or more.
• A transaction below min_amount is not affected, because the rule does not apply to it.
• A deny from any applied rule wins over an allow from another rule or policy (see Evaluation Order). More approvals or another policy cannot lift the cap.
• 0 is valid only on deny rules. An allow rule with threshold: 0 would allow every transaction at or above min_amount with no approval, so the API refuses it.
• A cap binds only where its policy applies, which is on the wallets the policy is attached to. On a card-enabled wallet, the customer policy applies only to transactions that its own signer group endorses, so a cap in that policy does not stop card settlement.

​

address_list

{
  "rule_type": "address_list",
  "action": "allow",
  "definition": {
    "addresses": [
      "0x742d35Cc6634C0532925a3b8D404fA40b5398Ad2",
      "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    ]
  }
}

• The rule applies only when the destination address is in the addresses list.
• For an allow-list, set action: allow and pair with a default-deny in another rule (or rely on the policy engine’s default-deny on no-applicable-policy).
• For a deny-list, set action: deny and the listed addresses are blocked outright.

​

Evaluation Order

1. Loads every policy attached to the wallet. If zero policies, return deny immediately ("No policies found for wallet").
2. For each policy, evaluates each rule in turn. A rule produces one of: applied + allow, applied + deny, or not-applicable.
3. Aggregates per policy: if any rule denies → policy = deny. Else if any rule allows → policy = allow. Else (no rule applied) → policy = not-applicable.
4. Aggregates across policies: if any policy denies → transaction = deny. Else if any policy allows → transaction = allow. Else (no applicable policy) → transaction = deny (default).

​

Lifecycle

​

Practical Examples

​

”Default permissive” — single signature, no restrictions

{
  "name": "Default single-signature policy",
  "signer_group_id": "grp_admin",
  "rules": [
    { "rule_type": "approval_threshold", "action": "allow",
      "definition": { "threshold": 1 } }
  ]
}

​

“Tiered approval by amount” — single-sig under $10k, dual-sig above

{
  "name": "Tiered approval policy",
  "signer_group_id": "grp_admin",
  "rules": [
    { "rule_type": "approval_threshold", "action": "allow",
      "definition": { "threshold": 1 } },
    { "rule_type": "amount_threshold", "action": "allow",
      "definition": {
        "min_amount": 10000000000,
        "threshold": 2,
        "asset": { "id": "USDC" }
      } }
  ]
}

​

”Sanctions deny-list” — block specific addresses outright

{
  "name": "OFAC blocklist",
  "signer_group_id": "grp_compliance",
  "rules": [
    { "rule_type": "address_list", "action": "deny",
      "definition": { "addresses": ["0xSanctionedAddress1", "0xSanctionedAddress2"] } }
  ]
}

​

Related

• Common Flows — Create a Policy — happy-path curl walk-through.
• Wallet Transaction Signing — endorsed-request flow for mutating an existing policy or attaching/detaching to a wallet.
• Wallets — architectural overview of signer groups, policies, and intents.