Transaction screening analyzes counterparty wallet risk to automatically approve, reject, or flag transactions for manual review.
- Integrates with Chainalysis (categorical risk) or Elliptic (decimal scores 0-10).
- Outgoing transactions are screened before broadcast. Rejected transactions never leave custody.
- Incoming transactions are quarantined until screening passes.
- A supervisor agent automates approval/rejection decisions based on your configured thresholds.
Transaction screening is your first line of defense against processing illicit funds. Automated screening reduces the manual review burden while ensuring that no transaction bypasses compliance checks. Proper threshold configuration manages the balance between operational efficiency (fewer false positives) against risk tolerance (catching more suspicious activity).
For architects and operators: Configure risk thresholds based on your regulatory requirements and risk appetite. Monitor flagged transaction volumes — too many flags may indicate thresholds are too aggressive; too few may indicate insufficient scrutiny.
Before reading this page, you should understand:
- Compliance overview - How compliance services work together
- Transactions - Transaction lifecycle in Ripple Custody
Transaction screening analyzes the risk of blockchain transactions by examining counterparty wallet addresses against known risk indicators. Ripple Custody integrates with third-party screening providers to automate this analysis for both incoming and outgoing transactions.
When a transaction is created, the compliance service sends the counterparty address to your configured screening provider. The provider analyzes the address against their database of:
- Known illicit addresses (sanctions, ransomware, fraud)
- High-risk entity associations
- Suspicious transaction patterns
- Jurisdiction-based risk factors
The provider returns a risk assessment, which Ripple Custody uses to make an automated decision based on your configured thresholds.
Ripple Custody supports two screening providers. You configure one provider per deployment.
Elliptic uses decimal risk scores ranging from 0 to 10:
| Score Range | Risk Level | Typical Action |
|---|---|---|
| 0 - 3.3 | Low | Auto-approve |
| 3.3 - 6.6 | Medium | Manual review |
| 6.6 - 10 | High | Auto-reject |
You configure the exact thresholds for your organization. Transactions that fall between your low and high thresholds are classified as medium risk and require manual review.
Chainalysis uses categorical risk levels:
| Category | Description |
|---|---|
| Low | Minimal risk indicators |
| Medium | Some risk indicators present |
| High | Significant risk indicators |
| Severe | Critical risk indicators (sanctions, etc.) |
| Unknown | Risk level could not be determined |
For each category, you configure whether to auto-approve, auto-reject, or require manual review.
Based on the risk assessment and your configured thresholds, the system makes one of three decisions:
| Decision | Meaning | What happens |
|---|---|---|
AUTO_APPROVED | Risk is within acceptable limits | Transaction proceeds to execution |
AUTO_REJECTED | Risk exceeds limits | Transaction is blocked |
FLAGGED | Risk requires review | Transaction queued for manual approval |
For flagged transactions, users with appropriate roles (such as compliance-manager) must manually approve or reject the transaction.
Screening runs before the transaction is broadcast to the blockchain. If rejected, no funds leave your custody.
Funds are quarantined when detected by the indexer. Screening runs on the quarantined funds, and they are only released to the destination account after compliance checks pass. High-risk incoming funds can be held indefinitely pending investigation.
Internal transfers—transfers between accounts within your organization—typically represent low-risk movements that do not require compliance screening. You can configure accounts to automatically skip quarantine for these internal transfers while maintaining full audit visibility.
When an incoming transfer arrives, the system checks:
- Is the sender a known Ripple Custody account (not an external address)?
- Does the recipient account have a
skipQuarantineFromconfiguration? - Does the sender fall within the configured scope?
If all conditions are met, the transfer skips quarantine and proceeds immediately. The system emits a QuarantineSkipped event for audit purposes.
You configure the skipQuarantineFrom property at the account level. This property defines which internal transfers skip quarantine when received by that account.
| Value | Behavior |
|---|---|
None | Default. All incoming transfers are quarantined normally. |
Domain | Skip quarantine for transfers from accounts in the same domain. |
Instance | Skip quarantine for transfers from any account in the same Ripple Custody instance, including child domains. |
The Instance scope includes the root domain and all child domains recursively. Use this setting when your organization spans multiple domains but all internal transfers should be treated as low-risk.
Even with skipQuarantineFrom configured, quarantine still applies to:
- External transfers — Transfers from addresses not managed by Ripple Custody
- Out-of-scope transfers — Transfers where the sender is outside the configured scope (for example, a cross-domain transfer when
Domainis configured)
The quarantineStatus field on transfers indicates the quarantine outcome:
| Status | Meaning |
|---|---|
Quarantined | The system currently holds this transfer pending compliance review |
Released | The system quarantined and then released this transfer |
Skipped | This transfer bypassed quarantine due to internal transfer configuration |
The existing quarantined boolean field remains available for backward compatibility. Use quarantineStatus for the full semantic state.
All quarantine decisions are fully auditable:
- The system emits a
QuarantineAppliedevent when a transfer enters quarantine - The system emits a
QuarantineSkippedevent when a transfer skips quarantine - The system emits a
ComplianceConfigurationUpdatedevent when you change the configuration - Transfers appear in reporting with the appropriate
quarantineStatusvalue - The system records the skip reason and scope for regulatory transparency
For API configuration, see Configure compliance settings.
Automated approval and rejection decisions require a supervisor agent — a system-level user that executes compliance decisions. You configure this agent during compliance setup.
- Customize risk score configuration — Set up risk thresholds
- Create a compliance supervisor agent — Configure the automated decision agent
- Add a policy for automatic release of quarantined transfers — Manage quarantined incoming transfers
- Add a policy rule for outgoing transactions — Configure manual review workflows
| Topic | Description |
|---|---|
| Travel Rule | Configure VASP-to-VASP information exchange |
| Compliance overview | How screening and Travel Rule work together |
| Policies | Create governance policies for compliance workflows |