# Transaction screening

Executive summary
**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.


Why this matters
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.

Prerequisites
Before reading this page, you should understand:

- [Compliance overview](/products/custody/v1.34/concepts/compliance) - How compliance services work together
- [Transactions](/products/custody/v1.34/concepts/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.

## How screening works

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.

## Screening providers

Ripple Custody supports two screening providers. You configure one provider per deployment.

### Elliptic

[Elliptic](https://www.elliptic.co/) 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

[Chainalysis](https://www.chainalysis.com/) 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.

## Screening decisions

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.

## Incoming vs outgoing transactions

### Outgoing transactions

Screening runs before the transaction is broadcast to the blockchain. If rejected, no funds leave your custody.

### Incoming transactions

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.

## Skip quarantine for internal transfers

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.

### How it works

When an incoming transfer arrives, the system checks:

1. Is the sender a known Ripple Custody account (not an external address)?
2. Does the recipient account have a `skipQuarantineFrom` configuration?
3. 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.

### Configuration scopes

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.

### When quarantine still applies

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 `Domain` is configured)


### Transfer status

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.

### Audit and compliance

All quarantine decisions are fully auditable:

- The system emits a `QuarantineApplied` event when a transfer enters quarantine
- The system emits a `QuarantineSkipped` event when a transfer skips quarantine
- The system emits a `ComplianceConfigurationUpdated` event when you change the configuration
- Transfers appear in reporting with the appropriate `quarantineStatus` value
- The system records the skip reason and scope for regulatory transparency


For API configuration, see [Configure compliance settings](/products/custody/v1.34/api/accounting-entities/account/compliance-configuration).

## Supervisor agent

Automated approval and rejection decisions require a **supervisor agent** — a system-level user that executes compliance decisions. You configure this agent during compliance setup.

## Related documentation

- [Customize risk score configuration](/products/custody/v1.34/ui/transaction-screening-and-risk-management/customize-risk-score-configuration) — Set up risk thresholds
- [Create a compliance supervisor agent](/products/custody/v1.34/ui/transaction-screening-and-risk-management/create-a-compliance-supervisor-agent) — Configure the automated decision agent
- [Add a policy for automatic release of quarantined transfers](/products/custody/v1.34/ui/transaction-screening-and-risk-management/add-a-policy-for-an-automatic-release-of-quarantined-transfers) — Manage quarantined incoming transfers
- [Add a policy rule for outgoing transactions](/products/custody/v1.34/ui/transaction-screening-and-risk-management/add-a-policy-rule-for-outgoing-transactions) — Configure manual review workflows


## Next steps

| Topic | Description |
|  --- | --- |
| [Travel Rule](/products/custody/v1.34/concepts/compliance/travel-rule) | Configure VASP-to-VASP information exchange |
| [Compliance overview](/products/custody/v1.34/concepts/compliance) | How screening and Travel Rule work together |
| [Policies](/products/custody/v1.34/concepts/governance/policies) | Create governance policies for compliance workflows |