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 символа.
number
Допуск недоплаты в процентах (0–100) именно для этого депозита: если получено не меньше expectedAmount × (1 − N/100), депозит считается оплаченным (paid). Полезно, когда клиент платит с биржи, удерживающей комиссию. По умолчанию — настройка сайта в админ-кабинете, иначе глобальная настройка платформы (0 — без допуска).
boolean
Режим доплаты. Если клиент прислал меньше, депозит получает статус wrong_amount, но остаётся открытым до конца окна мониторинга: клиент досылает недостающую сумму на тот же адрес, суммы складываются и депозит становится paid (или paid_over). Пока окно открыто, в ответе isFinal=false и topUp.waiting=true с topUp.remainingAmount. По умолчанию — настройка сайта. Доплата меньше 1% от expectedAmount игнорируется как пыль.
string
1.4.0. Webhook-URL именно для этого депозита (вместо callback_url сайта). Публичный http(s)-хост; приоритет: счёт → депозит/статический адрес → родительский адрес → сайт.
integer
Срок жизни депозита в секундах (окно мониторинга адреса), от 300 до 2 592 000 (30 дней). Опционально — по умолчанию берётся окно сети из настроек платформы (см. deposit.defaultLifetimeSecondsByNetwork в GET /v1/public/limits). По истечении депозит получает статус expired; если клиент всё же заплатил позже — вызовите POST /v1/public/deposits/{uuid}/refresh, и депозит оживёт.
Пример ответа для 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, пока депозит не получил ни одной транзакции.
string
Сеть актива (TRON, TON, …).
boolean
Терминальный ли статус (paid / paid_over / wrong_amount / cancel / fail / system_fail / refund_paid / refund_fail) — можно прекращать поллинг. expired не терминален: депозит можно оживить через refresh.
string | null
Оценка суммы в USD (полученной, а до получения — ожидаемой) по курсу на момент ответа. null, если курса нет.
string | null
Курс актива к USD на момент ответа.
string | null
Комиссия обменника (ledger), если учёт комиссий включён и депозит финализирован.
string
Время создания депозита (ISO-8601).
string
Время последнего изменения статуса (ISO-8601).
string | null
Допуск недоплаты (%) этого депозита; null — по настройкам сайта/платформы.
boolean
Режим доплаты включён.
object | null
Для платежей на статический адрес: { uuid, orderId, label } родительского адреса. null у обычных депозитов.
object | null
1.4.0. Последняя выплата-возврат депозита: payoutUuid, status, amount, destinationAddress, createdAt, updatedAt. null — возврат не запрашивался. См. Возврат депозита.
object | null
Состояние режима доплаты (null, если выключен).

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

GET /v1/public/deposits/{uuid} — по uuid из ответа на создание. GET /v1/public/deposits/by-order-id/{orderId} — по вашему order_id. Оба эндпоинта возвращают один и тот же объект депозита. Поле transaction заполняется, как только в сети замечена входящая tx, и обновляется с каждым новым подтверждением. Опрашивайте эндпоинт периодически либо опирайтесь на webhooks, чтобы не дёргать API лишний раз.

Обновить депозит (принудительная перепроверка)

POST /v1/public/deposits/{uuid}/refresh — форс-перепроверка адреса в сети. Используйте, когда клиент нажал «я оплатил», а transaction всё ещё null: платформа немедленно опросит сеть, а не дождётся планового тика. Просроченный депозит (expired) с найденной входящей tx оживляется (статус вернётся в check, окно мониторинга продлится). Возвращает актуальный объект депозита (как GET). Не чаще одного раза в 30 секунд на депозит — иначе 429 RATE_LIMITED.
cURL
Это 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). Допустимые значения — из набора бизнес-статусов депозита (см. Статусы депозита). Неизвестные значения молча игнорируются.
string
Keyset-пагинация: курсор из meta.nextCursor предыдущего ответа. Первую страницу по курсору запрашивайте с пустым cursor= — тогда meta.nextCursor появится в ответе (null — конец). При наличии cursor параметр page игнорируется. Выдача по курсору не сдвигается при появлении новых депозитов — ни пропусков, ни дублей при обходе истории.

Поля meta

number
Текущая страница.
number
Размер страницы.
number
Всего записей по всем страницам (для пагинации).
string | null
Только в режиме cursor: курсор следующей страницы, null — страниц больше нет.

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
Причина ручного действия (комментарий оператора).

Возврат депозита отправителю

Новое в 1.4.0
Создаёт выплату-возврат (source = refund) с hot-кошелька на адрес отправителя входящей транзакции (transaction.fromAddress) или на указанный toAddress. Депозит переходит в refund_process; по исходу выплаты — в refund_paid (webhook deposit.refunded) или refund_fail (opt-in webhook deposit.refund_failed). Возврат разрешён из статусов paid, paid_over, wrong_amount и refund_fail (повторная попытка). Выплата-возврат проходит обычный поток выплат: лимиты, whitelist, AML, JIT-подготовка, мониторинг сети. По настройке платформы «Возврат требует одобрения» (включена по умолчанию) она создаётся в pending_approval и ждёт решения оператора в админке — деньги уходят с hot-кошелька, автоматический возврат по внешнему запросу опасен. Требует ключ со scope deposit_and_payout.

Тело запроса

string
Адрес получателя. По умолчанию — адрес отправителя входящей транзакции. Если отправитель неизвестен (нет transaction.fromAddress), поле обязательно — иначе 400 REFUND_SENDER_UNKNOWN.
string
Memo/tag получателя для memo-сетей (TON, XRP, XLM…).
string
Сумма возврата (decimal string). По умолчанию — вся полученная сумма. Не больше полученной (400 REFUND_AMOUNT_INVALID). Сетевая комиссия удерживается с hot-кошелька по правилам выплат.
string
Причина (до 500 символов) — попадает в аудит.

Ответ 201

payout — обычный объект выплаты (см. Выплаты); отслеживайте его через GET /v1/public/payouts/{uuid} и вебхуки payout.*. В объекте депозита появляется поле refund:
Повторный вызов при живой выплате-возврате → 409 REFUND_IN_PROGRESS. После failed / rejected / cancelled возврат можно запросить снова (депозит к этому моменту в refund_fail).

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

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

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

Как только платформа замечает первую входящую транзакцию на адрес (и 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, Аутентификация, Идемпотентность, Ошибки.