Машинный перевод

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

Проверка адреса

Crypto2B позволяет клиентской системе проверить уровень риска (AML) любого криптоадреса перед выполнением операции с ним. Типичный сценарий — проверка адреса, введённого пользователем в форме вывода средств, перед созданием заявки на вывод.

Проверка выполняется асинхронно. Клиентская система регистрирует проверку, вызывая API /addressChecks/create, и получает результат одним из двух способов:

Обработать колбэк от Crypto2B с результатом проверки (см. Колбэки).
Повторно вызывать API /addressChecks/create с теми же параметрами до получения результата.

Процесс проверки адреса

Последовательность действий

Пользователь вводит адрес в клиентской системе, например для вывода средств.
Клиентская система отправляет Crypto2B запрос на проверку адреса, указывая валюту, транспортный протокол и адрес.
Crypto2B проверяет параметры запроса, ограничения клиента и наличие средств для оплаты проверки, регистрирует проверку и возвращает её идентификатор checkId со статусом Pending.
Crypto2B выполняет проверку адреса и определяет его уровень риска.
После завершения проверки Crypto2B списывает плату за проверку с баланса клиента и переводит проверку в статус Completed.
Если клиентская система использует механизм колбэков, Crypto2B отправляет колбэк с результатом проверки.
В противном случае клиентская система повторяет запрос с теми же параметрами и получает результат со статусом Completed.
Клиентская система принимает решение о принятии адреса на основе уровня риска amlRiskGrade.

Запрос

POST /api/v1/addressChecks/create

Параметр	Тип	Обязательный	Описание
`currencyShortName`	string	да	Короткое название валюты, например `USDT`
`transportProtocol`	string	да	Транспортный протокол, например `Tron`
`address`	string	да	Проверяемый адрес, не более 200 символов

{
  "currencyShortName": "USDT",
  "transportProtocol": "Tron",
  "address": "TJYeasypBnB2x5hLTpYPQZ6YR9ZL3hLj6b"
}

Ответ

Проверка зарегистрирована или выполняется — `202 Accepted`

{
  "data": {
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Pending",
    "amlRiskGrade": null,
    "description": null,
    "fromCache": null
  }
}

Проверка завершена — `200 OK`

{
  "data": {
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Completed",
    "amlRiskGrade": "Low",
    "description": "Exchange wallet",
    "fromCache": true
  }
}

Поле	Описание
`checkId`	Уникальный идентификатор проверки
`status`	Статус проверки: `Pending`, `Completed`
`amlRiskGrade`	Уровень риска адреса (см. Справочники). Заполняется только при статусе `Completed`
`description`	Описание адреса по результатам проверки, если доступно
`fromCache`	`true`, если возвращается ранее полученный результат (см. Повторные проверки)

Ошибки

HTTP-код	Код ошибки	Описание
400	—	Ошибка валидации параметров запроса, в том числе неверный формат адреса для указанной валюты и протокола
400	`INVALID_CURRENCY`	Валюта не найдена или не поддерживается на указанном протоколе
400	`INVALID_TRANSPORT_PROTOCOL`	Транспортный протокол не найден
402	`INSUFFICIENT_BALANCE`	На балансе клиента недостаточно средств для оплаты проверки
422	`OPERATION_RESTRICTED`	Проверка адреса недоступна для этого клиента
422	`TARIFF_NOT_FOUND`	Для клиента не настроен тариф

Статусы проверки

Статус	Описание
`Pending`	Проверка зарегистрирована и выполняется
`Completed`	Проверка успешно завершена, уровень риска получен, плата списана
`Error`	Проверка завершилась ошибкой. Плата не списывается
`Unknown`	Результат проверки не удалось определить, например проверка не поддерживается для указанной валюты. Плата не списывается

к сведению

Статусы Error и Unknown передаются только в колбэке. Если запрос повторяется после такой проверки, Crypto2B регистрирует новую проверку и возвращает 202 Accepted с новым checkId.

Повторные проверки

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

пока проверка выполняется — возвращает 202 Accepted с тем же checkId; новая проверка не создаётся;
после завершения — возвращает 200 OK с сохранённым результатом и fromCache: true; плата повторно не списывается.

По истечении 10 минут запрос регистрирует новую проверку, за которую взимается плата.

подсказка

Если клиентская система не использует колбэки, рекомендуется повторять запрос каждые несколько секунд до получения 200 OK. Изменение checkId в ответе означает, что предыдущая проверка завершилась ошибкой и была зарегистрирована новая.

Плата за проверку

За каждую успешно завершённую проверку с баланса клиента списывается фиксированная плата в долларах США; её размер определяется тарифом клиента (см. Тарификация).

Плата списывается, когда проверка завершается со статусом Completed.
Плата списывается со стейблкоин-баланса клиента (USDT или USDC) по курсу на момент списания. Сумма и валюта списания передаются в колбэке.
Если ни на одном из стейблкоин-балансов нет достаточных средств, запрос отклоняется с кодом 402.
За проверки со статусом Error или Unknown плата не взимается.
Списания за проверку адресов отображаются в списке операций личного кабинета.

Колбэк

Если для клиента настроен URL колбэка, Crypto2B отправляет колбэк при завершении проверки в любом из финальных статусов: Completed, Error, Unknown.

{
  "data": {
    "type": "AddressCheck",
    "checkId": "550e8400-e29b-41d4-a716-446655440000",
    "address": "TJYeasypBnB2x5hLTpYPQZ6YR9ZL3hLj6b",
    "status": "Completed",
    "amlRiskGrade": "Low",
    "description": "Exchange wallet",
    "currency": "USDT",
    "protocol": "Tron",
    "feeAmount": 0.5,
    "feeCurrencyShortName": "USDT",
    "timestamp": "2024-01-15T10:30:00Z",
    "errorCode": null,
    "errorMessage": null
  }
}

Поле	Описание
`type`	Тип операции: `AddressCheck`
`checkId`	Идентификатор проверки
`address`	Проверяемый адрес
`status`	Статус проверки: `Completed`, `Error`, `Unknown`
`amlRiskGrade`	Уровень риска адреса. Заполняется только при статусе `Completed`
`description`	Описание адреса по результатам проверки, если доступно
`currency`	Короткое название валюты
`protocol`	Транспортный протокол
`feeAmount`	Сумма списанной платы в валюте `feeCurrencyShortName`. `null`, если плата не списывалась
`feeCurrencyShortName`	Валюта, в которой списана плата
`timestamp`	Дата и время формирования колбэка (ISO 8601)
`errorCode`	Код ошибки для статусов `Error` и `Unknown`
`errorMessage`	Описание ошибки для статусов `Error` и `Unknown`

Коды ошибок колбэка

Код	Статус	Описание
`INSUFFICIENT_BALANCE`	`Error`	На момент списания на балансе клиента не было достаточно средств для оплаты проверки
`ANTIFRAUD_ERROR`	`Error`	Ошибка при выполнении проверки
`ANTIFRAUD_INVALID_RESULT`	`Unknown`	Проверка завершилась без определения уровня риска
`CURRENCY_NOT_SUPPORTED`	`Unknown`	Проверка адреса не поддерживается для указанной валюты или протокола
`INTERNAL_ERROR`	`Error`	Внутренняя ошибка обработки

примечание

Для колбэков проверки адреса уникальность определяется комбинацией type и checkId, а не type и id, как для других операций.

Процесс проверки адреса​

Последовательность действий​

Запрос​

Ответ​

Проверка зарегистрирована или выполняется — 202 Accepted​

Проверка завершена — 200 OK​

Ошибки​

Статусы проверки​

Повторные проверки​

Плата за проверку​

Колбэк​

Коды ошибок колбэка​