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.

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 reached, no further withdrawals are permitted.

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.
• 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.

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. To apply a rule to any destination, don't add a destination matcher.

{
  "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.

{
  "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 the matcher value. Ripple Custody (Wallet) excludes rules without a CHAIN_ID matcher from cross-chain raw signing — you must add an explicit CHAIN_ID matcher to authorize the sign. Add one CHAIN_ID matcher per allowed chain.

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 doesn't apply to non-EVM wallets: an XRP Ledger wallet accepts a CHAIN_ID of 1.

Example: Limit raw signing on the Optimism chain (chain ID 10) to 1 transaction per 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, list assets from the registry:

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

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. Viewers can't.

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