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

Копировать

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

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

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

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

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

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

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

В большинстве руководств первый рабочий ответ скрыт за кучей подготовки: регистрация, SDK, вебхуки. Здесь иначе. Один curl-вызов подтверждает, что API работает у вас, дальше добавляем возможности по одной. TypeScript SDK появится в самом конце как опциональное удобство.

Получите API-ключ

1. Зарегистрируйтесь на app.vilna.io, создайте рабочее пространство и проект внутри него. У каждого проекта свой набор адресов, балансов и событий.
2. Сгенерируйте API-ключ в настройках проекта.
3. Сохраните его в переменной окружения, чтобы примеры ниже работали как есть:

export VILNA_API_KEY="your-api-key"

Проверка работоспособности: список блокчейнов

Ваш "hello world" - один запрос, который проверяет ключ и показывает, что видит API.

curl "https://api.vilna.io/v1/blockchains" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

В ответ придут поддерживаемые сети с CAIP-2 идентификаторами, именами и флагами возможностей:

{
  "items": [
    { "gid": "eip155:1", "name": "ethereum", "is_active": true },
    { "gid": "eip155:56", "name": "bsc", "is_active": true },
    { "gid": "bip122:000000000019d6689c085ae165831e93", "name": "bitcoin", "is_active": true }
  ],
  "meta": { "page": 1, "total": 31 }
}

Если такой ответ пришёл - на этом настройка завершена. Всё ниже добавляет возможности по одной, но ключ уже работает.

Справочник: GET /blockchains.

Дальше: мониторинг адреса

Зарегистрируйте адрес, который хотите отслеживать. API отслеживает его сразу во всех сетях выбранного семейства - один вызов покрывает все EVM-сети, все Bitcoin-подобные цепи и так далее.

curl -X POST "https://api.vilna.io/v1/addresses/external" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
    "chainFamily": "evm",
    "label": "Treasury"
  }'

chainFamily принимает значения evm, bitcoin, solana или tron. Ответ возвращает ID адреса и список сетей, в которых он зарегистрирован. С этого момента Vilna индексирует историю адреса и отслеживает новые транзакции в реальном времени.

Справочник: POST /addresses/external. О различии между внешними и HD-адресами см. Основные концепции.

Дальше: чтение балансов и истории

Когда адрес зарегистрирован, два read-only эндпоинта закрывают большинство задач.

Текущие балансы по всем отслеживаемым адресам:

curl "https://api.vilna.io/v1/balances?limit=10" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

У каждой записи есть GID актива и структурированная сумма с двумя полями: base (целочисленное значение в виде строки) и formatted (человекочитаемое). Используйте base для расчётов, formatted - для отображения.

Недавняя активность - изменения балансов по всем адресам, с пагинацией:

curl "https://api.vilna.io/v1/activity?limit=10" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

В каждой записи есть направление (in/out), актив и дельта. Удобно для проверки "было ли что-то на адресах за последний час" без сканирования всех транзакций.

Справочники: GET /balances, GET /activity. Подробнее о формате сумм: Основные концепции - Суммы.

Дальше: получение событий

Опрос подходит для простых случаев, но в продакшене обычно нужно получать события сразу. Vilna отправит событие на ваш эндпоинт сразу после подтверждения в блокчейне.

Создайте вебхук-канал, указав свой HTTP-эндпоинт:

curl -X POST "https://api.vilna.io/v1/channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "config": {
      "kind": "webhook",
      "url": "https://your-app.example.com/vilna-webhook"
    }
  }'

Сохраните id канала из ответа в переменную окружения, затем отправьте тестовое событие, чтобы убедиться, что эндпоинт доступен:

export CHANNEL_ID="<id-из-ответа>"
curl -X POST "https://api.vilna.io/v1/channels/${CHANNEL_ID}/actions/test" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Если эндпоинт ответил 2xx - всё готово. Vilna будет отправлять реальные события на этот URL при любой активности на отслеживаемых адресах.

Справочники: POST /channels, POST /channels/{channel_id}/actions/test. Схема payload и жизненный цикл каналов: Каналы уведомлений. Типы событий: События и мониторинг.

Использование SDK (опционально)

Если у вас TypeScript-стек, официальный SDK даёт типизированные клиенты, сгенерированные из OpenAPI-спецификации.

npm install @vilna/sdk

import { createVilnaClient } from "@vilna/sdk";

const client = createVilnaClient({
  apiKey: process.env.VILNA_API_KEY!,
});

const { data, error } = await client.GET("/blockchains");

Каждый вызов возвращает { data, error } с полной типобезопасностью. Полное руководство по SDK: TypeScript SDK. Для других языков сгенерируйте клиент из OpenAPI-спецификации.

Дальнейшие шаги