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 Approvals.
• Doesn't let a wallet send on its own. The wallet still needs a LIMIT rule for the asset. Wallet-as-a-Service checks limits first. If a transaction exceeds a limit, Wallet-as-a-Service 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:

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 Conditions step, select the asset, and then select Approval under Rule.
5. Enter the amount in Require approval when the amount is over.
6. Select the approvers, and set Threshold to the number of approvals you require.
7. Select the approval timeout: 5, 15, or 30 minutes, or 1, 2, 4, 12, or 24 hours. The default is 1 hour.
8. On the Confirm step, review the rule, and then select Add policy rule.

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, Wallet-as-a-Service creates an approval request for the rule's approvers. The request keeps the approvers, required count, and timeout that the rule has when Wallet-as-a-Service 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, Wallet-as-a-Service 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. Wallet-as-a-Service doesn't offer step-up authentication.

• Policy rules (Policy Engine v2)
• Approvals
• Configure approval flows
• Policy Engine v2: transaction status changes