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

Выберите сценарий по тому, что должно учитывать приложение: депозиты пользователей, остатки на кошельках или поступления по счетам. Vilna отслеживает адреса под вашим контролем; решение о зачислении пользователю или исполнении заказа принимает ваше приложение.

Используйте ключ проекта с правами, указанными в связанных операциях. Перед каждой изменяющей операцией сохраняйте Idempotency-Key, точное тело запроса и описание действия в вашем приложении. Если исход неизвестен, повторяйте запрос с теми же значениями; см. Идемпотентность. Схемы, примеры запросов и Try it находятся на страницах операций.

• Биржи и крипто-банки: выделение депозитных адресов и внутренний учёт.
• Обменники и платёжные сервисы: сверка остатков на кошельках в поддерживаемых сетях.
• Частные лица и фрилансеры: мониторинг переводов и поступлений по счетам.

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

1. Зарегистрируйте расширенный публичный ключ, затем получите производные адреса для выбранного семейства. Выберите selection.kind: next для следующего свободного индекса или диапазон для явного выделения. Сохраните ID публичного ключа, канонические значения адресов и индексы деривации вместе с привязками к пользователям. При повторе выделения используйте сохранённые ключ и параметры исходного запроса.
2. Создайте webhook-канал с вашим HTTPS URL и payload_version: v2. Сразу сохраните ID, имя и секрет вебхука. Протестируйте канал для выбранного семейства и проверьте подписанную доставку и ответ обработчика 2xx. Принятие теста не подтверждает доставку, а канал сам по себе не подписывается на реальные события.
3. Создайте первую подписку с ID этого канала, выбранным family и условием отправки уведомления (trigger) вида block с after_blocks: 0. Задайте поддерживаемые сети в filters.chain_gids, а при необходимости группу депозитных адресов через filters.address_tag_ids. Сохраните ID и конфигурацию подписки. Она даёт ранний сигнал о включении подходящей транзакции в блок.
4. При необходимости создайте вторую подписку с той же областью отбора и триггером network для более позднего сигнала подтверждения. Сохраните для неё отдельный ключ идемпотентности и исходные параметры запроса. Одна подписка не отправляет обе стадии; раннее включение не означает окончательности.
5. Проверяйте каждую доставку и обрабатывайте повторные ID событий. Сопоставляйте входящие переводы с сохранённой связью адреса и пользователя. Сверяйте текущее состояние транзакции перед окончательным зачислением, после пропуска доставки или реорганизации. Ваша политика подтверждений определяет, когда предварительное зачисление становится доступным пользователю.

Результат - запись о депозите, связанная с адресом, транзакцией и пользователем. См. семантику триггеров и сверку состояния. Тест канала и раннее уведомление не подтверждают завершение депозита.

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

1. Выполните Search balances для одного поддерживаемого family, передав нужные адреса. При необходимости ограничьте результат через chain_gids или asset_gids. Прочитайте все страницы с помощью page и limit: один ответ не является полным снимком средств.
2. Повторите поиск отдельно для каждого используемого поддерживаемого семейства. Запрос evm может охватывать подходящие EVM-сети, но не включает Bitcoin и Tron. При пакетных запросах соблюдайте ограничения операции на число адресов и фильтров.
3. Используйте Summarize balances для итогов проекта в пределах одного семейства, также учитывая пагинацию. Храните asset_gid рядом с каждой суммой, чтобы различать активы и сети. Для расчётов используйте целочисленные строки base, для отображения - formatted.
4. Добавьте канал и подписку по депозитному сценарию для уведомлений об изменениях. Используйте List transactions и чтение балансов для сверки после пропуска доставок. Проверяйте is_sync, прежде чем считать баланс синхронизированным.

Результат собирается из запросов по отдельным семействам с учётом всех страниц. Мониторинг и уведомления не выполняют обмен и не перемещают средства между кошельками.

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

Для выставления счёта клиенту:

1. Выберите уже зарегистрированный адрес и актив для сверки. Прочитайте метаданные токена, чтобы получить decimals перед расчётом суммы.
2. Создайте счёт с этим адресом, asset_gid, положительной целочисленной строкой в базовых единицах в amount и подходящим временем истечения. При повторах сохраняйте время истечения, исходное тело и ключ идемпотентности. В метаданных можно сохранить свой номер заказа.
3. Сохраните ID счёта и читайте его состояние для сверки жизненного цикла. В аутентифицированном ответе amount и confirmed_amount - целочисленные строки в базовых единицах. Сравнивайте их целочисленной арифметикой, а завершение жизненного цикла определяйте по status.
4. Для чтения остатков используйте Search balances отдельно для каждого поддерживаемого семейства, проходя все страницы.

Счёт фиксирует запрос и сверяет поступления в блокчейне на ваш адрес. В разделе Счета описаны недоплаты, истечение срока и различие между статусом жизненного цикла и подтверждённой суммой.

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