Onboarding

Onboarding establishes a relationship between a customer entity and one or more EVM wallet addresses. A customer must be registered before their addresses can be monitored for on-chain activity or included in settlements.

Prerequisites

Customers must complete KYC verification through SumSub with a GREEN status before they can be registered. BRRR will not begin monitoring or risk-assessing addresses until this status is confirmed.

Customer and address model

  Partner
    │
    ├── Customer A (customerId: "cust_abc")
    │     ├── Address 1: 0xPrimary...    ← registered at creation
    │     ├── Address 2: 0xSecond...     ← added later
    │     └── Address 3: 0xThird...      ← added later
    │
    └── Customer B (customerId: "cust_xyz")
          └── Address 1: 0xOther...

Each customer is identified by a unique customerId you define. One customer can have multiple addresses. An address can only belong to one customer.

Onboarding flow

  POST /api/v4/partner/customer/register
  { customerId, addressEVM }
           │
           ▼
  Customer created + first address registered
  BRRR begins monitoring addressEVM
           │
           ▼ (optional, add more addresses)
  POST /api/v4/partner/customer/add-address
  { customerId, addressEVM }
           │
           ▼
  Additional address registered and monitored

Endpoints

Endpoint	Description
POST /api/v4/partner/customer/register	Create a new customer and register their first EVM address
POST /api/v4/partner/customer/add-address	Add an additional EVM address to an existing customer

Idempotency

Both endpoints are safe to retry on network errors:

Scenario	Response
customerId already registered	400 CUSTOMER_EXISTS — treat as success if you were retrying
addressEVM already registered to this customer	400 ADDRESS_EXISTS — treat as success if you were retrying

Check before retrying

If you receive a network error and are unsure whether the request succeeded, retry with the same customerId and addressEVM. If you get CUSTOMER_EXISTS or ADDRESS_EXISTS, the original request already succeeded.

customerId requirements

Constraint	Detail
Format	Alphanumeric, hyphens, and underscores only (^[a-zA-Z0-9_-]+$)
Maximum length	64 characters
Case sensitivity	Case-sensitive — Cust_1 and cust_1 are different customers
Uniqueness	Must be unique within your integration

After onboarding

Once a customer and address are registered, BRRR automatically:

1. Begins monitoring the address for on-chain activity
2. Performs an initial risk assessment
3. Sends a RISK_ASSESSMENT webhook with the result

See Monitoring and Risk assessment for what happens next.

Offboarding

To remove an address or customer from monitoring, see Offboarding.

Next steps

After onboarding, BRRR will send a RISK_ASSESSMENT webhook with the initial risk score. Set up your webhook endpoint and read Risk assessment to understand how to act on each risk level.