Быстрый старт

Этот гайд проведёт через полный цикл интеграции: получить API-ключ, подписать запрос, создать депозит и поймать webhook об оплате. Все примеры используют реальную схему подписи, проверенную против серверного гарда.

Базовый адрес в примерах — https://wallet.your-exchange.com. Замените его на base URL вашего инстанса (см. Окружения). Идентификатор ключа api_id в примерах — pk_live_a1b2c3d4, формат orderId — order_1042.

Получите API-ключ

В личном кабинете создайте API-ключ для сайта. Вы получите пару:

api_id — публичный идентификатор ключа (уходит в заголовке X-Api-Id);
api_secret — секрет для подписи (показывается один раз, по сети не передаётся).

Там же задайте callback_url (куда слать webhooks) и, при необходимости, белый список IP.

Сохраните api_secret в защищённом хранилище сразу. Повторно его показать нельзя — только перевыпустить (rotate), что сделает старый секрет недействительным.

Соберите подпись

Каждый запрос подписывается HMAC-SHA256. Сообщение для подписи — X-Timestamp + "." + raw_request_body, ключ — ваш api_secret. Результат — строчный hex. Для запросов без тела (GET) тело — пустая строка, то есть сообщение принимает вид "<timestamp>." (timestamp, затем точка).

import crypto from 'node:crypto';

const BASE_URL  = 'https://wallet.your-exchange.com';
const API_ID    = 'pk_live_a1b2c3d4';
const API_SECRET = process.env.WALLET_API_SECRET; // никогда не хардкодьте

function signedHeaders(body) {
  const ts  = Math.floor(Date.now() / 1000).toString();
  const raw = body ? JSON.stringify(body) : '';          // GET -> ''
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(`${ts}.${raw}`)                              // <ts>.<raw_body>
    .digest('hex');
  return {
    'X-Api-Id': API_ID,
    'X-Timestamp': ts,
    'X-Signature': signature,
    'Content-Type': 'application/json',
  };
}

Подробнее (Python, PHP, разбор ошибок подписи) — Аутентификация.

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

Вызовите POST /v1/public/deposits. В ответ придёт uuid депозита, адрес на оплату (address) и, для memo-сетей, memo.

const body = {
  assetCode: 'USDT_TRC20',
  orderId: 'order_1042',
  expectedAmount: '100.50',
};
const res = await fetch(`${BASE_URL}/v1/public/deposits`, {
  method: 'POST',
  headers: signedHeaders(body),
  body: JSON.stringify(body), // те же байты, что подписали
});
const json = await res.json();
if (!json.ok) throw new Error(`${json.error.code}: ${json.error.message}`);

const { uuid, address, memo } = json.data;
// address — адрес на оплату; memo — для memo-сетей (может быть null)

Ответ (пример)

{
  "ok": true,
  "data": {
    "uuid": "8f1c2e7a-2b1d-4c3e-9a5f-0c1d2e3f4a5b",
    "orderId": "order_1042",
    "assetCode": "USDT_TRC20",
    "network": "TRON",
    "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
    "memo": null,
    "status": "check"
  }
}

orderId и expectedAmount опциональны. Без orderId платформа сгенерирует уникальный. Если expectedAmount опущен — ожидаемой суммой становится минимум актива (minDeposit); чтобы принять любую сумму, передайте expectedAmount: "0". Точный набор полей запроса и ответа — на странице Депозиты.

Покажите адрес клиенту

Отобразите data.address (и data.memo, если он не null). Клиент отправляет крипту на этот адрес. Для memo-сетей оплата без указания memo не будет привязана к депозиту — выводите memo явно и заметно.

Поймайте оплату

Webhook (рекомендуется). Когда депозит подтверждён, платформа отправит на ваш callback_url событие deposit.finalized. Заголовок X-Signature webhook’а подписан вашим callback_secret — обязательно проверьте подпись. См. Webhooks.Polling (запасной вариант). Опросите статус депозита: GET /v1/public/deposits/{uuid} или GET /v1/public/deposits/by-order-id/{orderId}. Поле status дойдёт до paid, paid_over или wrong_amount. См. Статусы депозитов.

cURL — проверка статуса (GET, тело пустое)

TS=$(date +%s)
SIG=$(printf '%s.' "$TS" \
  | openssl dgst -sha256 -hmac "$API_SECRET" -hex | sed 's/^.* //')
curl "$BASE_URL/v1/public/deposits/8f1c2e7a-2b1d-4c3e-9a5f-0c1d2e3f4a5b" \
  -H "X-Api-Id: $API_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG"

Для GET-запроса тело пустое, поэтому подписывается строка "<timestamp>." — timestamp, затем точка.

Дальше

Отправить выплату

Валюты и сети

Webhooks

Коды ошибок

​Дальше

Отправить выплату

Валюты и сети

Webhooks

Коды ошибок

Дальше