Risk assessment

Every registered wallet address is continuously monitored for on-chain activity. Whenever activity is detected, BRRR performs a risk evaluation and delivers the result via webhook. Your integration must act on the risk level before proceeding to settlement.

How risk assessment works

  Customer passes KYC (SumSub GREEN)
           │
           ▼
  Partner registers address
  POST /partner/customer/add-address
           │
           ▼
  BRRR performs initial risk assessment
  (reviewType: "INITIAL")
           │
           ▼
  RISK_ASSESSMENT webhook → Partner
           │
  ┌────────┴─────────────────────────────┐
  │                                      │
  ▼                                      ▼
LOW / MEDIUM                        HIGH / VERY HIGH
Proceed to settlement               Do not settle — hold
                                    and review manually

After the initial assessment, BRRR continues monitoring. Every incoming transfer to the address triggers a new evaluation (reviewType: "TOPUP") and another RISK_ASSESSMENT webhook. See Monitoring for details.

Risk levels

Level	Meaning	Settlement allowed?	Recommended action
LOW	Address is clear, no risk signals detected	✅ Yes	Proceed to Create a Settlement Quote
MEDIUM	Minor risk signals present	✅ Yes	Proceed with caution; document the decision for your records
HIGH	Significant risk signals; escalated to Holyheld's AML team	❌ No	Hold funds; flag for manual review; do not settle
VERY HIGH	Address flagged for serious risk; escalated to Holyheld's AML team	❌ No	Do not settle; contact support@holyheld.com

HIGH and VERY HIGH block settlement

Attempting to create a settlement quote for an address with HIGH or VERY HIGH risk returns a FULFILLMENT_DENIED error. Always check the risk level before calling Create a Settlement Quote.

Receiving risk results

Webhook notifications (recommended)

Subscribe to RISK_ASSESSMENT webhooks to receive updates in real time. A webhook fires for:

• The initial assessment (reviewType: "INITIAL") — typically within seconds of address registration
• Every incoming transfer (reviewType: "TOPUP") — even if the risk level has not changed

Webhooks may arrive out of order. Always use the timestamp field to determine recency. See Webhooks — Event ordering.

API polling

Query the current risk score at any time without waiting for a webhook:

• GET /api/v4/partner/risk/by-customer/{customerId} — all addresses for a customer
• GET /api/v4/partner/risk/by-address/{addressEVM} — a specific address

These endpoints return the most recent completed assessment and do not trigger a new evaluation.

For each address, the riskScores array is ordered from newest to oldest, so riskScores[0] is always the latest completed review.

Risk assessment during onboarding

Risk assessment begins automatically after both conditions are met:

1. The customer has passed KYC — SumSub status is GREEN or FINISHED
2. The address has been registered via POST /api/v4/partner/customer/add-address

If the KYC result is not yet available when the address is registered, BRRR stores the registration and waits for the SumSub GREEN webhook before starting the evaluation.

KYC status requirements

The externalCustomerID in the SumSub webhook must match the customerId used during Onboarding.

Risk assessment only begins after GREEN or FINISHED SumSub status. The following statuses do not trigger risk assessment: RETRY, RESUBMIT, FAILED, FINAL. The statuses EDD and ManualApproval are escalated to Holyheld's AML team for manual review.

When risk level cannot be determined

If BRRR cannot automatically determine the risk level (for example, due to insufficient on-chain history or an AML flag), an internal review is initiated. The RISK_ASSESSMENT webhook is sent once the manual review is complete. Design your system to handle the webhook whenever it arrives — do not time out waiting for it.

Next steps

Once you receive a LOW or MEDIUM risk score, you can proceed to Settlement estimation to create a quote. For HIGH or VERY HIGH addresses, hold funds and do not submit a quote until the risk is resolved.