Policy reference

This page is a reference for policy rule limit types, matchers, statuses, permissions, and error codes. For the API operations, see Manage policy rules via the API. For the full request and response schemas, see the Policies operations in the Ripple Custody (Wallet) API reference.

LIMIT rules support all three. APPROVAL and TRAVEL_RULE rules support SINGLE_TX only. For how the wallet limits endpoints show the other fields, see Use the wallet limits endpoints.

A LIMIT rule sets its limit type in definition.limit.amount.aggregation. Every amount condition uses operator GT: the rule limits transactions of more than threshold. A transaction that equals the threshold passes.

The examples on this page show the definition object. A LIMIT rule request also needs trigger set to OUTBOUND_INITIATED and an assetId outside definition. Without them, the API rejects the rule with PAL006.040. See Create a policy rule via the API.

Rolling and Max total value totals count the asset's outbound transactions that match the rule and aren't rejected or failed. That includes pending transactions, such as ones waiting for approval, and transactions made before you created the rule, so a new Max total value rule can already be at its limit when it becomes active. Sweeps and passkey transfers don't count toward these totals.

Sweeps, passkey transfers, and some signing actions aren't evaluated against limit rules. See Operations that bypass policies.

Limits the maximum amount for any single transaction.

Example: Limit single ETH transactions to 10 ETH maximum.

{
  "kind": "LIMIT",
  "limit": {
    "amount": { "threshold": "10", "operator": "GT", "aggregation": "SINGLE_TX" }
  }
}

Limits the cumulative amount over a sliding time window.

Common duration values:

Example: Limit ETH withdrawals to 100 ETH per 24 hours.

{
  "kind": "LIMIT",
  "limit": {
    "amount": { "threshold": "100", "operator": "GT", "aggregation": "ROLLING", "duration": "86400s" }
  }
}

Sets a lifetime cap on total withdrawals. Once withdrawals reach the cap, the rule permits no further withdrawals.

Example: Limit total ETH withdrawals to 1,000 ETH ever.

{
  "kind": "LIMIT",
  "limit": {
    "amount": { "threshold": "1000", "operator": "GT", "aggregation": "TOTAL" }
  }
}

Matchers filter which transactions a policy rule applies to. Add matchers to create rules that target specific scenarios.

• Send each matcher as { "type": "...", "values": ["..."] }. Don't use the older single value string, which is deprecated. Responses echo each matcher with both values and value.
• 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.
• A rule can carry at most one of USER or API_CREDENTIAL, and at most one destination matcher from COUNTERPARTY_ID, ADDRESS_ID, WALLET_ID, and ALL_COUNTERPARTIES. Combining two of them returns PAL006.020 ("duplicate matcher type").
• A rule with no matchers is a base rule. A base limit rule applies only when no limit rule with matchers applies to the transaction. When any limit rule with matchers applies, Ripple Custody (Wallet) ignores all base limit rules for that asset for that transaction, including base rolling and Max total value rules, even if their limits are lower. This replacement happens within each rule kind: base approval rules still apply. A scoped rule can therefore loosen a base limit, and a wallet-wide cap needs a matching scoped rule as well. The console Confirm step warns you when a rule overrides matching rules. See Evaluation order.
• Transactions that a dApp submits through WalletConnect aren't checked against the address book. Ripple Custody (Wallet) records their destination as external, so COUNTERPARTY_ID, ADDRESS_ID, WALLET_ID, and ALL_COUNTERPARTIES matchers never match them, even when the destination is in your address book. They still need transaction approvers, and limit rules still evaluate them.
• 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.
• APPROVAL rules don't support matchers.

Applies the rule only to transactions of a specific type.

Values by blockchain:

{
  "trigger": "OUTBOUND_INITIATED",
  "assetId": "3::XRP",
  "matchers": [
    { "type": "TRANSACTION_TYPE", "values": ["Payment"] }
  ],
  "definition": {
    "kind": "LIMIT",
    "limit": {
      "amount": { "threshold": "1000", "operator": "GT", "aggregation": "SINGLE_TX" }
    }
  }
}

Applies the rule only when a specific user initiates the transaction.

{
  "matchers": [
    {
      "type": "USER",
      "values": ["8617b5b5-dfcf-4ffc-9f46-f7cec35a88bd"]
    }
  ]
}

Applies the rule only when a specific API credential submits the transaction.

{
  "matchers": [
    {
      "type": "API_CREDENTIAL",
      "values": ["cred-uuid-here"]
    }
  ]
}

Applies the rule only when sending to a specific address from your address book.

{
  "matchers": [
    {
      "type": "ADDRESS_ID",
      "values": ["019d1b00-c1f5-77a0-bda7-0a3d09c668b9"]
    }
  ]
}

Applies the rule only when sending to a specific counterparty.

{
  "matchers": [
    {
      "type": "COUNTERPARTY_ID",
      "values": ["019d1b00-c1f5-77a0-bda7-0a3d09c668b9"]
    }
  ]
}

Applies the rule to any transaction whose destination resolves to a counterparty. Use it to set one limit for all counterparty payments without listing each counterparty.

ALL_COUNTERPARTIES takes no values, and matches only destinations that resolve to a counterparty. When this rule applies to a transaction, it replaces the rules of the same kind that have no matchers for that transaction.

{
  "matchers": [
    {
      "type": "ALL_COUNTERPARTIES",
      "values": []
    }
  ]
}

Applies the rule only when signing for a specific address. Use this matcher for multi-signature scenarios where your wallet signs on behalf of another address. Only an active rule with a SIGN_FOR matcher that lists that address authorizes a sign-for transaction. Base rules and rules with other matchers never authorize it. If no such rule exists, Ripple Custody (Wallet) rejects the transaction with PAL006.005. On an EVM wallet, each SIGN_FOR value must be an EIP-55 checksummed address. Ripple Custody (Wallet) rejects any other form with PAL006.028.

{
  "matchers": [
    {
      "type": "SIGN_FOR",
      "values": ["rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"]
    }
  ]
}

Authorizes cross-chain raw signing for a specific EVM chain ID that Ripple Custody (Wallet) doesn't natively integrate.

The rule applies only when the raw transaction's chainId matches one of the matcher's values. Limit rules without any matchers (base rules) never apply to cross-chain raw signing. A rule with other matchers applies when all of its matchers match the transaction, whether or not it includes a CHAIN_ID matcher. If no rule applies, Ripple Custody (Wallet) rejects the transaction with PAL006.005. To allow several chains, list each chain ID as a value in a single CHAIN_ID matcher. A rule can hold only one CHAIN_ID matcher: a second one returns PAL006.020 or PAL006.040.

Value format: positive integer. A value that isn't an integer returns PAL006.028. Ripple Custody (Wallet) rejects natively integrated chain IDs (for example, Ethereum mainnet 1, Arbitrum 42161) — use the standard raw signing flow for those chains. This check applies to every wallet, including non-EVM wallets: in production, an XRP Ledger wallet also gets PAL006.028 for a CHAIN_ID of 1. Native chain IDs are the ones registered for the environment, so sandbox uses testnet IDs. A CHAIN_ID matcher on a non-EVM wallet never matches a transaction.

Example: Limit raw signing on the Optimism chain (chain ID 10) to 1 ETH per rolling hour.

{
  "trigger": "OUTBOUND_INITIATED",
  "assetId": "2::ETH",
  "matchers": [
    { "type": "CHAIN_ID", "values": ["10"] }
  ],
  "definition": {
    "kind": "LIMIT",
    "limit": {
      "amount": { "threshold": "1", "operator": "GT", "aggregation": "ROLLING", "duration": "3600s" }
    }
  }
}

You can add multiple matchers to a single rule. The transaction must match all matchers for the rule to apply.

Example: Limit a specific user to 50 ETH per transaction when sending to a specific counterparty.

{
  "trigger": "OUTBOUND_INITIATED",
  "assetId": "2::ETH",
  "matchers": [
    { "type": "USER", "values": ["user-uuid-here"] },
    { "type": "COUNTERPARTY_ID", "values": ["counterparty-uuid-here"] }
  ],
  "definition": {
    "kind": "LIMIT",
    "limit": {
      "amount": { "threshold": "50", "operator": "GT", "aggregation": "SINGLE_TX" }
    }
  }
}

Policy rules identify a token by its registry ID in assetId, so the rule covers that token contract only. To find a token's registry ID, read asset.id from the wallet's balances (GET /v2/vaults/{vaultId}/wallets/{walletId}/balances, which needs a WALLETS credential).

The wallet limits endpoints identify the token by symbol and contract instead. Include the contract field with the token's contract address:

{
  "limitType": "PER_TX",
  "symbol": "USDC",
  "limitQty": "10000",
  "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
}

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 wallet limits endpoints report the same statuses with a LIMIT_ prefix. See Use the wallet limits endpoints.

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.

The wallet limits endpoints use keylimit:create, keylimit:read, and keylimit:delete in the same way.

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. Owners, administrators, proposers, approvers, and auditors can view rules, but viewers can't.

Ripple Custody (Wallet) accepts an APPROVAL rule on a wallet that has compliance screening turned on. See What happens to a transaction.

For transaction rejection codes, see Transaction status changes.

• Policies – Understand rule kinds, scope, lifecycle, and evaluation
• Manage policies via the console – Create, change, and delete policy rules in the console
• Manage policy rules via the API – Create, list, get, and delete policy rules with the API
• Policy best practices – Recommended patterns and troubleshooting