Policy rules (Policy Engine v2)

Policy Engine v2 adds typed policy rules. Each rule has a kind that decides what the rule does when a transaction matches it:

Your existing wallet limits are LIMIT rules. They keep working, and the policy rules API returns them as LIMIT rules.

• Only LIMIT rules let a wallet send. A wallet can only receive an asset until it has an applicable LIMIT rule for that asset. APPROVAL and TRAVEL_RULE rules never let a transaction through on their own. If no LIMIT rule applies, Wallet-as-a-Service rejects the transaction with PAL006.005.
• Rule kinds don't override each other. A transaction must pass its applicable LIMIT rules, and then meet any APPROVAL and TRAVEL_RULE requirements that apply to it.
• A blocked transaction never reaches approvers. If a LIMIT rule blocks the transaction, Wallet-as-a-Service rejects it before it creates any approval request.

For each wallet and asset, Wallet-as-a-Service sorts LIMIT rules into two groups:

• Base rules have no matchers. They apply to every outgoing transaction for the asset.
• Scoped rules have one or more matchers, such as USER or COUNTERPARTY_ID. A scoped rule applies only when the transaction matches every one of its matchers.

If at least one scoped rule applies to a transaction, the scoped rules replace the base rules for that transaction, including base rolling and lifetime limits. If no scoped rule applies, the base rules apply. The transaction must pass every rule in the selected group.

Example: A wallet has a base per-transaction limit of 10 ETH, and a scoped per-transaction limit of 50 ETH for one API credential.

• A 30 ETH transfer from that API credential passes. The scoped rule applies, so the base rule doesn't.
• A 30 ETH transfer from any other initiator fails, because the base rule applies.

1. Open the wallet and go to the Policy tab.

2. Select Add a new rule.

3. On the Direction step, select Outbound for transfers from this wallet, or Inbound for deposits into this wallet. Only Travel Rule rules support Inbound. Select Next.

   

4. On the Conditions step, select the asset, and then select the rule under Rule:

   • Limit: Select Max total value, Rolling, or Per transaction, and enter the Value limit. For Rolling, select a Duration: 1 hour, 1 day, 1 week, 2 weeks, or 1 month.
   • Approval: See Step-up approvals.
   • Travel rule: See Set up Travel Rule.

   

5. On the Scope step, select the destinations the rule applies to. You can also narrow the rule by Sign for address and Transaction types. To apply the rule to every destination, leave the selection empty.

   

6. On the Advanced step, leave All selected, or restrict the rule to one User or API credential.

7. On the Confirm step, review the rule, and then select Add policy rule.

   

If your organization has a Policy rules approval group, the rule shows Inactive | Approval pending until approvers approve it. Approvers find the request under Notifications > Approvals.

After approval, the rule shows Active | Enabled on the Policy tab.

POST /v2/vaults/{vaultId}/wallets/{walletId}/policy-rules

Your API credential needs the policy:create permission at organization, vault, or wallet scope. See Permissions.

Registry IDs look like 3::XRP. To find an asset's registry ID, list assets from the registry. For example, to find a native asset, filter by blockchain and standard:

GET /v2/registry/assets?filter.blockchain.eq=<blockchain>&filter.standard.eq=NATIVE

LIMIT, APPROVAL, and TRAVEL_RULE rules use the same amount object:

This rule caps payments to any counterparty at 10,000 of the asset in a rolling 24-hour window:

{
  "trigger": "OUTBOUND_INITIATED",
  "assetId": "3::XRP",
  "matchers": [
    { "type": "ALL_COUNTERPARTIES", "values": [] }
  ],
  "definition": {
    "kind": "LIMIT",
    "limit": {
      "amount": {
        "threshold": "10000",
        "operator": "GT",
        "aggregation": "ROLLING",
        "duration": "86400s"
      }
    }
  }
}

For APPROVAL and TRAVEL_RULE examples, see Step-up approvals and Set up Travel Rule.

The API returns the new rule. The rule goes through your organization's Policy rules approval flow, so it usually has status RULE_CREATION_APPROVAL_PENDING and active: false.

{
  "id": "0199a1c2-5d3e-7a10-9b2f-4c8e1d6f0a21",
  "vaultId": "019be892-2834-7435-be18-bc13ac4c73ce",
  "walletId": "019bec51-ab18-7284-907a-dd7747277116",
  "createdBy": "8617b5b5-dfcf-4ffc-9f46-f7cec35a88bd",
  "trigger": "OUTBOUND_INITIATED",
  "assetId": "3::XRP",
  "matchers": [
    { "type": "ALL_COUNTERPARTIES", "value": "", "values": [] }
  ],
  "status": "RULE_CREATION_APPROVAL_PENDING",
  "active": false,
  "createdAt": "2026-09-24T12:00:00Z",
  "updatedAt": "2026-09-24T12:00:00Z",
  "definition": {
    "kind": "LIMIT",
    "limit": {
      "amount": {
        "threshold": "10000",
        "operator": "GT",
        "aggregation": "ROLLING",
        "duration": "86400s"
      }
    }
  }
}

• List supports pageSize (default 50, maximum 1,000) and pageToken. You can filter by kind, trigger, assetId, status, active, createdAt, and updatedAt.
• No update operation. To change a rule, create the new rule first, and then delete the old one. This order keeps the wallet protected throughout the change.
• Wallet scope. A rule belongs to one wallet. If you request a rule ID under a different wallet, the API returns not found.

The existing /v2/vaults/{vaultId}/wallets/{walletId}/policy-rules/limits endpoints keep working, and use the keylimit:* permissions. See Manage policies.

Matchers use the same types as wallet limits. See Policy reference. In the policy rules API:

• Send each matcher as { "type": "...", "values": ["..."] }. Don't use the older single value string, which Ripple has deprecated.
• Include each matcher type at most once, with up to 100 values. A transaction must match every matcher, and any one value in each matcher.
• The API rejects the deprecated COUNTERPARTY type. Use COUNTERPARTY_ID instead.
• ALL_COUNTERPARTIES takes no values. It matches only destinations that resolve to a counterparty. To apply a rule to any destination, leave out destination matchers.
• APPROVAL rules don't support matchers.

A rule also passes through the short-lived statuses RULE_CREATED, RULE_CREATION_APPROVAL_COMPLETE, and RULE_DELETION_APPROVAL_COMPLETE. The active field is true only for RULE_ENABLED and RULE_DELETION_APPROVAL_PENDING.

The policy rules API uses the policy permission family, which is separate from keylimit. A keylimit permission doesn't give access to the policy rules API, and a policy permission doesn't give access to the /policy-rules/limits endpoints.

When you create an API credential, you can grant each permission at organization, vault, or wallet scope. In the console, owners and administrators can create and delete rules. Approvers, auditors, proposers, and support users can view rules.

For transaction rejection codes, see Policy Engine v2: transaction status changes.

• Step-up approvals
• Travel Rule
• Policy concepts
• Policy reference