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

Руководство по быстрому старту

Начните работу с Vilna всего за 15 минут. Это руководство проведет вас через настройку мониторинга первого адреса и получение уведомлений через webhook в реальном времени.

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

Перед началом вам понадобится:

  • Учетная запись Vilna с API ключом
  • Публично доступный webhook endpoint (или используйте ngrok для тестирования)
  • Базовые знания REST API

Шаг 1: Получите API ключ

  1. Зарегистрируйтесь для получения учетной записи Vilna
  2. Перейдите в Настройки → API Ключи
  3. Создайте новый API ключ и сохраните его в безопасном месте
export VILNA_API_KEY="ваш_api_ключ_здесь"

Шаг 2: Добавьте первый адрес

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

Вариант А: Импорт одного адреса

curl -X POST https://api.vilna.io/v1/addresses \
-H "Authorization: Bearer $VILNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
  "blockchain_gid": "eip155:1",
  "label": "Казначейский кошелек"
}'

Ответ:

{
  "id": "addr_550e8400-e29b-41d4-a716-446655440000",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
  "blockchain_gid": "eip155:1",
  "label": "Казначейский кошелек",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Вариант Б: Импорт расширенного публичного ключа

curl -X POST https://api.vilna.io/v1/xpubs \
-H "Authorization: Bearer $VILNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "xpub": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...",
  "blockchain_gid": "eip155:1",
  "label": "Депозиты клиентов"
}'

Затем генерируйте адреса по мере необходимости:

curl -X POST https://api.vilna.io/v1/addresses/generate/xpub/next \
-H "Authorization: Bearer $VILNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "xpub_id": "xpub_660e8400-e29b-41d4-a716-446655440001",
  "label": "Клиент #001"
}'

Шаг 3: Создайте канал уведомлений

Настройте webhook канал для получения уведомлений в реальном времени:

curl -X POST https://api.vilna.io/v1/channels \
-H "Authorization: Bearer $VILNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "type": "webhook",
  "name": "Мой Webhook",
  "webhook_url": "https://your-app.com/webhook",
  "webhook_secret": "сгенерируйте-случайный-32-символьный-секрет"
}'

Ответ:

{
  "id": "chan_770e8400-e29b-41d4-a716-446655440002",
  "type": "webhook",
  "name": "Мой Webhook",
  "webhook_url": "https://your-app.com/webhook",
  "status": "active",
  "created_at": "2024-01-15T10:31:00Z"
}

Шаг 4: Создайте подписку

Свяжите ваш адрес с webhook каналом:

curl -X POST https://api.vilna.io/v1/subscriptions \
-H "Authorization: Bearer $VILNA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "channel_id": "chan_770e8400-e29b-41d4-a716-446655440002",
  "address_ids": ["addr_550e8400-e29b-41d4-a716-446655440000"],
  "event_types": ["transaction.confirmed"],
  "min_confirmations": 1
}'

Ответ:

{
  "id": "sub_880e8400-e29b-41d4-a716-446655440003",
  "channel_id": "chan_770e8400-e29b-41d4-a716-446655440002",
  "address_ids": ["addr_550e8400-e29b-41d4-a716-446655440000"],
  "event_types": ["transaction.confirmed"],
  "min_confirmations": 1,
  "status": "active",
  "created_at": "2024-01-15T10:32:00Z"
}

Шаг 5: Реализуйте обработчик webhook

Создайте простой обработчик webhook для обработки входящих уведомлений:

Пример на Node.js

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

const WEBHOOK_SECRET = 'ваш-webhook-секрет';

app.post('/webhook', (req, res) => {
  // Проверка подписи
  const signature = req.headers['x-vilna-signature'];
  const timestamp = req.headers['x-vilna-timestamp'];
  const eventId = req.headers['x-vilna-event-id'];
  
  const payload = `${timestamp}.${eventId}.${JSON.stringify(req.body)}`;
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Неверная подпись');
  }
  
  // Обработка события
  const event = req.body;
  console.log(`Получено событие ${event.event_type}:`, event.data);
  
  switch (event.event_type) {
    case 'transaction.confirmed':
      // Обработка подтвержденной транзакции
      console.log(`Транзакция подтверждена: ${event.data.amount} ${event.data.asset_name}`);
      // Обновите базу данных, начислите средства пользователю и т.д.
      break;
    
    case 'transaction.pending':
      // Обработка ожидающей транзакции
      console.log(`Обнаружена ожидающая транзакция`);
      break;
  }
  
  // Всегда быстро возвращайте 200 OK
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Обработчик webhook слушает порт 3000');
});

Пример на Python

from flask import Flask, request
import hmac
import hashlib
import json

app = Flask(__name__)
WEBHOOK_SECRET = 'ваш-webhook-секрет'

@app.route('/webhook', methods=['POST'])
def webhook():
    # Проверка подписи
    signature = request.headers.get('X-Vilna-Signature')
    timestamp = request.headers.get('X-Vilna-Timestamp')
    event_id = request.headers.get('X-Vilna-Event-Id')
    
    payload = f"{timestamp}.{event_id}.{request.data.decode()}"
    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    if signature != expected_signature:
        return 'Неверная подпись', 401
    
    # Обработка события
    event = request.json
    print(f"Получено событие {event['event_type']}:", event['data'])
    
    if event['event_type'] == 'transaction.confirmed':
        # Обработка подтвержденной транзакции
        amount = event['data']['amount']
        asset = event['data']['asset_name']
        print(f"Транзакция подтверждена: {amount} {asset}")
        # Обновите базу данных, начислите средства пользователю и т.д.
    
    # Всегда быстро возвращайте 200 OK
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

Шаг 6: Протестируйте интеграцию

Отправьте тестовый webhook

Проверьте работу вашего обработчика webhook:

curl -X POST https://api.vilna.io/v1/channels/chan_770e8400-e29b-41d4-a716-446655440002/test \
-H "Authorization: Bearer $VILNA_API_KEY"

Вы должны получить тестовое событие на ваш webhook endpoint.

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

Запросите текущий баланс отслеживаемого адреса:

curl https://api.vilna.io/v1/addresses/addr_550e8400-e29b-41d4-a716-446655440000/balances \
-H "Authorization: Bearer $VILNA_API_KEY"

Ответ:

{
  "items": [
    {
      "asset_gid": "eip155:1/slip44:60",
      "asset_name": "ETH",
      "balance": "5.25",
      "usd_value": "12562.50",
      "last_updated": "2024-01-15T10:35:00Z"
    },
    {
      "asset_gid": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "asset_name": "USDC",
      "balance": "10000.00",
      "usd_value": "10000.00",
      "last_updated": "2024-01-15T10:35:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
    "blockchain_gid": "eip155:1"
  }
}

Шаг 7: Чек-лист для продакшена

Перед запуском в продакшн убедитесь, что вы:

  • Реализовали проверку подписи для безопасности webhook
  • Добавили обработку ошибок для обработки webhook
  • Настроили идемпотентность используя event_id для предотвращения дублирования
  • Настроили логику повторных попыток для неудачных API вызовов
  • Добавили мониторинг для вашего webhook endpoint
  • Протестировали с реальными транзакциями в тестовой сети
  • Установили подходящие требования к подтверждениям для вашего случая
  • Реализовали правильное логирование для отладки
  • Защитили API ключи используя переменные окружения
  • Настроили резервные каналы уведомлений для критичных событий

Распространенные сценарии использования

Прием платежей

// Генерация уникального платежного адреса
const address = await generateAddress(customerId);

// Показать адрес клиенту
displayPaymentAddress(address);

// Webhook уведомит когда платеж поступит
// Обработка в webhook обработчике

Мониторинг казначейства

// Добавить все казначейские кошельки
const wallets = ['0x123...', '0x456...', '0x789...'];
await addAddresses(wallets);

// Настроить email уведомления для крупных переводов
await createEmailChannel('[email protected]');
await createSubscription({
  event_types: ['transaction.confirmed'],
  min_amount: '10000'
});

Депозиты биржи

// Импорт xpub HD кошелька
const xpub = await importXpub(EXCHANGE_XPUB);

// Генерация депозитного адреса для каждого пользователя
async function getUserDepositAddress(userId) {
  const address = await generateFromXpub(xpub.id, `Пользователь ${userId}`);
  await saveUserAddress(userId, address);
  return address;
}

Решение проблем

Не получаете webhooks?

  1. Проверьте публичную доступность webhook URL

    curl -X POST https://your-app.com/webhook \
-H "Content-Type: application/json" \
-d '{"test": true}'

  2. Проверьте активность подписки

    curl https://api.vilna.io/v1/subscriptions \
-H "Authorization: Bearer $VILNA_API_KEY"

  3. Проверьте логи канала на наличие ошибок

    curl https://api.vilna.io/v1/channels/chan_xxx/logs \
-H "Authorization: Bearer $VILNA_API_KEY"

Локальное тестирование с ngrok

# Установите ngrok
npm install -g ngrok

# Запустите локальный сервер
node webhook-handler.js

# В другом терминале откройте его через ngrok
ngrok http 3000

# Используйте URL от ngrok при создании канала
# https://abc123.ngrok.io/webhook

Следующие шаги

Поздравляем! Вы успешно:

  • ✅ Добавили адрес для мониторинга
  • ✅ Создали webhook канал
  • ✅ Настроили подписку
  • ✅ Реализовали обработчик webhook
  • ✅ Протестировали интеграцию

Теперь вы можете:

Получить помощь

  • 📚 Документация: Доступна в этой документации
  • 💬 Поддержка: Свяжитесь с поддержкой через официальные каналы
  • 🐛 Сообщить о проблеме: github.com/vilna-io/issues
 
Следующая страница