Policies

Transaction policies are the security rules that control what funds can leave your wallets. Each policy is a policy rule with a kind: a limit rule caps what a wallet can send, an approval rule holds large transactions for named approvers, and a Travel Rule rule requires a Travel Rule data exchange before a transfer settles. Every wallet in Ripple Custody (Wallet) is deposit-only by default. You must create at least one limit rule for an asset before you can send that asset from the wallet.

Think of policies as programmable spending limits. When you submit a transaction, the policy engine checks it against the applicable active policy rules for that wallet and asset. If the transaction exceeds any applicable limit, the system rejects it before signing. This protects your assets even if someone gains unauthorized access to your API credentials or user accounts.

Policies answer these questions:

• How much can leave in a single transaction?
• How much can leave over a period of time?
• What is the maximum that can ever leave?
• Who can initiate transactions, and to where?
• Which transactions need extra approvers, or a Travel Rule exchange?

Policies protect against:

• Unauthorized large transfers – Per-transaction limits cap individual transaction amounts
• Rapid fund drainage – Rolling-duration limits detect abnormal withdrawal patterns
• Total asset loss – Max-total-value limits set lifetime caps on withdrawals

1. Create a policy – Open your wallet's Policy tab and select Add a new rule. Select Limit, and then select the asset, limit type, and amount.

2. Approve the policy – If your organization has approval groups configured, designated approvers must authorize the policy before it takes effect.

3. Send transactions – Once the policy is active, transactions within the limit proceed normally. Transactions exceeding the limit are rejected.

See Manage policies via the console for the full walkthrough.

Each policy rule has a kind that decides what the rule does when a transaction matches it:

Wallet limits that you create with the older wallet limits endpoints are LIMIT rules, with the same IDs. See Use the wallet limits endpoints.

• 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, Ripple Custody (Wallet) 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, Ripple Custody (Wallet) rejects it before it creates any approval request.

Policies operate at the wallet level only. Each policy rule applies to a single wallet and controls transactions for a specific asset within that wallet. The exception is a TRAVEL_RULE rule with no amount condition, which can apply to every asset in the wallet.

LIMIT rules support three limit types. In the policy rules API, the limit type is the rule's aggregation. The older wallet limits endpoints call it limitType.

• Per transaction (SINGLE_TX, or PER_TX in the wallet limits endpoints) – Maximum amount for any single transaction
• Rolling (ROLLING, or ROLLING_DURATION) – Maximum cumulative amount within a sliding time window
• Max total value (TOTAL, or CONSTANT) – Lifetime cap on total withdrawals

You can combine multiple limit types on the same wallet for layered protection.

See Policy reference for complete limit type documentation, duration values, and examples.

Each policy rule must be unique within its wallet. Ripple Custody (Wallet) identifies a rule by these attributes:

The amount and the rolling window don't count, so two LIMIT rules that differ only in amount or window are duplicates. For APPROVAL rules, the amount does count, so you can create approval tiers with different thresholds.

You can create multiple rules with the same kind, limit type, and asset if they have different matchers. For example:

• Per transaction + XRP + no matchers → Applies to all XRP transactions
• Per transaction + XRP + TRANSACTION_TYPE: OfferCreate → Applies only to XRP Ledger DEX offers

Both rules can coexist because their matcher configurations differ.

Policies are immutable. You can't edit an existing policy's limit amount, duration, or matchers.

To modify a policy:

1. Create a new policy with the updated values.
2. After the new policy is active, delete the existing policy (see Manage policies via the console).

Creating the new policy first keeps the wallet protected throughout the change. See Modify a policy.

Every policy rule moves through a series of statuses from creation to deletion.

Policy rules move through five main statuses: pending approval, enabled, rejected, pending deletion, and deleted. A rule in RULE_DELETION_APPROVAL_PENDING status continues to enforce transactions until approvers approve the deletion—this prevents gaps in protection. If approvers reject the deletion, the rule returns to RULE_ENABLED. A rule that Ripple Custody (Wallet) can't process moves to RULE_ERROR.

See Policy reference for the complete status reference.

Whether a policy requires approval depends on your organization's approval group configuration.

If your organization has an approval group for Policy rules, new policy rules enter RULE_CREATION_APPROVAL_PENDING status. Designated approvers must authorize the policy before it takes effect.

The policy activates after the required number of approvers authorize it (for example, 2 of 3 approvers). If the approval threshold becomes mathematically impossible to reach (for example, too many approvers skip), the policy moves to RULE_REJECTED.

If no approval group exists for Policy rules, the policy automatically activates immediately after creation. It transitions directly to RULE_ENABLED with active: true.

See Configure approval flows to configure approval groups for your organization.

When you submit a transaction, the policy engine evaluates it against all active policies for that wallet and asset. Policy checks are one stage in the full transaction pipeline.

Policy evaluation is the first check after a user or API credential creates a transaction. The full pipeline is:

1. Policy check – The engine evaluates the transaction against every applicable LIMIT rule (see Evaluation order). If any applicable rule rejects it, Ripple Custody (Wallet) rejects the transaction immediately and never sends it to approvers.
2. Approval check – If a step-up approval rule fires, the rule's approvers must authorize the transaction. Otherwise, if your organization configures approval groups for transactions, designated approvers must authorize it. The transaction stays in POLICY_CHECK_PENDING while approvers respond. Any TRAVEL_RULE rule that applies also requires a Travel Rule exchange before the transfer settles.
3. MPC signing – The wallet's MPC quorum signs the transaction.
4. Blockchain submission – Ripple Custody (Wallet) publishes the signed transaction to the network.

See Governance and controls overview for how policies, approvals, and MPC quorums work together.

For each wallet and asset, Ripple Custody (Wallet) sorts the enforcing LIMIT rules (status RULE_ENABLED or RULE_DELETION_APPROVAL_PENDING) 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.

The engine then evaluates the transaction:

1. The engine selects which rules apply:
   • If at least one scoped rule matches the transaction, the scoped rules replace the base rules for that transaction, including base rolling and max-total-value rules.
   • If no scoped rule matches, the base rules apply.
   • If no rule applies, the engine rejects the transaction with PAL006.005.
2. For each applicable rule, the engine checks whether the transaction would exceed the limit.
3. If any applicable rule rejects the transaction, the entire transaction fails.
4. If all applicable rules pass, the transaction proceeds to the next stage (approvals or signing).

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.

Ripple Custody (Wallet) checks policy limits against the transaction amount only and excludes network fees (gas on EVM chains, transaction fees on XRP Ledger) from the limit calculation. For example, if you have a PER_TX limit of 10 ETH and send exactly 10 ETH, the policy check passes — the gas cost doesn't push the transaction over the limit.

Policy checks don't cover all outgoing fund movements. Asset sweeping bypasses policies entirely. A wallet doesn't need any policies in place before Ripple Custody (Wallet) can sweep it, and Ripple Custody (Wallet) doesn't evaluate sweep transactions against existing policies.

This means policies alone don't prevent all fund movement from a wallet. If you need to restrict sweeping, manage sweep configurations separately through Settings > Workflows. Only owners and administrators can configure sweeping operations.

See Asset sweeping for details on sweep configuration.

Matchers filter which transactions a policy applies to. A transaction must match all matchers on a policy for that policy to apply. If a policy has no matchers, it applies to all transactions for that asset.

Active matcher types include: TRANSACTION_TYPE, USER, API_CREDENTIAL, SIGN_FOR, COUNTERPARTY_ID, ALL_COUNTERPARTIES, ADDRESS_ID, WALLET_ID, and CHAIN_ID. APPROVAL rules don't support matchers. Use COUNTERPARTY_ID for counterparty destinations. The API rejects the older, deprecated COUNTERPARTY matcher.

See Policy reference for detailed matcher documentation and examples.

If you have webhooks configured for the TRANSACTION domain, you receive notifications as transactions move through the policy check stage. The relevant statuses are:

These webhooks allow you to build automated monitoring for policy enforcement — for example, alerting on rejected transactions or tracking policy check latency. Because approvals happen in this stage, POLICY_CHECK_PENDING can last for the full approval window rather than milliseconds, so set any latency alerts accordingly. See Transaction status changes.

See Webhooks overview for setup instructions and payload format.

• Ready to create a policy? Follow Manage policies via the console or Manage policy rules via the API.
• Looking up a limit type, matcher, status, permission, or error code? See Policy reference.
• Planning your policies or having issues? See Policy best practices, including its troubleshooting section.