Skip to main content
Подборка вопросов, на которых чаще всего спотыкаются интеграторы CMS обменника. Если ответа нет — загляните в Аутентификацию, Идемпотентность, каталог Ошибок и Лимиты запросов.

​
Подпись запросов

В 9 из 10 случаев подписаны не те байты тела. Подпись считается от сырого тела — ровно той строки, что уходит на сервер.
  • Сериализуйте JSON один раз, подпишите эту строку и отправьте именно её.
  • Не используйте библиотеку, которая повторно сериализует объект перед отправкой (другой порядок ключей или пробелы сломают подпись).
  • Сообщение для HMAC — это {timestamp}.{raw_body} (timestamp, точка, тело).
  • Ключ HMAC — api_secret, результат — hex в нижнем регистре.
Эталонные сниппеты на Node.js, Python, PHP и cURL — на странице Аутентификация.
Для GET/DELETE и любых запросов без тела raw_body — пустая строка (не {} и не null). Тогда сообщение для подписи получается вида {timestamp}. (timestamp, затем точка и ничего после неё).
Нет. api_secret участвует только в вычислении X-Signature на вашей стороне и никогда не отправляется в заголовках. Платформа хранит секрет в зашифрованном виде и проверяет подпись на сервере. Не используйте устаревший заголовок X-Api-Secret.

​
Время и часы

X-Timestamp вышел за пределы ±300 секунд от времени сервера платформы. Обычно это рассинхронизация часов.
  • Включите синхронизацию по NTP на сервере обменника.
  • Берите X-Timestamp непосредственно перед отправкой запроса, а не заранее.
  • Время — в секундах Unix (не в миллисекундах).
В целых секундах Unix-времени (например, 1782000000). Распространённая ошибка — прислать миллисекунды; такой timestamp окажется далеко в будущем и вернёт TIMESTAMP_SKEW.

​
Идемпотентность и дубликаты

Присылайте на каждую write-операцию заголовок X-Idempotency-Key: <uuid>. Повтор того же запроса с тем же ключом и тем же телом вернёт первый результат — без дубликата и без 409. Ключ хранится 24 часа и изолирован в пределах вашего сайта.
order_id — ваш бизнес-идентификатор заявки; по нему ресурс ищется позже через GET .../by-order-id/{order_id}. По умолчанию он строго уникален в рамках сайта — повтор вернёт 409 DUPLICATE_ORDER_ID. X-Idempotency-Key — технический ключ безопасного повтора одного и того же HTTP-запроса. Используйте оба: order_id для связи с заявкой, X-Idempotency-Key для надёжных ретраев. Подробнее — Идемпотентность.
Этот код возвращается, когда тот же X-Idempotency-Key уже использовался, но с другим телом запроса. Сгенерируйте новый UUID для нового тела, либо повторяйте ровно то же тело, что и в первый раз.

​
Суммы и числа

Деньги в API — всегда строки ("100.50"). Числа с плавающей точкой теряют точность (0.1 + 0.2 !== 0.3), что недопустимо для финансов. Передавайте и читайте суммы как строки; на своей стороне считайте через decimal-библиотеку, а не через float/number.
Сумма содержит больше знаков после запятой, чем поддерживает актив (asset.decimals). Например, USDT_TRC20 — 6 знаков, BTC/LTC — 8. Округлите сумму до точности актива (значение decimals есть в GET /v1/public/assets).
Из GET /v1/public/assets: поля minDeposit, minPayout, decimals. Не хардкодьте — набор активов и лимиты зависят от настроек инстанса.

​
Сети, адреса и memo (TON)

TON относится к memo-based архетипу: используется общий приёмный адрес, а конкретная заявка идентифицируется уникальным memo (comment). При создании депозита в TON платформа выдаёт пару «адрес + memo» — плательщик обязан указать memo, иначе платёж невозможно привязать к заявке. Передавайте memo пользователю вместе с адресом и не теряйте его.
Адрес и memo проверяются по правилам конкретной сети. Убедитесь, что адрес соответствует выбранной сети (code из GET /v1/public/networks), а memo — формату memo-based сети. Не подставляйте адрес одной сети в операцию другой сети.
GET /v1/public/networks — список включённых сетей с архетипом и числом подтверждений; GET /v1/public/assets — активы с привязкой к сети, точностью и лимитами. Эти справочники меняются редко — кэшируйте их.

​
Webhooks, тестирование и polling

Используйте POST /v1/public/webhooks/test — платформа поставит в очередь тестовый webhook (X-Event-Type: webhook.test) на ваш callback_url с настоящей подписью. Так вы проверите, что endpoint доступен и корректно валидирует X-Signature, ещё до первой реальной операции. Переотправить уже сгенерированное событие можно через POST /v1/public/webhooks/resend/{event_id} (по X-Event-Id).
Основной механизм — webhooks: изменения статуса доставляются мгновенно. Polling (GET .../{uuid} или .../by-order-id/{order_id}) держите как редкий запасной механизм на случай пропущенного webhook — не чаще раза в несколько секунд, иначе упрётесь в лимиты запросов.
Webhook приходит с заголовками X-Signature, X-Timestamp, X-Event-Type, X-Event-Id. Подпись — HMAC-SHA256 от сырого тела webhook с вашим callback_secret. Сверяйте её и используйте X-Event-Id для идемпотентной обработки на своей стороне. Детали — на странице Webhooks.

​
Доступ: IP-whitelist и ключи

Отдельного публичного sandbox нет: WalletCore — это отдельный инстанс на каждого клиента (свой сервер, свои ключи, своя БД). Тестирование выполняется на вашем инстансе — оператор может включить нужные сети/активы и помочь с тестовыми параметрами. Для проверки доставки уведомлений используйте POST /v1/public/webhooks/test.
Для сайта задан белый список IP, и запрос пришёл не с разрешённого адреса. Добавьте исходящий IP сервера обменника в whitelist в личном кабинете. Учтите прокси/NAT: в whitelist должен попасть реальный внешний IP, с которого уходит запрос.
Выпустите новый ключ в личном кабинете, переключите интеграцию на новую пару api_id / api_secret, убедитесь, что запросы проходят, и только потом отзовите старый ключ. api_secret показывается один раз при создании — сохраните его сразу в надёжном месте. Запросы старым отозванным ключом получат API_KEY_REVOKED.
Немедленно отзовите ключ в личном кабинете и выпустите новый. Поскольку подпись зависит от секрета, отзыв ключа делает любые ранее перехваченные запросы невалидными для новых вызовов.

​
Общее

Только на error.code — он стабилен. error.message предназначен для людей и может меняться. Полный каталог кодов с рекомендациями по устранению — на странице Ошибки.
error.traceId — идентификатор запроса в логах инстанса. При обращении в поддержку укажите его: по traceId оператор быстро найдёт конкретный запрос. Для 5xx это основной способ диагностики, так как внутренний message в production скрыт.
У каждого клиента свой инстанс, поэтому base URL выдаётся при подключении (например, https://wallet.your-exchange.com). Все эндпоинты живут под /v1/public/*. Подробнее — Окружения и справочники.
Связанные страницы: Аутентификация, Идемпотентность, Ошибки, Лимиты запросов, Webhooks.