Описание API

Сводка по адресу

Эндпоинт сводки возвращает базовую информацию об адресе: баланс, число транзакций, признак контракта и время последней активности. Вызов защищён Basic-авторизацией. Для обращения к API нужен ключ из личного кабинета my.bitscore.ru — там же создаются ключи API и виден идентификатор арендатора (tenant).

ℹ️

Каждый вызов расходует один resource «API call» из лимита лицензии. Остаток виден на странице управления лицензией.

Эндпоинт

http

POST /api/<address>/summary?chain=<chain>

bash

curl -X 'POST' \
  'https://<basic_domain>/evm/api/<address>/summary/?chain=<chain>' \
  -H 'Authorization: Basic <base64(tenant_id:api_key)>' \
  -d ''

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

Один лёгкий вызов даёт AML-офицеру быструю «визитную карточку» адреса без запуска полного расследования. Это удобно для первичного триажа клиентских и контрагентских адресов, проверки реквизитов перед платежом и массовой обработки списков. Параметр chain фиксирует сеть, чтобы один и тот же адрес не был спутан между разными блокчейнами при работе с обращениями и запросами.

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

Ответ 200 OK:

json

{
  "balance": 234234.23545,
  "usd_balance": 12.5,
  "tx_total": 120,
  "is_contract": true,
  "last_activity": 1729240270
}

Поле	Тип	Описание
`balance`	number	Баланс адреса в нативном активе сети.
`usd_balance`	number	Оценка баланса в долларах США.
`tx_total`	integer	Общее число транзакций адреса.
`is_contract`	boolean	`true`, если адрес — смарт-контракт.
`last_activity`	integer	Время последней активности (Unix-таймстамп).

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

Поля ответа позволяют аналитику быстро оценить характер адреса: пустой или «спящий» адрес, активный кошелёк с большим оборотом или смарт-контракт. Признак is_contract и tx_total помогают отделить технические адреса протоколов от пользовательских при идентификации клиента и контрагентов. Время последней активности (last_activity) пригодится при оценке актуальности адреса и при подготовке выгрузок для комплаенс-процедур по 115-ФЗ и рекомендациям FATF.

Коды ошибок

Код	Значение
`401`	Не авторизован — ключ не найден или неверный.
`402`	Закончились доступные вызовы API для этого ключа.
`403`	Доступ запрещён — ключ отозван.
`404`	Лицензия или арендатор (tenant) не найдены.

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

Что возвращает сводка по адресу?

Сводка возвращает компактный набор базовых атрибутов адреса: текущий баланс в нативном активе сети (balance), его оценку в долларах (usd_balance), общее число транзакций (tx_total), признак смарт-контракта (is_contract) и время последней активности (last_activity).

Это «визитная карточка» адреса: она не содержит детальной разбивки по рискам или контрагентам, а даёт быстрый профиль для первичной оценки и фильтрации.

Когда использовать сводку, а когда риск-скоринг?

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

Риск-скоринг применяют, когда по адресу уже принимается содержательное решение — нужна оценка вовлечённости в подозрительную активность, источники и получатели средств, категории риска. На практике сводка часто служит фильтром перед запросом полного скоринга.

Нужна ли авторизация для вызова сводки?

Да. Эндпоинт защищён Basic-авторизацией: в заголовке Authorization передаётся base64(tenant_id:api_key). Ключ API и идентификатор арендатора (tenant) выпускаются и хранятся в личном кабинете my.bitscore.ru.

Без корректного ключа вызов вернёт 401; отозванный ключ — 403; исчерпанный лимит вызовов — 402.

Какие сети (chain) поддерживаются?

Сводка запрашивается для конкретной сети, которая передаётся параметром chain в строке запроса. Эндпоинт построен по EVM-маршруту (/evm/api/...), то есть рассчитан на EVM-совместимые сети.

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

Как понять, что адрес — это смарт-контракт?

В ответе за это отвечает поле is_contract. Если оно равно true, адрес является смарт-контрактом, а не кошельком пользователя; false — обычный (externally owned) адрес.

Это важно для интерпретации остальных полей: у контрактов баланс и транзакции отражают логику протокола (пул, мост, биржевой контракт), а не поведение конкретного физического или юридического лица.