# Справочник API

## Обзор

Vilna API - это комплексная платформа для управления и мониторинга блокчейн-кошельков, предоставляющая инфраструктуру корпоративного уровня для операций с цифровыми активами.

### Ключевые возможности

- **Мониторинг транзакций**: Отслеживание транзакций блокчейна в реальном времени на множестве сетей
- **Обнаружение токенов**: Автоматическое обнаружение и отслеживание токенов
- **Управление адресами**: Генерация и управление блокчейн-адресами с поддержкой xpub
- **Запросы балансов**: Запрос текущих балансов по адресам
- **Система уведомлений**: Webhook и email каналы для событий блокчейна
- **Мультичейн поддержка**: 30+ блокчейнов, включая Bitcoin, Ethereum, Solana и другие


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

### Стандарты идентификации

Vilna реализует [стандарты CAIP](/ru/apis/caip-standards) для единообразной кросс-чейн идентификации:

- **CAIP-2**: Идентификация блокчейнов
- **CAIP-10**: Идентификация аккаунтов
- **CAIP-19**: Идентификация активов


### Соглашения об именовании

- **Внутренние ID**: Формат UUID v7 для объектов Vilna (например, `channel_id`, `xpub_id`)
- **Глобальные ID (GID)**: Формат CAIP для блокчейн-объектов (например, `asset_gid`, `transaction_gid`)


## Безопасность

Узнайте о [безопасности API](/ru/apis/security):

- Методы аутентификации
- Цифровые подписи и верификация webhook
- Ограничение частоты запросов
- Лучшие практики


## Форматы ответов

### Успешный ответ


```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Ответ списка с пагинацией


```json
{
  "items": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "total_pages": 5
  }
}
```

### Ответ с ошибкой (RFC 7807)

Отчеты об ошибках следуют стандарту [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) с использованием формата `application/json`.

#### Структура ответа с ошибкой


```json
{
  "type": "/problems/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "The request contains invalid parameters",
  "errors": [
    {
      "field": "xpub_id",
      "message": "Invalid UUID format"
    }
  ]
}
```

#### Распространенные ответы об ошибках

- **400 Bad Request**: Недействительные параметры или тело запроса
  - `type: /problems/invalid-request`
  - Включает ошибки валидации полей в массиве `errors`
- **401 Unauthorized**: Отсутствует или недействителен API ключ
  - `type: /problems/unauthorized`
- **404 Not Found**: Ресурс не найден
  - `type: /problems/not-found`
- **500 Internal Server Error**: Неожиданная ошибка сервера
  - `type: /problems/internal-error`


## Коды состояния HTTP

| Код | Описание |
|  --- | --- |
| 200 | Успешно |
| 201 | Создано |
| 204 | Нет содержимого |
| 400 | Неверный запрос |
| 401 | Не авторизован |
| 403 | Запрещено |
| 404 | Не найдено |
| 422 | Необработанная сущность |
| 429 | Слишком много запросов |
| 500 | Внутренняя ошибка сервера |


## Ресурсы для разработчиков

- **[Спецификация OpenAPI](/ru/apis/spec)** - Полная документация API
- **[Инструменты интеграции](/ru/tools/openapi)** - Postman, Swagger и генерация кода
- **[SDK](/ru/tools)** - SDK для различных языков программирования


## Дополнительная документация

- **[Руководство быстрого старта](/guides/quickstart)** - Пошаговое руководство по интеграции
- **[Обзор архитектуры](/guides/architecture-overview)** - Дизайн системы и концепции
- **[Руководство по каналам](/guides/channels)** - Подробная настройка уведомлений


## Поддержка

- **GitHub**: [github.com/vilna-io](https://github.com/vilna-io)
- **Документация**: [Полное руководство](/guides/quickstart)