Описание API

Риск-скоринг

Эндпоинты риск-скоринга позволяют рассчитать оценку риска адреса программно. Расчёт асинхронный: сначала вы запускаете задачу (POST) и получаете job_id, затем опрашиваете её статус (GET). Все вызовы защищены Basic-авторизацией. Для обращения к API нужен ключ из личного кабинета — выпустите его на my.bitscore.ru в разделе «Ключи API».

Запуск расчёта

Создайте задачу на расчёт риск-скора для адреса в указанной сети:

http

POST /api/<address>/risk_score/chain=<str>&aggregator=<money|money_rank_weight>

Параметр aggregator необязателен — по умолчанию используется money.

bash

curl -X 'POST' \
  'https://<basic_domain>/risk/api/<address>/risk_score/chain=<chain>&aggregator=money' \
  -H 'Authorization: Basic <base64(tenant_id:api_key)>'

Ответ 200 OK содержит идентификатор задачи job_id:

text

risk_score_result_TRON.TQXPL...rjQj.01234abc-...-a2d7c261c132.8f1c529c-...-44b7f4f63014.money

Для чего это нужно?

Запуск расчёта через API позволяет AML-офицеру оценивать риск адреса в момент операции, а не постфактум: проверка вывода, пополнения или контрагента встраивается прямо в платёжный конвейер. Выбор aggregator настраивает методику под политику комплаенса, а возвращаемый job_id становится ссылкой на расчёт, которую удобно логировать в деле клиента для последующего аудита и отчётности по 115-ФЗ.

Статус по Job ID

Используйте полученный job_id, чтобы запросить статус и результат расчёта:

http

GET /api/risk_score?job_id=<str>

bash

curl -X 'GET' \
  'https://<basic_domain>/risk/api/risk_score?job_id=<job_id>' \
  -H 'Authorization: Basic <base64(tenant_id:api_key)>'

Структура ответа

При готовности возвращается объект risk_score:

json

{
  "risk_score": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "address": "string",
    "hash": "string",
    "risk_score": 0,
    "raw_risk_score": {},
    "chain": "string",
    "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_by": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "creator_display_name": "string",
    "created_at": "2025-09-29T10:21:14.560Z",
    "updated_at": "2025-09-29T10:21:14.561Z",
    "graph_file_name": "string"
  }
}

Поле risk_score — числовая оценка риска, raw_risk_score — детализация по категориям, chain — сеть, created_at / updated_at — время расчёта.

Для чего это нужно?

API-скоринг встраивает проверку риска прямо в бизнес-процессы: автоматически оценивать каждый адрес вывода на бирже, в реальном времени блокировать операции с высоким риском и вести KYT-мониторинг без ручной проверки. Это масштабирует комплаенс на тысячи транзакций и фиксирует решения для аудита.

Коды ошибок

Код	Значение
`402`	Вызов ограничен лицензией (закончились ресурсы).
`422`	Ошибка валидации параметров запроса.
`404`	Задача с указанным `job_id` не найдена.
`409`	Конфликт — расчёт ещё выполняется или уже обработан.

Для чего это нужно?

Корректная обработка кодов ответа делает интеграцию устойчивой и аудируемой. Аналитик и разработчик различают деловые ситуации (исчерпан лимит лицензии — 402, расчёт ещё идёт — 409) и технические ошибки запроса (422, 404), что исключает ложные блокировки операций и потерю расчётов. Однозначная реакция на каждый код обеспечивает непрерывность KYT-мониторинга и прозрачность процесса при проверках регулятора.

Частые вопросы

Почему расчёт асинхронный и зачем нужен job_id?

Оценка риска адреса требует обхода графа транзакций и опроса внешних источников, поэтому она не укладывается в один синхронный HTTP-запрос. Bitscore разбивает процесс на два шага: POST ставит задачу в очередь и сразу возвращает job_id, а GET по этому идентификатору отдаёт готовый результат.

Такая схема не держит соединение открытым на время расчёта и позволяет запускать массовый скоринг параллельно, не упираясь в таймауты.

Что такое параметр aggregator (money и money_rank_weight)?

aggregator задаёт способ свёртки риска по связанным адресам в итоговую оценку. Значение money взвешивает вклад источников по объёму средств, а money_rank_weight дополнительно учитывает «вес» (ранг) контрагента в графе.

Параметр необязателен — по умолчанию применяется money. Выбирайте money_rank_weight, когда важно усилить влияние крупных или высокорисковых узлов сети.

Как часто опрашивать статус по job_id?

Рекомендуется опрашивать GET /api/risk_score?job_id=… с интервалом в несколько секунд, пока задача не завершится. Пока расчёт выполняется, эндпоинт может возвращать код 409 — это нормальное состояние «ещё не готово», а не ошибка.

Не опрашивайте статус чаще раза в секунду: это создаёт лишнюю нагрузку и расходует лимиты лицензии без пользы.

Чем API-скоринг лучше ручной проверки адреса?

Ручная проверка не масштабируется: аналитик физически не успеет проверить тысячи адресов вывода. API встраивает оценку риска прямо в бизнес-процессы — каждая операция проверяется автоматически и единообразно, по одним и тем же правилам.

Это ускоряет принятие решений, убирает человеческий фактор и фиксирует результат расчёта для последующего аудита и отчётности по 115-ФЗ и рекомендациям FATF.

Что делать при ошибке 402?

Код 402 означает, что вызов ограничен лицензией — закончились доступные ресурсы (квота на расчёты). Проверьте остаток лимита и условия тарифа в личном кабинете my.bitscore.ru и при необходимости расширьте лицензию.

До пополнения квоты новые задачи на расчёт приниматься не будут, поэтому имеет смысл предусмотреть обработку этого кода в интеграции.

Что означает ошибка 409 и как её обрабатывать?

Код 409 — это конфликт состояния: расчёт по указанному job_id ещё выполняется либо уже обработан. При опросе статуса воспринимайте 409 как сигнал «подождите и повторите запрос», а не как фатальную ошибку.

Если код возвращается стабильно и долго, проверьте корректность job_id и убедитесь, что задача действительно была создана успешным POST-запросом.