Monitoring

BRRR automatically monitors every wallet address registered through the Onboarding flow. No additional API calls are required to start monitoring — it begins the moment an address is successfully registered.

How monitoring works

  Partner registers address
  POST /partner/customer/add-address
           │
           ▼
  BRRR begins watching the address
  for on-chain activity (automatic)
           │
           │  incoming token transfer detected
           ▼
  BRRR triggers a risk re-evaluation
  (regardless of current risk score)
           │
           ▼
  RISK_ASSESSMENT webhook → Partner
  { risk: "LOW" | "MEDIUM" | "HIGH" | "VERY HIGH",
    reviewType: "TOPUP", ... }

Monitoring covers incoming token transfers across all networks supported by BRRR. Every qualifying transfer triggers a fresh risk evaluation, even if the address's risk level has not changed since the previous assessment.

Risk levels

The RISK_ASSESSMENT webhook delivers one of four risk levels. Your integration should act on each as follows:

Risk level	Meaning	Recommended action
LOW	Address is clear to proceed	Create a settlement quote and execute normally
MEDIUM	Address has minor risk signals	Proceed with caution; document the decision
HIGH	Address has significant risk signals	Do not settle; hold funds and review manually
VERY HIGH	Address is flagged for serious risk	Do not settle; contact support@holyheld.com

Settlement eligibility

Only addresses with a risk assessment of LOW or MEDIUM can proceed to the Settlement estimation step. Attempting to create a quote for a HIGH or VERY HIGH address will result in a FULFILLMENT_DENIED error.

Webhook events

Every risk re-evaluation — including evaluations where the risk level is unchanged — triggers a RISK_ASSESSMENT webhook. This ensures your system always has the latest risk status without needing to poll.

{
  "type": "RISK_ASSESSMENT",
  "timestamp": 1724247261,
  "payload": {
    "customerId": "cust_a1b2c3d4",
    "addressEVM": "0x26b92eD884B9FE3f572252ee78172BfBC1653dC1",
    "risk": "LOW",
    "reviewTimestamp": 1724247261,
    "reviewType": "TOPUP",
    "reviewData": {
      "fromAddress": "0x26b92eD884B9FE3f572252ee78172BfBC1653dC1",
      "amount": "10000",
      "totalAmount": "754699"
    }
  }
}

The reviewType field distinguishes the context:

reviewType	When it fires
INITIAL	First risk assessment when the address is registered
TOPUP	Re-assessment triggered by an incoming on-chain transfer

Retrieving risk scores via API

In addition to webhooks, you can fetch the current risk score at any time:

• By customer ID — GET /api/v4/partner/risk/by-customer/{customerId} — returns risk history for all addresses registered to that customer
• By EVM address — GET /api/v4/partner/risk/by-address/{addressEVM} — returns the risk history for a specific address

These endpoints return completed risk history and do not trigger a new evaluation. Within each riskScores array, entries are ordered from newest to oldest.

Monitoring and offboarding

Monitoring stops automatically when an address is removed via POST /api/v4/partner/customer/remove-address or when the customer is removed via POST /api/v4/partner/customer/remove.

No further RISK_ASSESSMENT webhooks will be sent for removed addresses.

Next steps

When a RISK_ASSESSMENT webhook arrives with risk LOW or MEDIUM, proceed to Settlement estimation to create a quote. See Webhooks for the full event reference and signature verification.