> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Didit проверяет адреса крипто-кошельков и хэши транзакций на AML-риск: оценка риска, связи с рискованными адресами и санкции. От $0.15 за проверку.

Криптоскрининг кошельков Didit, который также называется скринингом адресов или KYT (знай свою транзакцию), проверяет адреса кошельков и хеши транзакций каждого криптоперевода на риск AML. На выходе вы получаете оценку риска, степень подверженности рискованным источникам и совпадения с санкционными списками.

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

> [!TIP]
>
> Нужно проверить адрес **без** транзакции? Используйте эндпоинт [скрининга кошелька по запросу](https://docs.didit.me/ru/transaction-monitoring/wallet-screening.md) (`POST /v3/wallet-screening/`), чтобы получить тот же результат оценки риска для одного кошелька одним вызовом API.

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

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

1. В данных транзакции указано `currency_kind: "crypto"`
2. Мониторинг транзакций включен в [настройках приложения](https://docs.didit.me/ru/transaction-monitoring/settings.md)

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

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

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

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

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

```json theme={null}
{
  "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 выполнит скрининг кошелька назначения.

```json theme={null}
{
  "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 проверит хеш, привязанный к вашему адресу депозита, и, если доступно, дополнит ответ сводкой по транзакции.

```json theme={null}
{
  "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](https://business.didit.me), либо подключить собственный ключ провайдера в разделе **Marketplace** консоли (категория «Мониторинг криптовалют»).

`LIGHTNING` поддерживается только в конфигурациях Chainalysis и Elliptic с подключённым ключом.

> [!TIP]
>
> При **ценах с подключённым ключом** вы подключаете существующий 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](https://docs.didit.me/ru/transaction-monitoring/console.md) в виде интерактивной визуализации.

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

Результаты скрининга напрямую поступают в [движок правил](https://docs.didit.me/ru/transaction-monitoring/rules.md). 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-события.

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

> [card] [Отправка транзакций](https://docs.didit.me/ru/transaction-monitoring/transactions.md)
>
> Как отправлять транзакции, включая данные криптокошельков.

> [card] [Правила и скоринг](https://docs.didit.me/ru/transaction-monitoring/rules.md)
>
> Как результаты скрининга поступают в движок правил.

> [card] [Руководство по консоли](https://docs.didit.me/ru/transaction-monitoring/console.md)
>
> Просмотр анализа криптоскрининга, источников средств и графов сети в консоли.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.