Перейти к содержимому
Последнее обновление

Паттерны интеграции

Это руководство описывает пять распространённых сценариев интеграции. Каждый паттерн включает цель, используемые API-вызовы и последовательность операций. Полные схемы запросов и ответов см. в справочнике Platform API.

1. Система обнаружения депозитов

Цель: Отслеживать депозитные адреса клиентов и реагировать на поступление средств в реальном времени.

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

Как это работает

  1. Импортируйте публичный ключ вашего HD-кошелька (POST /public_keys).
  2. Сгенерируйте уникальный депозитный адрес для каждого клиента (POST /public_keys/{public_key_id}/addresses/next).
  3. Создайте вебхук-канал уведомлений (POST /notification_channels).
  4. При поступлении средств Vilna доставляет вебхук-событие на ваш сервер.
  5. Ваш сервер проверяет подпись, сопоставляет адрес с клиентом и зачисляет средства на его счет.

Последовательность

БлокчейнVilnaВаш серверКлиентБлокчейнVilnaВаш серверКлиентЗапрос адреса для пополненияPOST /public_keys/{public_key_id}/addresses/nextНовый адресПоказать адресОтправка средствОбнаружение транзакцииWebhook POSTПроверка подписиЗачисление на счётДепозит подтверждён

Основной код

# 1. Импорт xPub
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/public_keys" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...",
    "label": "Customer Deposits",
    "derivation_path": "m/84h/0h/0h"
  }'

# 2. Генерация следующего адреса для нового клиента
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/public_keys/{pubkey_id}/addresses/next" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

# 3. Создание вебхук-канала
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deposit Webhooks",
    "config": {
      "kind": "webhook",
      "url": "https://your-app.example.com/deposits/webhook",
      "headers": {}
    }
  }'

Рекомендации по проектированию

  • Используйте заголовок X-Webhook-Idempotency-Key для предотвращения двойного зачисления при повторных доставках.
  • Храните связь между сгенерированными адресами и идентификаторами клиентов в вашей базе данных.
  • Проверяйте подписи вебхуков перед обработкой (когда будет доступно). См. Аутентификация.

2. Трекер портфеля

Цель: Показать пользователям агрегированный обзор их активов и недавней активности по нескольким сетям.

Когда использовать: Дашборды кошельков, бухгалтерские инструменты и продукты для аналитики портфеля.

Как это работает

  1. Импортируйте каждый адрес пользователя с помощью POST /addresses/external.
  2. Запрашивайте GET /balances для текущих активов.
  3. Запрашивайте GET /activity для недавних изменений баланса.
  4. Используйте references.tokens и references.blockchains из ответа для отображения названий токенов и информации о сетях без дополнительных запросов.

Последовательность

VilnaВаше приложениеVilnaВаше приложениеPOST /addresses/external (для каждого адреса)Адрес созданGET /balancesСписок балансовGET /activity?limit=50Лента активностиРендер дашборда

Основной код

# Добавление адреса
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/addresses/external" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "chainFamily": "evm",
    "label": "Main Wallet"
  }'

# Получение балансов
curl "https://${VILNA_NAMESPACE}.vilna.app/balances?limit=30&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

# Получение недавней активности
curl "https://${VILNA_NAMESPACE}.vilna.app/activity?limit=50&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Рекомендации по проектированию

  • Используйте значение meta.total_pages для реализации пагинации или бесконечной прокрутки.
  • Объект references в каждом ответе устраняет необходимость в отдельных запросах токенов или сетей.
  • Для обновлений в реальном времени комбинируйте опрос с вебхук-каналом.

3. Управление HD-кошельками

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

Когда использовать: Кастодиальные платформы, горячие кошельки бирж и любые системы, генерирующие адреса из мастер-публичного ключа.

Как это работает

  1. Импортируйте расширенный публичный ключ (POST /public_keys) с путем деривации.
  2. Когда нужен новый адрес, вызовите POST /public_keys/{public_key_id}/addresses/next.
  3. Vilna отслеживает индекс деривации и немедленно начинает мониторинг нового адреса.
  4. Запрашивайте балансы и транзакции по всем производным адресам с помощью GET /balances и GET /transactions.

Последовательность

VilnaВаш серверVilnaВаш серверPOST /public_keys (xpub + путь деривации)ID публичного ключаPOST /public_keys/{public_key_id}/addresses/nextПроизводный адресGET /addressesСписок адресовGET /balancesАгрегированные балансы

Основной код

# Импорт расширенного публичного ключа
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/public_keys" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "xpub6BosfCnifzxRT1QKLpFfcUrgWmLqoJcGt...",
    "label": "Exchange Hot Wallet",
    "derivation_path": "m/44h/60h/0h"
  }'

# Генерация адресов по мере необходимости
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/public_keys/{pubkey_id}/addresses/next" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Рекомендации по проектированию

  • Vilna поддерживает пути деривации BIP-32, BIP-44, BIP-49 и BIP-84.
  • Вы можете импортировать ключи xPub, yPub или zPub в зависимости от нужного формата адреса (legacy, SegWit, native SegWit).
  • Публичный ключ никогда не передаётся из Vilna в незашифрованном виде — приватные ключи никогда не требуются.

4. Мультичейн-мониторинг

Цель: Отслеживать адреса в нескольких блокчейнах и фильтровать активность по сети.

Когда использовать: Мультичейн-кошельки, кросс-чейн аналитические дашборды и инструменты комплаенс-мониторинга.

Как это работает

  1. Проверьте доступные блокчейны (GET /blockchains).
  2. Зарегистрируйте адреса с указанием chainFamily для мониторинга во всех сетях этого семейства.
  3. Запрашивайте GET /activity или GET /transactions и фильтруйте по сети при необходимости.
  4. Используйте references.blockchains для отображения метаданных сети.

Последовательность

VilnaВаше приложениеVilnaВаше приложениеGET /blockchainsСписок сетейPOST /addresses/external (chainFamily: "evm")Адрес созданGET /activityЛента активности (с информацией о сетях)Фильтрация по сети

Основной код

# Список поддерживаемых сетей
curl "https://${VILNA_NAMESPACE}.vilna.app/blockchains" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

# Мониторинг адреса во всех EVM-сетях (Ethereum, Polygon, Arbitrum и др.)
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/addresses/external" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B",
    "chainFamily": "evm",
    "label": "Multi-chain Wallet"
  }'

# Получение активности по всем сетям
curl "https://${VILNA_NAMESPACE}.vilna.app/activity?limit=30&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Рекомендации по проектированию

  • EVM-адреса (с префиксом 0x) можно отслеживать во всех EVM-совместимых сетях одним вызовом POST /addresses/external, указав chainFamily: "evm".
  • Не-EVM сети (Bitcoin, Solana, Tron) требуют форматов адресов, специфичных для сети.
  • Каждая сеть индексируется независимо, поэтому один адрес может иметь разные балансы и историю транзакций в разных сетях.

5. Оповещения о транзакциях

Цель: Получать уведомления в реальном времени через несколько каналов при блокчейн-активности на отслеживаемых адресах.

Когда использовать: Мониторинг казначейства, комплаенс-оповещения, операционные дашборды и системы дежурства.

Как это работает

  1. Добавьте адреса для наблюдения (POST /addresses/external).
  2. Создайте вебхук-канал для бэкенда (POST /notification_channels с kind: "webhook").
  3. Опционально создайте Telegram-канал для операторов (POST /notification_channels с kind: "telegram").
  4. Протестируйте оба канала (POST /notification_channels/{notification_channel_id}/actions/test).
  5. Все события по отслеживаемым адресам доставляются в каждый активный канал.

Последовательность

TelegramВаш серверVilnaБлокчейнTelegramВаш серверVilnaБлокчейнОба канала получают одно событиеНовая транзакцияWebhook POSTСообщение в Telegram

Основной код

# Создание вебхук-канала
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Alerts",
    "config": {
      "kind": "webhook",
      "url": "https://your-app.example.com/alerts/webhook",
      "headers": {}
    }
  }'

# Создание Telegram-канала
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ops Team Telegram",
    "config": {
      "kind": "telegram",
      "bot_token": "987654321:ABCdefGHIjklMNOpqrsTUVwxyz123456789",
      "chat_id": -1001234567890,
      "language": "en",
      "thread_id": 0
    }
  }'

# Тестирование вебхук-канала
curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_channels/{channel_id}/actions/test" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Рекомендации по проектированию

  • Все активные каналы получают все события. Используйте серверную фильтрацию в обработчике вебхука для маршрутизации или подавления событий.
  • Вебхук-каналы включают HMAC-подписи для верификации (запланировано). Telegram-каналы верифицируются через процесс настройки Telegram-бота.
  • Для счетов с высокой стоимостью активов используйте оба канала, чтобы операторы получали Telegram-оповещения, а бэкенд обрабатывал события автоматически.

Дополнительные материалы

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

Настройте первую интеграцию от начала до конца

Основные концепции

Адреса, токены, суммы и паттерн references

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

Использование API-ключей и проверка подписи вебхуков

Platform API

Полная документация эндпоинтов со схемами запросов и ответов

Предыдущая страница
Следующая страница