Step-up approvals

Step-up approvals require named approvers for large transactions. You set an amount for a wallet and asset. Transactions of that amount or less use the wallet's usual approval group. Transactions of more than that amount wait for the approvers you name on the rule.

For example: "Transfers of up to 50,000 XRP use our standard approvers. Anything more than 50,000 XRP needs 2 of 3 finance approvers."

A step-up approval is an APPROVAL policy rule.

• Scope. A step-up approval rule applies to outgoing transactions of one asset from one wallet.
• Threshold. The rule fires when a single transaction's amount is greater than the threshold. A transaction for exactly the threshold amount doesn't fire the rule.
• Tiers. You can create several rules with different thresholds for the same wallet and asset. When more than one rule fires, the rule with the highest threshold applies.
• Replaces the default approval group. When a rule fires, its approvers and required count replace the wallet or organization transaction approval group for that transaction. The rule doesn't add to the approval group. When no rule fires, the usual approval group applies. See Wallet-level transaction approvals.
• Doesn't let a wallet send on its own. The wallet still needs a LIMIT rule for the asset. Ripple Custody (Wallet) checks limits first. If a transaction exceeds a limit, Ripple Custody (Wallet) rejects it without asking any approvers.

A treasury wallet has a default approval group, a 500,000 XRP per-transaction limit, and two step-up approval rules:

Required role: Owner or Administrator.

1. Open the wallet and go to the Policy tab.
2. Select Add a new rule.
3. On the Direction step, select Outbound, and then select Next.
4. On the Rule step, select Approval, and then select Next.
5. On the Conditions step, select the asset, and then enter the amount in Require approval when the amount is over.
6. Under Approvers, select the approvers, and set Threshold to the number of approvals you require.
7. Under Approval timeout, select 5, 15, or 30 minutes, or 1, 2, 4, 12, or 24 hours. The default is 1 hour. Select Next.
8. On the Confirm step, review the rule, and then select Add policy rule. Approval rules skip the Scope and Advanced steps.

If your organization has a Policy rules approval group, the new rule takes effect only after those approvers approve it.

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

{
  "trigger": "OUTBOUND_INITIATED",
  "assetId": "3::XRP",
  "definition": {
    "kind": "APPROVAL",
    "approval": {
      "amount": {
        "threshold": "50000",
        "operator": "GT",
        "aggregation": "SINGLE_TX"
      },
      "users": {
        "userIds": [
          "8617b5b5-dfcf-4ffc-9f46-f7cec35a88bd",
          "2c0e7f3a-91d4-4b6e-a5c8-3f1d9e0b7a42",
          "b5d9a1e6-4c2f-4e8b-9a73-0d6c1f8e2b95"
        ]
      },
      "requiredApprovals": 2,
      "timeoutDuration": "3600s"
    }
  }
}

The API returns the rule with status RULE_CREATION_APPROVAL_PENDING. The rule then follows the policy rule lifecycle.

1. The transaction passes its limit checks.
2. If a step-up approval rule fires, Ripple Custody (Wallet) creates an approval request for the rule's approvers. The request keeps the approvers, required count, and timeout that the rule has when Ripple Custody (Wallet) creates the request. If you delete or replace the rule later, pending requests don't change.
3. The transaction waits in POLICY_CHECK_PENDING while approvers respond.
4. The transaction then continues or stops:
   • Approved: The transaction moves to POLICY_CHECK_PASSED and continues to signing.
   • Rejected: The transaction moves to REJECTED with reason PAL006.044 (approval requirement not met).
   • Timed out: The transaction moves to REJECTED with reason PAL006.045 (approval expired).
   • Invalid rule: If the rule's approval requirement is invalid, Ripple Custody (Wallet) rejects the transaction with PAL006.047. It never approves the transaction automatically.

Approvers see step-up approval requests with their other transaction approvals, in the web console and the mobile app. In the console, the transaction page shows Approval needed: Create transaction, the time left to respond, and Approve and Skip buttons. The approvals API and APPROVAL webhooks show these requests with source type TRANSACTION_GATE.

If the user who created the transaction is one of the rule's approvers, they can approve it.

Step-up approvals add more approvers to large transactions. They don't ask the user who creates the transaction to sign in again, for example with a passkey or hardware security key. Ripple Custody (Wallet) doesn't offer step-up authentication.

• Policies
• Manage policy rules via the API
• Approvals
• Configure approval flows
• Transaction status changes