Когда использовать
Иногда нужно проверить AML-риск криптокошелька до того, как появится транзакция для записи. Например, когда клиент добавляет адрес для вывода или когда ваша комплаенс-команда хочет разово проверить адрес. Эндпоинт скрининга кошельков по запросу выполняет скрининг одного адреса и возвращает полный результат оценки риска, не создавая транзакцию. Это самостоятельный аналог автоматического криптоскрининга, который выполняется при отправке транзакции. Оба варианта используют одних и тех же провайдеров аналитики блокчейна и один и тот же формат результата.
Скрининг кошельков ничего не записывает в таблицу транзакций. Если результат проверки нужно привязать к отслеживаемой транзакции (с правилами, оповещениями и webhook), отправьте транзакцию.
Предварительные требования
Мониторинг транзакций должен быть настроен для приложения: либо с управляемым провайдером, либо с существующим ключом провайдера. Настройте его в разделе Транзакции > Настройки > Настройки провайдера в Business Console. Если провайдер не настроен, эндпоинт возвращает409 Conflict.
Запрос
POST https://verification.didit.me/v3/wallet-screening/
Аутентификация выполняется через заголовок x-api-key.
Покрытие сетей
Управляемая проверка поддерживает Base (BASE), Optimism (OP) и Arbitrum One (ARB) как для проверки кошельков, так и для проверки хешей транзакций.
Подключённые провайдеры могут иметь другое покрытие. Сеть также должна поддерживаться выбранным провайдером и вашим аккаунтом.
Celo (CELO), Mode (MODE) и Plume (PLUME) проверяются через подключённый аккаунт TRM Labs (Marketplace, со своим ключом). Управляемая проверка их не охватывает и возвращает 400.
Не отправляйте ETH для другой сети EVM: один и тот же адрес может иметь разную активность и разный риск в каждой сети.
При управляемой проверке USDT и USDC являются устаревшими псевдонимами для Ethereum, а не поиском во всех сетях, где существуют эти токены.
Для фактической сети кошелька используйте идентификатор сети (ETH, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM, HBAR, а с TRM Labs также CELO, MODE или PLUME).
Для токенов в записанных транзакциях сохраняйте токен в transaction_details.currency, а сеть указывайте отдельно в transaction_details.crypto_params.crypto_chain.
См. выбор актива и сети.
Ответ
Ответ содержит стандартизированный результат скрининга. По структуре он совпадает с результатом провайдераWALLET_SCREENING, возвращаемым при скрининге транзакций.
Как задаётся
severity. severity соответствует диапазону, в который попадает нормализованный risk_score: 0-9 → UNKNOWN, 10-39 → LOW, 40-69 → MEDIUM, 70-89 → HIGH, 90-100 → CRITICAL. UNKNOWN — самый низкий диапазон, а не отдельное состояние «нет данных». Значение risk_score: 0 (типичный случай чистого адреса) означает, что провайдер не вернул негативной оценки. Ненулевой балл в диапазоне 1-9 — реальный сигнал, но ниже уровня LOW. Поэтому оценивайте сам risk_score, а не только уровень. В любом случае не отображайте UNKNOWN как подтверждение отсутствия рисков или как успешное прохождение проверки.direction не меняет модель риска. Необязательное поле direction передаётся провайдеру только как контекст. Оно не влияет на risk_score, severity и на то, какие списки разбивки возвращаются: source_of_funds и destination_of_funds возвращаются всегда. Поэтому изменение или отсутствие direction не требует повторного скрининга уже проверенного адреса.Факторы риска
risk_factors отвечает на вопрос «почему адресу присвоена такая оценка». Провайдеры оценивают адрес по собственной модели и возвращают только вердикт. Merkle Science, например, возвращает целое число 0-5, поэтому одного risk_score недостаточно для принятия решений. Каждая запись называет один фактор. Записи упорядочены: сначала факторы высокого риска, затем по сумме, которая через них прошла.
Высокая оценка без фактора с
is_high_risk — реальный и значимый результат. Это означает, что провайдер оценил адрес по собственной модели экспозиции и не зафиксировал совпадений по санкционным спискам, с PEP или с атрибутированными сущностями. Перечисленные факторы — это потоки средств, на которых основана оценка. В summary это указано явно. Такие адреса стоит рассматривать как «проверить потоки средств», а не как подтверждённое совпадение. risk_factors ограничен пятью наиболее значимыми факторами. source_of_funds и destination_of_funds всегда содержат полную разбивку.risk_factors — это поле верхнего уровня, а не вложенное. Результаты, полученные до появления этого поля, не содержат ключ вовсе: читайте его как пустой список, а не предполагайте пустое объяснение.Разбивка по экспозиции
Каждая запись вsource_of_funds / destination_of_funds описывает одну сущность, с которой адрес обменивался средствами:
Связи с контрагентами
counterparty_connections перечисляет сущности, которые провайдер связывает с проверяемым адресом. Для Merkle Science они берутся из собственных меток владельца и пользователя адреса, поэтому одна и та же сущность может встречаться дважды, и они не содержат потоков средств: received_usd, sent_usd, received_hops и sent_hops равны null, а percentage равен 0.0. Потоки средств читайте в source_of_funds и destination_of_funds.
Пример
Реальный ответ для адреса из санкционного списка OFAC, проверенного через Merkle Science. Сокращён толькоraw_response, а report_signature заменён:
sanctions_hit: true может означать, что сам кошелёк находится под санкциями, или только то, что его средства имеют санкционную экспозицию, поэтому само по себе это не означает, что владелец проверяемого кошелька находится под санкциями.
Когда тот же скрининг выполняется для зарегистрированной транзакции, правила также могут читать custom_values.wallet_sanctioned, которое равно true только в том случае, если провайдер связывает сам кошелёк с сущностью, находящейся под санкциями, и custom_values.aml_sanctions_exposure_pct.
См. Поля скрининга для правил.
Чтобы отличить атрибуцию от экспозиции, читайте risk_factors, source_of_funds и destination_of_funds.
Пошаговое руководство см. в разделе Скрининг криптовалют и кошельков.
PDF-отчёт
Чтобы получить PDF-отчёт с брендингом Didit по результату скрининга, повторно отправьте точное тело ответа, включаяreport_signature, на POST /v3/wallet-screening/pdf/. Это запрос без сохранения состояния: вызова провайдера нет, дополнительная оплата не взимается, ничего не сохраняется. Изменение любого подписанного поля (risk_score, severity, sanctions_hit, …) перед повторной отправкой приводит к ошибке 400.
Биллинг
За каждый успешный скрининг AML-мониторинга тарифицируется одна операция, по той же ставке, что и скрининг криптовалют, связанный с транзакцией. Подробнее о ставках для управляемых ключей и подключённых ключей см. в разделе цены. Приложения в песочнице не тарифицируются. Ошибки валидации (400) и ошибки ненастроенного провайдера (409) никогда не тарифицируются.
Ошибки
Следующие шаги
Справочник API
Полная схема запроса и ответа для endpoint Screen Wallet.
PDF-отчёт Screen Wallet
Визуализация результата скрининга в виде PDF с брендингом Didit.
Скрининг криптовалют и кошельков
Автоматический скрининг при создании транзакции и модель результата.