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

Копировать

• Копировать для LLM

  Копировать страницу как Markdown для LLM
• Просмотреть как Markdown

  Открыть эту страницу как Markdown
• Открыть в ChatGPT

  Получить анализ от ChatGPT
• Открыть в Claude

  Получить инсайты от Claude
• Подключиться к Cursor

  Установить сервер MCP в Cursor
• Подключиться к VS Code

  Установить сервер MCP в VS Code

На этой странице описаны ключевые доменные концепции, с которыми вы столкнётесь при работе с Vilna API. Каждый раздел объясняет, что представляет собой концепция, как она идентифицируется и когда используется. Полное описание эндпоинтов см. в справочнике Platform API.

Блокчейны и идентификаторы сетей (CAIP-2)

Vilna идентифицирует каждый блокчейн с помощью глобального идентификатора (GID) стандарта CAIP-2. Формат: namespace:reference — например, eip155:1 для основной сети Ethereum или eip155:137 для Polygon.

Получить список всех поддерживаемых сетей можно с помощью GET /blockchains. Каждая сеть может быть активирована или деактивирована в вашем пространстве имён. Мониторинг ведётся только для активных сетей.

Распространённые GID сетей:

Полную справку по стандарту CAIP см. в разделе Стандарты CAIP.

Адреса

Адрес представляет блокчейн-аккаунт, который вы хотите отслеживать. Существует два способа добавления адресов:

Внешние адреса — это самостоятельные аккаунты, которые вы импортируете по отдельности с помощью POST /addresses/external. Вы указываете значение адреса, chainFamily (семейство сетей, которое автоматически привязывает адрес ко всем сетям этого семейства) и необязательную метку.

HD-производные адреса генерируются из публичного ключа (см. следующий раздел). Эти адреса создаются последовательно и автоматически ставятся на мониторинг после генерации.

Поддерживаемые форматы адресов:

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

Получение адреса из публичного ключа

Если у вас есть необработанный публичный ключ и вам нужен соответствующий блокчейн-адрес, используйте POST /addresses/external/resolve. Этот эндпоинт вычисляет адрес из публичного ключа, создает внешний адрес и возвращает его. Публичный ключ используется только для деривации и не сохраняется. Если адрес с вычисленным значением уже существует, возвращается существующий.

curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/addresses/external/resolve" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5",
    "addressFormat": "evm"
  }'

Поле publicKey принимает hex-кодированные ключи secp256k1 (сжатые или несжатые, с опциональным префиксом 0x) для форматов EVM, Tron и Bitcoin, а также base58-кодированные ключи ed25519 для Solana. Также можно передать необязательные поля label и meta, как и при создании внешнего адреса напрямую.

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

Получить список всех адресов можно с помощью GET /addresses.

Публичные ключи и HD-кошельки

Если вы управляете HD-кошельком, вы можете импортировать его расширенный публичный ключ (xPub, yPub или zPub) с помощью POST /public_keys. Vilna использует пути деривации BIP-32 / BIP-44 / BIP-49 / BIP-84 для детерминированной генерации дочерних адресов.

После импорта публичного ключа вызовите POST /public_keys/{public_key_id}/addresses/next для генерации следующего неиспользованного адреса в последовательности деривации. Новый адрес автоматически регистрируется для мониторинга в сетях, связанных с публичным ключом.

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

Токены и активы (CAIP-19)

Каждый токен или монета идентифицируется с помощью идентификатора актива CAIP-19. Формат: chain_gid/asset_namespace:asset_reference.

Нативные токены используют пространство имён slip44:

eip155:1/slip44:60          - ETH в сети Ethereum
eip155:56/slip44:60         - BNB в сети BSC

Контрактные токены используют пространство имён, соответствующее стандарту токена:

eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48   - USDC в сети Ethereum
eip155:56/erc20:0x55d398326f99059fF775485246999027B3197955    - USDT в сети BSC

Метаданные токена (название, символ, десятичные знаки) включены в поле references.tokens ответов API.

Транзакции и события

Транзакция представляет подтверждённую или ожидающую операцию в блокчейне. Получить список транзакций по всем вашим адресам можно с помощью GET /transactions.

Каждая транзакция содержит одно или несколько канонических событий, описывающих произошедшее:

События — это строительные блоки для понимания действий транзакции. Например, одна транзакция обмена может породить несколько событий transfer и событие fee.

Активность

Лента активности (GET /activity) — это представление более высокого уровня, показывающее изменения балансов на отслеживаемых адресах. Каждая запись включает:

• direction — in (получено) или out (отправлено)
• amount — какая сумма была получена или потеряна (см. раздел «Суммы» ниже)
• token — какой актив изменился
• address — какой из ваших адресов был затронут

Используйте ленту активности, когда вам нужен простой обзор «что пришло, что ушло» без разбора необработанных событий транзакций.

Балансы

Запросите текущие активы ваших адресов с помощью GET /balances (все адреса) или GET /addresses/{address}/balances (один адрес). Ответ содержит список каждого токена с его суммой.

Балансы обновляются автоматически по мере индексации новых транзакций.

Суммы

Все денежные значения в API возвращаются в виде объекта с двумя полями:

{
  "base": "1000000",
  "formatted": "1.0"
}

Всегда используйте base для арифметики и хранения. Используйте formatted только для отображения.

Каналы уведомлений

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

Вебхук — Vilna отправляет HTTP POST на ваш URL при каждом релевантном событии. Запрос будет включать заголовки с HMAC-SHA256 подписью для верификации (запланировано). Подробнее о подписях см. в разделе Аутентификация.

Telegram — События доставляются в чат Telegram.

Создайте канал с помощью POST /notification_channels и протестируйте его через POST /notification_channels/{notification_channel_id}/actions/test.

Каналы глобальны для вашего пространства имён. Все отслеживаемые адреса доставляют события во все активные каналы.

Паттерн references

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

Для ответа с одним элементом:

{
  "item": { "...": "..." },
  "references": {
    "tokens": { "eip155:1/slip44:60": { "name": "ETH", "...": "..." } },
    "blockchains": { "eip155:1": { "name": "Ethereum", "...": "..." } },
    "addresses": { "eip155:1:0x742d...": { "...": "..." } }
  }
}

Для ответа со списком:

{
  "items": [ "..." ],
  "meta": {
    "limit": 30,
    "page": 1,
    "total": 142,
    "total_pages": 5
  },
  "references": { "...": "..." }
}

Объект meta предоставляет информацию о пагинации. Используйте параметры запроса limit и page для навигации по страницам.

Ошибки

API возвращает ошибки в формате RFC 7807 application/problem+json:

{
  "type": "https://docs.vilna.io/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "fields": [
    { "name": "address.value", "reason": "must be a valid blockchain address" }
  ]
}

Массив fields точно указывает, какие поля не прошли валидацию и почему.

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