Перейти к содержанию

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

Сквозное прохождение ключевых вызовов API: создать хранилище, выпустить кошелёк, проверить баланс, оценить комиссию, отправить вывод и отследить его.

Необходимое

Понадобится Key ID и Secret. Их создаёт администратор вашей организации в админ-панели: Settings → API Keys. Подробности про подпись HMAC-SHA256 — в Аутентификации.

Аутентификация

Каждому запросу нужны три заголовка с HMAC-подписью. Полный алгоритм и примеры кода — в Аутентификации.

В примерах ниже $HEADERS означает:

-H "X-API-Key: $API_KEY_ID" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Signature: $SIGNATURE"

Шаг 1: Создание хранилища

Хранилище представляет конечного клиента, чьи активы будут на хранении.

curl -X POST {{baseUrl}}/vaults \
  $HEADERS \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "cust_12345",
    "name": "Alice Johnson"
  }'

Ответ (201):

{
  "id": "d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890",
  "externalId": "cust_12345",
  "name": "Alice Johnson",
  "metadata": {},
  "status": "Active",
  "createdAt": "2026-02-22T10:00:00Z"
}

Запомните id хранилища — он понадобится при выпуске кошельков.

Шаг 2: Выпуск кошелька

Выпустите кошелёк в хранилище. Понадобятся vault ID из шага 1 и asset ID (доступен в админ-панели в разделе Assets).

curl -X POST {{baseUrl}}/vaults/d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890/wallets \
  $HEADERS \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "label": "Primary ETH Wallet"
  }'

Ответ (201):

{
  "id": "f4a5b6c7-d8e9-0123-fabc-456789abcdef",
  "vaultId": "d1e2f3a4-b5c6-7890-d1e2-f3a4b5c67890",
  "assetId": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
  "assetName": "Ethereum",
  "assetSymbol": "ETH",
  "network": "Ethereum",
  "label": "Primary ETH Wallet",
  "depositAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "depositTag": null,
  "status": "Active",
  "createdAt": "2026-02-22T10:30:00Z"
}

depositAddress — это on-chain адрес для приёма средств. Передайте его конечному клиенту для пополнения.

Шаг 3: Проверка баланса

curl {{baseUrl}}/wallets/f4a5b6c7-d8e9-0123-fabc-456789abcdef/balance $HEADERS

Ответ (200):

{
  "available": "1.5000",
  "pending": "0.2500",
  "locked": "0.0000",
  "total": "1.7500"
}
Поле Описание
available Доступно для вывода или перевода.
pending Поступления, ещё не подтверждённые в сети.
locked Средства, зарезервированные под транзакции в полёте.
total Сумма available + pending + locked.

Шаг 4: Оценка комиссии

Перед отправкой вывода оцените сетевую комиссию.

curl -X POST {{baseUrl}}/transactions/estimate-fee \
  $HEADERS \
  -H "Content-Type: application/json" \
  -d '{
    "sourceWalletId": "f4a5b6c7-d8e9-0123-fabc-456789abcdef",
    "destinationAddress": "0xABC1234567890DEF1234567890abcDeF12345678",
    "amount": "0.5000"
  }'

Ответ (200):

{
  "low": {
    "networkFee": "0.000049051962603",
    "gasPrice": "1.075798425",
    "gasLimit": "21000",
    "feePerByte": null
  },
  "medium": {
    "networkFee": "0.000049051962603",
    "gasPrice": "1.169768470",
    "gasLimit": "21000",
    "feePerByte": null
  },
  "high": {
    "networkFee": "0.000056458147116",
    "gasPrice": "2.369911802",
    "gasLimit": "21000",
    "feePerByte": null
  }
}

Три уровня комиссии — low, medium, high — позволяют предложить клиенту компромисс между приоритетом и стоимостью. В каждом уровне есть networkFee (оценка общей комиссии в нативном активе — единственное поле для отображения) и зависящие от сети входные параметры расчёта:

Поле Когда возвращается
gasPrice / gasLimit EVM-сети (ETH, USDT-ERC20 и др.) — networkFee = gasPrice × gasLimit в нативном активе
feePerByte UTXO-сети (BTC) — комиссия за байт подписанной транзакции

Выберите уровень на клиенте (обычно по умолчанию medium) и передайте feeLevel: "Low" \| "Medium" \| "High" в запросе вывода ниже. Если поле не указать, вывод по умолчанию использует medium.

Шаг 5: Отправка вывода

Создание вывода на внешний адрес.

Idempotency-Key обязателен

Каждый запрос, перемещающий средства (/transactions/withdraw, /transactions/transfer), требует заголовок Idempotency-Key. Генерируйте уникальное значение на каждую логическую операцию (UUID, ULID или стабильный бизнес-идентификатор — до 64 символов, [A-Za-z0-9_-]). При повторе того же запроса с тем же ключом вернётся первоначальный ответ — повторного вывода не произойдёт. Тот же ключ с другим телом запроса даёт 400 — это почти всегда ошибка клиента.

curl -X POST {{baseUrl}}/transactions/withdraw \
  $HEADERS \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceWalletId": "f4a5b6c7-d8e9-0123-fabc-456789abcdef",
    "destinationAddress": "0xABC1234567890DEF1234567890abcDeF12345678",
    "amount": "0.5000",
    "note": "Ежемесячный казначейский перевод"
  }'

Ответ (201):

{
  "id": "b6c7d8e9-f0a1-2345-bcde-6789abcdef01",
  "type": "Withdrawal",
  "status": "Submitted",
  "sourceWalletId": "f4a5b6c7-d8e9-0123-fabc-456789abcdef",
  "assetSymbol": "ETH",
  "network": "Ethereum",
  "amount": "0.5000",
  "note": "Ежемесячный казначейский перевод",
  "createdAt": "2026-02-22T11:15:00Z"
}

Шаг 6: Отслеживание транзакции

Опрашивайте эндпоинт транзакции или подключите вебхуки для уведомлений в реальном времени.

curl {{baseUrl}}/transactions/b6c7d8e9-f0a1-2345-bcde-6789abcdef01 $HEADERS

Статусы транзакции

Статус Описание
Submitted Запрос принят платформой.
PendingSignature Ожидает подписи в кастоди-бэкенде.
Broadcasting Подписана и отправлена в сеть.
Confirming В сети, ожидает подтверждений.
Completed Полностью подтверждена и зачислена.
Failed Транзакция не удалась (см. failureReason).
Cancelled Транзакция отменена до исполнения.

Бонус: внутренний перевод

Перевод между двумя кошельками в одной организации (одинаковый актив). Правило Idempotency-Key то же — см. предупреждение выше.

curl -X POST {{baseUrl}}/transactions/transfer \
  $HEADERS \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceWalletId": "f4a5b6c7-d8e9-0123-fabc-456789abcdef",
    "destinationWalletId": "11223344-5566-7788-99aa-bbccddeeff00",
    "amount": "0.2500",
    "note": "Пополнение пользовательского кошелька"
  }'

Внутренние переводы исполняются мгновенно и без сетевых комиссий.

Дальше