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

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

Начните работу с Vilna API примерно за 10 минут. К концу этого руководства вы настроите мониторинг блокчейн-адреса, подключите вебхук-уведомления и запросите балансы — всё на рабочих примерах кода.

Прежде чем начать

Вам потребуется пространство имён (namespace) и API-ключ Vilna. Запросите доступ по адресу support@vilna.io.

Предварительные требования

  • Node.js 18+ (для примеров на TypeScript SDK) или curl

Шаг 1: Получите доступ к API

Каждое рабочее пространство получает собственное пространство имён (namespace). Ваш базовый URL:

https://{namespace}.vilna.app

Vilna аутентифицирует запросы с помощью заголовка X-Api-Key. Сохраните ключ в переменной окружения, чтобы приведенные ниже примеры работали без изменений:

export VILNA_NAMESPACE="demo"
export VILNA_API_KEY="your-api-key"

Шаг 2: Установите SDK

npm install @vilna/sdk

Инициализируйте клиент:

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

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

SDK использует openapi-fetch под капотом, поэтому каждый вызов возвращает { data, error } с полной типобезопасностью.

Предпочитаете curl?

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

Шаг 3: Проверьте доступные блокчейны

Перед добавлением адреса необходимо узнать, какие сети активны. Получите их список с помощью GET /blockchains.

curl "https://${VILNA_NAMESPACE}.vilna.app/blockchains" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Ответ (сокращённо):

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

Списковые эндпоинты возвращают items, meta (пагинация) и references (связанные объекты). Подробнее об обёртке ответов см. в Основных концепциях.

Шаг 4: Добавьте адрес для мониторинга

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

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

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

Шаг 5: Настройте вебхук-уведомления

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

curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_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",
      "headers": {}
    }
  }'
Сохраните секрет вебхука

В ответе содержится поле secret. Сохраните его немедленно — оно отображается только один раз. Оно понадобится для проверки подписи вебхуков (когда будет доступно).

Отправьте тестовое событие, чтобы убедиться в работоспособности канала. Замените ${CHANNEL_ID} на id из ответа выше.

curl -X POST "https://${VILNA_NAMESPACE}.vilna.app/notification_channels/${CHANNEL_ID}/actions/test" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Шаг 6: Проверьте балансы

Запросите все балансы по отслеживаемым адресам с помощью GET /balances или для конкретного адреса — GET /addresses/{address}/balances.

curl "https://${VILNA_NAMESPACE}.vilna.app/balances?limit=30&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Ответ (сокращённо):

{
  "items": [
    {
      "asset_gid": "eip155:1/slip44:60",
      "amount": { "base": "1500000000000000000", "formatted": "1.5" }
    }
  ],
  "references": {
    "tokens": {
      "eip155:1/slip44:60": { "symbol": "ETH", "decimals": 18 }
    }
  }
}

Суммы возвращаются в структурированном формате с машиночитаемым значением base и человекочитаемым значением formatted. Подробнее см. в разделе Основные концепции.

Шаг 7: Просмотрите историю транзакций

Получите ленту операций, влияющих на балансы, по всем вашим адресам.

curl "https://${VILNA_NAMESPACE}.vilna.app/activity?limit=10&page=1" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Ответ (сокращённо):

{
  "items": [
    {
      "direction": "in",
      "asset_gid": "eip155:1/erc20:0xdAC17...",
      "delta": { "base": "250000000", "formatted": "250.0" }
    }
  ]
}

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

Теперь у вас есть рабочая интеграция, которая отслеживает адрес, получает вебхук-события и запрашивает балансы. Далее:

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

Блокчейны, адреса, токены, суммы и паттерн references

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

Управление API-ключами, проверка подписи вебхуков и лучшие практики безопасности

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

Обнаружение депозитов, отслеживание портфеля, управление HD-кошельками

Platform API

Полный каталог эндпоинтов со схемами запросов и ответов

Management API

Управление рабочими пространствами, проектами и ключами

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