Скрининг крипто-кошельков и адресов: API KYT

Криптоскрининг кошельков Didit, который также называется скринингом адресов или KYT (знай свою транзакцию), проверяет адреса кошельков и хеши транзакций каждого криптоперевода на риск AML. На выходе вы получаете оценку риска, степень подверженности рискованным источникам и совпадения с санкционными списками. Для криптовалютных транзакций Didit может проверять адреса кошельков и хеши транзакций по провайдерам блокчейн-аналитики, таким как Merkle Science, Crystal, Chainalysis, Elliptic и TRM Labs, во время создания транзакции. Скрининг выполняется на стороне сервера, дополнительные вызовы API с вашей стороны не требуются.

Нужно проверить адрес без транзакции? Используйте эндпоинт скрининга кошелька по запросу (POST /v3/wallet-screening/), чтобы получить тот же результат оценки риска для одного кошелька одним вызовом API.

Как запускается скрининг

Криптоскрининг запускается автоматически, когда выполняются оба условия:

В данных транзакции указано currency_kind: "crypto"
Мониторинг транзакций включен в настройках приложения

Этот режим по умолчанию можно переопределить для каждой транзакции с помощью include_crypto_screening в payload запроса на создание транзакции:

Значение	Поведение
`true`	Запустить крипто-скрининг, даже если значение по умолчанию на уровне приложения отключено
`false`	Пропустить крипто-скрининг, даже если значение по умолчанию на уровне приложения включено
не указано или `null`	Использовать значение по умолчанию на уровне приложения, заданное в консоли

Значение по умолчанию на уровне приложения находится в разделе Транзакции > Настройки в Business Console. include_crypto_screening переопределяет это значение только для той транзакции, которую вы создаете.

Выбор актива и сети

Актив и сеть задаются в разных полях. Укажите transaction_details.currency как символ токена, transaction_details.currency_kind как crypto, а transaction_details.crypto_params.crypto_chain как сеть. Например, этот фрагмент описывает пользовательский токен в сети Base:

{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}

Управляемый скрининг принимает BTC, ETH, LTC, XRP, BCH, DOGE, TRX, SOL, MATIC, BNB, BASE, OP, ARB, AVAX, ADA, XLM и HBAR. BASE означает Base, OP означает Optimism, ARB означает Arbitrum One, AVAX означает Avalanche C-Chain, ADA означает Cardano, XLM означает Stellar, а HBAR означает Hedera. Распространенные названия сетей тоже принимаются, например POLYGON или POL для MATIC, BSC для BNB и TRON для TRX. Celo, Mode и Plume не входят в управляемую интеграцию, их скрининг выполняется через подключенный аккаунт TRM Labs (CELO, MODE, PLUME). Подключенные провайдеры имеют собственное покрытие; для Lightning действуют дополнительные требования, описанные ниже. Всегда указывайте crypto_chain для токена, включая USDT и USDC. Без него валюта используется как сеть, а USDT и USDC определяют свою сеть по хешу транзакции или, если хеша нет, по адресу кошелька. Хеш Tron или Solana выбирает сеть Tron или Solana. Хеш 0x выглядит одинаково во всех сетях EVM, поэтому для USDT, USDC и ETH Didit ищет его в Ethereum, BNB Chain, Polygon, Base, Arbitrum и Optimism и проверяет транзакцию в той сети, где он найден. ETH включен, потому что он является нативным активом Ethereum, Base, Arbitrum и Optimism, а также переводится в BNB Chain как бриджированный токен BEP-20. Если ни в одной сети нет этого хеша или сети нельзя проверить в данный момент, транзакция не проверяется и скрининг не тарифицируется. В этом случае custom_values.aml_screening_status равен FAILED, custom_values.aml_screening_error объясняет причину, а одобренная транзакция переходит на проверку. Транзакция USDT или USDC без хеша проверяет кошелек, и адрес кошелька определяет сеть. Адрес Tron проверяется в Tron, а адрес Solana в Solana. Адрес 0x проверяется в первой из сетей Ethereum, BNB Chain, Polygon, Base, Arbitrum и Optimism, где он отправлял транзакцию или хранит токен. Адрес 0x без активности в этих сетях или адрес, сети которого нельзя проверить в данный момент, проверяется в Ethereum. Передача crypto_chain позволяет не выполнять этот поиск. Никогда не подставляйте ETH вместо фактической сети. Указание символа пользовательского токена не гарантирует, что его переводы проиндексированы для скрининга по хешу транзакции. Покрытие токена нужно проверять по контракту токена и сети. Созданная транзакция не означает успешного скрининга: перед тем как считать транзакцию проверенной, проверьте статус скрининга и результат провайдера.

Входящие и исходящие переводы

transaction_details.direction обязателен, потому что он сообщает Didit, какую сторону перевода нужно проверить.

Направление	До ончейн-перевода	После ончейн-перевода
Входящая (депозиты)	Проверьте кошелёк отправителя-контрагента, если вы передаёте его в `counterparty.payment_method.account_id`	Проверьте хеш транзакции, привязанный к адресу депозита вашего сервиса или клиента, в `subject.payment_method.account_id`
Исходящая (выводы)	Проверьте кошелёк назначения в `counterparty.payment_method.account_id` до отправки средств	Проверьте хеш транзакции, привязанный к тому же кошельку назначения, в `counterparty.payment_method.account_id`

Для скрининга кошельков до перевода не указывайте transaction_details.payment_reference_id: Didit выполнит скрининг соответствующего адреса кошелька. Для проверки после перевода укажите хеш блокчейн-транзакции в transaction_details.payment_reference_id: Didit проверит хеш транзакции и, если доступно обогащение данными из блокчейна, сохранит сводку по транзакции.

Lightning Network

Для скрининга Lightning Network укажите в transaction_details.crypto_params.crypto_chain значение LIGHTNING. Для проверки Lightning нужен подключённый ключ провайдера Elliptic или Chainalysis (BYOK) в Marketplace консоли. Управляемые провайдеры Merkle Science, Crystal и TRM Labs не принимают LIGHTNING: Didit отклоняет такие запросы с кодом 400 до проверки или биллинга. Для Elliptic Didit проверяет переданный идентификатор Lightning через анализ Lightning-кошелька BTC в Elliptic. Для Chainalysis Didit отправляет перевод Lightning в KYT, если присутствует transaction_details.payment_reference_id.

Обязательные поля

Для всех запросов на проверку криптовалют отправьте:

transaction_details.direction: INBOUND или OUTBOUND
transaction_details.currency_kind: crypto
transaction_details.currency: символ актива, например BTC, ETH, USDC или ваш пользовательский токен
Адрес кошелька у участника, выбранного в соответствии с приведёнными выше правилами направления

Для проверки хеша транзакции после того, как перевод попал в блокчейн, также отправьте:

transaction_details.payment_reference_id: хеш блокчейн-транзакции

Если проверка криптовалют включена, а нужный для направления адрес кошелька не передан, API Create Transaction отклоняет запрос.

Пример: проверка исходящего перевода до отправки

Перед отправкой средств создайте исходящую криптотранзакцию без хеша транзакции. Didit выполнит скрининг кошелька назначения.

{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}

Пример: проверка входящего перевода после получения

После получения средств укажите хеш транзакции. Didit проверит хеш, привязанный к вашему адресу депозита, и, если доступно, дополнит ответ сводкой по транзакции.

{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}

Поддерживаемые провайдеры

Провайдер	Статус	Цены для управляемого провайдера	Цены при использовании подключённого ключа
Merkle Science	Доступен	$0.15/скрининг	$0.02/скрининг
Crystal	Подключите ключ провайдера через Marketplace	Недоступно	$0.02/скрининг
Chainalysis	Подключите ключ провайдера через Marketplace	Недоступно	$0.02/скрининг
Elliptic	Подключите ключ провайдера через Marketplace	Недоступно	$0.02/скрининг
TRM Labs	Подключите ключ провайдера через Marketplace	Недоступно	$0.02/скрининг

Настроить предпочтительного провайдера можно в разделе Транзакции > Настройки > Настройки провайдеров в Business Console, либо подключить собственный ключ провайдера в разделе Marketplace консоли (категория «Мониторинг криптовалют»). LIGHTNING поддерживается только в конфигурациях Chainalysis и Elliptic с подключённым ключом.

При ценах с подключённым ключом вы подключаете существующий API-ключ провайдера и оплачиваете указанную инфраструктурную комиссию за каждую проверку. Используйте этот вариант, если у вас уже есть коммерческое соглашение с провайдером аналитики блокчейна.

Результаты скрининга

Каждый скрининг возвращает результат в одном стандартном формате, независимо от того, какой провайдер используется.

Статус скрининга

custom_values.aml_screening_status показывает, была ли транзакция проверена.

Значение	Смысл
`COMPLETED`	Скрининг завершён. Результат находится в `provider_results` и в других полях скрининга в `custom_values`.
`PENDING`	Скрининг ещё не завершён: провайдер продолжает анализ или Didit повторно проверит хеш транзакции позже (см. ниже).
`ERROR`	Провайдер ответил, но сообщил, что его собственный анализ завершился с ошибкой.
`FAILED`	Транзакция не была проверена. `custom_values.aml_screening_error` указывает причину. Плата за скрининг, управляемый Didit, не взимается; запрос, на который ответил подключённый провайдер, засчитывается как запрос к провайдеру.

Транзакция, которая иначе была бы одобрена, переходит в IN_REVIEW, пока её скрининг имеет любой статус, кроме COMPLETED.

Хеши транзакций, которые ещё не проиндексированы

Аналитическому провайдеру блокчейна может потребоваться несколько минут, чтобы проиндексировать перевод, только что добавленный в блок. До этого он не может его проверить. Если провайдер сообщает, что хеш транзакции ещё не проиндексирован, а сама сеть подтверждает, что транзакция существует, Didit повторно проверяет её в фоновом режиме, а не отмечает скрининг как неудачный:

Ответ при создании уже показывает custom_values.aml_screening_status со значением PENDING, а причина указана в custom_values.aml_screening_error. Одобренная транзакция удерживается в статусе IN_REVIEW с decision_reason_code aml_screening_pending.
Didit повторно проверяет хеш транзакции примерно через 2, 12 и 42 минуты после её создания.
Когда повторная проверка выполнена, результат сохраняется так же, как и любой другой скрининг, и за скрининг списывается плата один раз. Ваши правила повторно применяются к данным скрининга, удержание снимается, и вы получаете один webhook transaction.status.updated со статусом, который транзакция имеет после применения правил, независимо от того, изменился ли он. Транзакция, которая за это время была отклонена или по которой проверяющий принял решение, сохраняет свой статус.
Если провайдер всё ещё не проиндексировал хеш транзакции после последней повторной попытки, скрининг завершается со статусом FAILED, как и при создании: транзакция остаётся в IN_REVIEW с decision_reason_code aml_screening_failed, а списание производится так же, как при сбое на этапе создания: ничего за скрининг, управляемый Didit, и один запрос к провайдеру, если последняя попытка дошла до вашего подключённого провайдера. За предыдущие попытки, которые были повторены, плата никогда не взимается.
Если к моменту повторной проверки баланса уже не хватает на скрининг, скрининг завершается со статусом FAILED, и плата не взимается.

Повторные проверки применяются к хешам транзакций в сетях Ethereum, BNB Chain, Polygon, Base, Arbitrum, Optimism и Tron. Хеш, о котором сети неизвестно, или хеш из другой сети не проверяется повторно: скрининг сразу завершается ошибкой.

Оценка риска и уровень критичности

Каждый проверенный кошелёк или транзакция получает:

Оценка риска (0–100): чем выше оценка, тем выше степень подверженности воздействию рискованных сущностей
Уровень критичности: определяется по оценке и принимает значения LOW, MEDIUM, HIGH или CRITICAL

Анализ источника средств

Процентная разбивка того, откуда поступили средства, с разбивкой по типам сущностей:

Категория	Уровень риска	Описание
`SANCTIONED`	Критический	Сущности из международных санкционных списков (OFAC, ЕС, ООН)
`TERRORIST_FINANCING`	Критический	Адреса, связанные с финансированием терроризма
`CHILD_EXPLOITATION`	Критический	Адреса, связанные с материалами об эксплуатации детей
`RANSOMWARE`	Высокий	Адреса для выплат по программам-вымогателям
`STOLEN_FUNDS`	Высокий	Адреса, связанные с известными кражами или взломами
`DARKNET_MARKET`	Высокий	Адреса даркнет-маркетплейсов
`MIXER`	Высокий	Сервисы микширования и тамблинга, которые используются для сокрытия происхождения средств
`SCAM`	Высокий	Известные мошеннические адреса
`HIGH_RISK_EXCHANGE`	Средний	Биржи со слабым контролем KYC/AML
`HIGH_RISK_JURISDICTION`	Средний	Сущности в юрисдикциях повышенного риска из списка FATF
`GAMBLING_UNLICENSED`	Средний	Нелицензированные игорные платформы
`P2P_EXCHANGE`	Низкий	Сервисы однорангового обмена
`EXCHANGE`	Низкий	Регулируемые криптовалютные биржи
`UNNAMED_SERVICE`	Низкий	Неидентифицированные сервисы

Каждая сущность в разбивке содержит процент средств, суммы полученных и отправленных средств, а также указание на то, является ли связь прямой или косвенной.

Таблица экспозиции

Таблица экспозиции показывает сущности-источники, сущности-получатели и контрагентов, включая:

Название сущности и категорию
Прямую или косвенную связь (количество переходов)
Суммы полученных и отправленных средств
Уровень риска для каждой сущности

Граф сети

Визуальное представление транзакционных связей кошелька в виде узлов и рёбер:

Узлы представляют кошельки, биржи, сервисы и другие сущности
Рёбра представляют транзакции между узлами, с суммами и хешами транзакций
Показатели включают статистику уровня графа, например центральность и глубину

Граф сети доступен в Business Console в виде интерактивной визуализации.

Интеграция с правилами

Результаты скрининга напрямую поступают в движок правил. Didit включает предустановленные правила, которые срабатывают автоматически на основе данных скрининга:

Предустановленное правило	Действие
Sanctions counterparty	Немедленное отклонение - сам проверяемый кошелёк связан с субъектом, находящимся под санкциями (`custom_values.wallet_sanctioned`)
Санкционная экспозиция	Добавить оценку и пометить для проверки - кошелёк переводил средства санкционным субъектам или получал их от них, но сам не находится под санкциями (`sanctions_hit` равно true, `wallet_sanctioned` не равно true)
Terrorist financing / child exploitation	Немедленное отклонение
Darknet market exposure	Добавить оценку и пометить для проверки
Mixer/obfuscation service exposure	Добавить оценку и пометить для проверки
High-risk source of funds (>30%)	Добавить оценку и пометить для проверки
Multiple risky counterparties	Добавить оценку и пометить для проверки
Medium wallet risk score	Добавить оценку и пометить для проверки
Скрининг ожидается	Удерживать транзакцию до завершения скрининга

Поля скрининга для правил

Криптоскрининг записывает следующие ключи в custom_values транзакции, поэтому правила могут использовать их как custom_values.<key>:

Поле	Тип	Описание
`sanctions_hit`	boolean	Значение `true`, если сам кошелёк находится под санкциями или если средства какого-либо из его контрагентов поступили от санкционных субъектов (экспозиция). Крупные биржи обычно получают `true` только из-за экспозиции.
`wallet_sanctioned`	boolean	Значение `true` только тогда, когда поставщик скрининга связывает сам проверяемый кошелёк с субъектом, находящимся под санкциями (согласно санкционным решениям OFAC, ЕС, ООН или HMT). Одна лишь экспозиция никогда не устанавливает это поле.
`aml_sanctions_exposure_pct`	число (0-100)	Доля проверенного объёма кошелька, которая связана с санкционными субъектами. Рассчитывается так же, как `aml_high_risk_exposure_pct`, но только по санкциям.

Используйте wallet_sanctioned, чтобы блокировать переводы на санкционный кошелёк, не отклоняя переводы на крупные биржи, у которых есть только косвенная экспозиция. Используйте sanctions_hit или aml_sanctions_exposure_pct, чтобы проверять или оценивать экспозицию. Предустановленное правило Sanctions counterparty отклоняет транзакцию, когда wallet_sanctioned равно true, а предустановленное правило Санкционная экспозиция направляет на проверку кошельки, у которых есть только экспозиция. Эти два правила никогда не срабатывают на одну и ту же транзакцию, поэтому санкционный кошелёк всегда отклоняется. Если вы установили Sanctions counterparty до этого изменения, Didit автоматически изменил его так, чтобы оно использовало wallet_sanctioned, и добавил Санкционную экспозицию в том же режиме, поэтому перевод, который старое правило отклоняло только из-за экспозиции, теперь направляется на проверку. После завершения скрининга Didit автоматически повторно оценивает все правила по обогащённым данным транзакции и запускает все применимые webhook-события.

Дальнейшие шаги

Отправка транзакций

Как отправлять транзакции, включая данные криптокошельков.

Правила и скоринг

Как результаты скрининга поступают в движок правил.

Руководство по консоли

Просмотр анализа криптоскрининга, источников средств и графов сети в консоли.

Начало работы

Функции

Справочник

Консоль

Скрининг крипто-кошельков и адресов: API KYT

Как запускается скрининг

Выбор актива и сети

Входящие и исходящие переводы

Lightning Network

Обязательные поля

Пример: проверка исходящего перевода до отправки

Пример: проверка входящего перевода после получения

Поддерживаемые провайдеры

Результаты скрининга

Статус скрининга

Хеши транзакций, которые ещё не проиндексированы

Оценка риска и уровень критичности

Анализ источника средств

Таблица экспозиции

Граф сети

Интеграция с правилами

Поля скрининга для правил

Дальнейшие шаги

Отправка транзакций

Правила и скоринг

Руководство по консоли

​Как запускается скрининг

​Выбор актива и сети

​Входящие и исходящие переводы

​Lightning Network

​Обязательные поля

​Пример: проверка исходящего перевода до отправки

​Пример: проверка входящего перевода после получения

​Поддерживаемые провайдеры

​Результаты скрининга

​Статус скрининга

​Хеши транзакций, которые ещё не проиндексированы

​Оценка риска и уровень критичности

​Анализ источника средств

​Таблица экспозиции

​Граф сети

​Интеграция с правилами

​Поля скрининга для правил

​Дальнейшие шаги

Отправка транзакций

Правила и скоринг

Руководство по консоли

Как запускается скрининг

Выбор актива и сети

Входящие и исходящие переводы

Lightning Network

Обязательные поля

Пример: проверка исходящего перевода до отправки

Пример: проверка входящего перевода после получения

Поддерживаемые провайдеры

Результаты скрининга

Статус скрининга

Хеши транзакций, которые ещё не проиндексированы

Оценка риска и уровень критичности

Анализ источника средств

Таблица экспозиции

Граф сети

Интеграция с правилами

Поля скрининга для правил

Дальнейшие шаги