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

Обзор

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

Базовые понятия

Платформа построена вокруг пяти понятий. Прежде чем писать код, разберитесь с каждым.

Хранилище (vault)

Хранилище — контейнер верхнего уровня для активов одного конечного клиента.

  • Одно хранилище на клиента.
  • Содержит один или несколько кошельков (по одному на актив).
  • Граница для отчётности по балансам и аудиту.

Создаётся через POST /vaults.

Кошелёк (wallet)

Кошелёк хранит баланс по одному активу (BTC, ETH, USDT и т. д.) внутри хранилища. У каждого кошелька есть один или несколько адресов для приёма средств в нативной сети актива.

  • Создаётся через POST /vaults/{vaultId}/wallets.
  • Имеет собственный баланс.
  • Имеет адрес для пополнения, который вы передаёте клиенту.

Транзакция

Транзакция — любое движение средств с участием кошелька. Три типа:

Тип Триггер On-chain?
Пополнение Средства поступают на адрес кошелька. Да (определяется автоматически).
Внутренний перевод POST /transactions/transfer между двумя подконтрольными кошельками. Нет.
Вывод POST /transactions/withdraw на внешний адрес. Да.

Транзакции проходят через статусы: Submitted → PendingSignature → Broadcasting → Confirming → Completed (или Failed / Cancelled).

Адресная книга

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

Управляется через эндпоинты /address-book.

Вебхук

Один HTTPS-эндпоинт, который вы регистрируете для получения уведомлений о событиях в реальном времени: зачисление пополнений, подтверждение выводов, изменения адресной книги, изменения статуса хранилища.

Каждая доставка содержит заголовок X-Webhook-Signature (HMAC-SHA256 от тела с использованием вашего секрета), что позволяет проверить подлинность.

Управляется через эндпоинты /webhooks/* — см. Интеграция вебхуков.

Типичный сценарий интеграции

Первый сквозной поток, который вы построите:

  1. Получите API-ключ у администратора своей организации. Ключ несёт набор скоупов (vaults:write, wallets:create, …) и может ограничивать доступ списком IP-адресов.
  2. Создайте хранилище на каждого конечного клиента (POST /vaults).
  3. Получите список активов, доступных вашей организации.
  4. Выпустите кошельки в каждом хранилище под нужные клиенту активы (POST /vaults/{vaultId}/wallets).
  5. Передайте клиенту адрес кошелька для пополнения.
  6. Настройте вебхук, чтобы узнавать о пополнениях в реальном времени, а не опросом.
  7. Для внешних выводов сначала добавьте адрес назначения в адресную книгу, затем вызовите POST /transactions/withdraw.

Аутентификация, скоупы, окружения

  • Все запросы подписываются алгоритмом HMAC-SHA256. Три обязательных заголовка (X-API-Key, X-Timestamp, X-Signature). Подробнее — в Аутентификации.
  • Каждому ключу выдаются скоупы. Запрос к эндпоинту, требующему скоуп, которого у ключа нет, возвращает 403.
  • Доступны два окружения — sandbox и production — с раздельными ключами (..._test_… и ..._live_…). Выбирайте нужное окружение в Справочнике API при вызовах со страницы.

Дальше