Skip to main content
Депозит — это запрос на приём средств от вашего клиента. Платформа создаёт уникальную цель приёма (адрес, а для memo-сетей — общий адрес плюс уникальный memo), мониторит сеть на входящую транзакцию и сообщает об оплате двумя способами: через статусы (которые вы читаете GET-запросами) и через webhooks, которые платформа сама шлёт на ваш callback_url. Все запросы подписываются HMAC — см. Аутентификация. Ответы приходят в едином конверте: { "ok": true, "data": ... } при успехе и { "ok": false, "error": { "code": "...", "message": "..." } } при ошибке (см. Ошибки). Все суммы — строки, чтобы не терять точность на float.
Во всех примерах ниже базовый URL и идентификатор ключа одни и те же: https://wallet.your-exchange.com и X-Api-Id: pk_live_a1b2c3d4. Подставьте свои значения из админ-кабинета.

Эндпоинты

Адрес или адрес + memo: TON против TRON/EVM

Платформа поддерживает две модели идентификации входящего платежа. От модели зависит, что именно нужно показать вашему клиенту для оплаты.

Address-based (TRON, EVM)

На каждый депозит выдаётся уникальный адрес. В ответе memo равен null. Клиент переводит средства на data.address — этого достаточно, чтобы платёж был привязан к нужной заявке.

Memo-based (TON)

Используется общий приёмный адрес плюс уникальный memo (он же comment/tag). В ответе memo не равен null. Клиент обязан указать и data.address, и data.memo — без memo платёж невозможно сопоставить с заявкой.
Для memo-сетей (TON) memo обязателен. Если клиент отправит средства на общий адрес без memo или с неверным memo, платёж не будет автоматически привязан к депозиту. Всегда проверяйте data.memo !== null и показывайте memo как отдельное обязательное поле.

Создать депозит

POST /v1/public/deposits Создаёт новый депозит и возвращает реквизиты для оплаты. Вызывайте этот эндпоинт в момент, когда клиент на стороне обменника выбрал валюту и готов платить. Операция идемпотентна по комбинации (site, order_id, asset) и, опционально, по заголовку X-Idempotency-Key. Подробнее — в разделе Идемпотентность.
Создание новых депозитов требует активной лицензии инстанса. Если лицензия не активирована, эндпоинт вернёт 403 LICENSE_REQUIRED. Уже идущие депозиты при этом не затрагиваются.

Тело запроса

string
required
Код актива, например USDT_TRC20, TRX, USDT_TON. Полный список доступных активов — GET /v1/public/assets. Максимум 64 символа.
string
Ваш идентификатор заявки (label), 1–255 символов. Опционально — если не передать, платформа сгенерирует уникальный код вида NNNN-NNNN-NNNN. По умолчанию (строгий режим) order_id должен быть уникален в рамках сайта: повтор уже использованного значения вернёт 409 DUPLICATE_ORDER_ID. Один и тот же order_id на другой валюте также вернёт 409. Для безопасных ретраев используйте X-Idempotency-Key — он проверяется раньше, чем срабатывает эта ошибка. См. Идемпотентность.
string
Ожидаемая сумма как decimal-строка, например "100.50". Опционально — если не передать, берётся минимальная сумма приёма актива (asset.minDepositAmount). Значение "0" означает «принять любую сумму». Число знаков после запятой не должно превышать точность актива, иначе вернётся 400 AMOUNT_TOO_MANY_DECIMALS.
string
Опциональная заметка к депозиту (видна только вам в админ-кабинете). Максимум 1024 символа.
Пример ответа для memo-сети (TON) — обратите внимание на непустой memo:
Покажите клиенту data.address, а если data.memo не равен null (memo-сети) — ещё и data.memo как обязательное поле. transaction равен null до тех пор, пока в сети не будет замечена входящая транзакция.

Поля ответа

Ответ создания и все GET-эндпоинты (кроме AML) возвращают один и тот же объект депозита:
string
Публичный идентификатор депозита. Используйте его в GET /v1/public/deposits/{uuid}.
string
Ваш order_id (label). Если вы его не передавали, здесь будет авто-сгенерированный код.
string
Адрес для оплаты. Для memo-сетей — общий приёмный адрес (используется вместе с memo).
string | null
Memo/comment. Не равен null и обязателен для memo-сетей (TON); null для address-based сетей (TRON, EVM).
string
Код актива депозита.
string
Ожидаемая сумма (строка). "0" означает, что принимается любая сумма.
string
Бизнес-статус депозита. Полный набор и переходы — Статусы депозита.
string
ISO-8601. До какого момента сеть мониторится на оплату. После этого момента неоплаченный депозит уходит в expired.
string | null
Ссылка на адрес в блок-эксплорере (null, если для актива не настроен шаблон).
object | null
On-chain данные входящей транзакции. null, пока депозит не получил ни одной транзакции.

Получить депозит

GET /v1/public/deposits/{uuid} — по uuid из ответа на создание. GET /v1/public/deposits/by-order-id/{orderId} — по вашему order_id. Оба эндпоинта возвращают один и тот же объект депозита. Поле transaction заполняется, как только в сети замечена входящая tx, и обновляется с каждым новым подтверждением. Опрашивайте эндпоинт периодически либо опирайтесь на webhooks, чтобы не дёргать API лишний раз.
Это GET-запросы без тела, поэтому подписываемое сообщение — X-Timestamp + "." + "", то есть просто "1769990500." (timestamp и точка). См. Аутентификация.
Прогресс подтверждений считается как transaction.confirmations / transaction.requiredConfirmations (например 3 / 19). Чтобы отличить точную оплату от переплаты или недоплаты, сравните transaction.receivedAmount с expectedAmount — подробности в Статусах депозита.

Список депозитов

GET /v1/public/deposits?page=1&perPage=20&status=paid Возвращает историю депозитов вашего сайта в обратном хронологическом порядке. Каждый элемент имеет ту же форму, что и одиночный депозит.

Параметры запроса

integer
default:"1"
Номер страницы, начиная с 1.
integer
default:"20"
Размер страницы. Минимум 1, максимум 100.
string
Фильтр по статусу: одно значение (?status=paid) или несколько через запятую (?status=paid,paid_over). Допустимые значения — из набора бизнес-статусов депозита (см. Статусы депозита). Неизвестные значения молча игнорируются.

Поля meta

number
Текущая страница.
number
Размер страницы.
number
Всего записей по всем страницам (для пагинации).

AML-данные депозита

GET /v1/public/deposits/{uuid}/aml GET /v1/public/deposits/by-order-id/{orderId}/aml Отдельный под-ресурс с результатом AML-скрининга source-of-funds — адреса отправителя входящей транзакции. Основной объект депозита намеренно не содержит AML-полей; запрашивайте их явно через эти эндпоинты.
amlStatus равен not_checked, если AML-скрининг выключен в настройках инстанса, либо транзакция ещё не замечена, либо сеть не поддерживается AML-провайдером. Значение checkState: "skipped" НЕ означает «чисто» — это означает, что проверка не выполнялась.

Поля AML-ответа

string
UUID депозита (тот же, что в GET /{uuid}).
string
Ваш order_id (label).
string
Код актива депозита.
string
Код сети депозита (например TRON, TON).
string | null
Адрес отправителя входящей транзакции — именно он проходит AML-скрин. null, пока tx не замечена.
string
Итоговый AML-статус депозита: not_checked (не проверялся / AML выключен) | passed (чисто) | flagged (подозрительно, но не блокировка) | hold (заблокирован, ждёт ручного решения) | rejected (отклонён).
string | null
Состояние запроса к провайдеру: pending | success | failed | error | skipped. null, если проверки не было.
string | null
Risk-score 0–100 (строка). null, если проверки не было.
string | null
Уровень риска: low | medium | high | severe. Значение severe соответствует санкциям, терроризму, краденым средствам или эксплуатации — блокировка независимо от score.
string | null
Решение скрининга: pass | flag | block.
string | null
Код AML-провайдера.
string | null
Топ-сигнал риска (категория с максимальным весом), например mixer, sanctions, scam, darknet.
object | null
Карта сигналов риска и их весов (0..1). null, если провайдер их не вернул.
string | null
Ссылка на полный отчёт провайдера (если есть).
string | null
Публичная share-ссылка на отчёт (если есть).
string | null
ISO-8601. Когда выполнен AML-скрин. null, если проверки не было.
string | null
Ручное действие оператора над заблокированным депозитом: release (разрешить свип) | quarantine_now.
string | null
ISO-8601. Когда применено ручное действие.
string | null
Причина ручного действия (комментарий оператора).

Частые ошибки

Полный список кодов и формат конверта ошибки — на странице Ошибки.

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

Как только платформа замечает первую входящую транзакцию на адрес (и memo) депозита. До этого момента transaction равен null, а status остаётся check. После детекции статус переходит в process, а поля транзакции обновляются с каждым подтверждением.
По финальному статусу: paid — оплачено ровно ожидаемой суммой, paid_over — больше, wrong_amount — меньше. Если expectedAmount равен "0", принимается любая сумма и исход всегда paid. Точную фактическую сумму смотрите в transaction.receivedAmount. Подробнее — в Статусах депозита.
Рекомендуем основным каналом сделать webhooks — платформа сама уведомит о смене статуса. GET-эндпоинты используйте как резервный механизм (для реконсиляции и при пропущенных вебхуках), опрашивая их с разумным интервалом.
В строгом режиме (по умолчанию) — 409 DUPLICATE_ORDER_ID, второй депозит не создаётся. Чтобы безопасно повторять запрос при сетевых сбоях, передавайте X-Idempotency-Key: при совпадении ключа и тела вернётся ранее созданный депозит. См. Идемпотентность.
Нет. Все запросы скоупятся по вашему сайту. Запрос депозита, принадлежащего другому сайту, вернёт 404 DEPOSIT_NOT_FOUND — платформа не раскрывает существование чужих UUID.
См. также: Статусы депозита, Webhooks, Аутентификация, Идемпотентность, Ошибки.