# API Reference

## Overview

The Vilna API is a comprehensive blockchain wallet management and monitoring platform that provides enterprise-grade infrastructure for digital asset operations.

### Key Features

- **Transaction Monitoring**: Real-time blockchain transaction tracking across multiple chains
- **Token Discovery**: Automatic token discovery and tracking
- **Address Management**: Generate and manage blockchain addresses with xpub support
- **Balance Queries**: Query current balances across addresses
- **Notification System**: Webhook and email channels for blockchain events
- **Multi-chain Support**: 30+ blockchains including Bitcoin, Ethereum, Solana, and more


## Core Concepts

### Identification Standards

Vilna implements [CAIP Standards](/apis/caip-standards) for consistent cross-chain identification:

- **CAIP-2**: Blockchain identification
- **CAIP-10**: Account identification
- **CAIP-19**: Asset identification


### Naming Conventions

- **Internal IDs**: UUID v7 format for Vilna-created objects (e.g., `channel_id`, `xpub_id`)
- **Global IDs (GID)**: CAIP format for blockchain objects (e.g., `asset_gid`, `transaction_gid`)


## Security

Learn about API [Security](/apis/security):

- Authentication methods
- Digital signatures and webhook verification
- Rate limiting
- Best practices


## Response Formats

### Success Response


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

### List Response with Pagination


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

### Error Response (RFC 7807)

Error reporting follows the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) standard using `application/json` format.

#### Error Response Structure


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

#### Common Error Responses

- **400 Bad Request**: Invalid request parameters or body
  - `type: /problems/invalid-request`
  - Includes field-level validation errors in `errors` array
- **401 Unauthorized**: Missing or invalid API key
  - `type: /problems/unauthorized`
- **404 Not Found**: Resource not found
  - `type: /problems/not-found`
- **500 Internal Server Error**: Unexpected server error
  - `type: /problems/internal-error`


## HTTP Status Codes

| Code | Description |
|  --- | --- |
| 200 | Success |
| 201 | Created |
| 204 | No Content |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Unprocessable Entity |
| 429 | Too Many Requests |
| 500 | Internal Server Error |


## Developer Resources

- **[OpenAPI Specification](/apis/spec)** - Complete API documentation
- **[Integration Tools](/tools/openapi)** - Postman, Swagger, and code generation
- **[SDKs](/tools)** - Language-specific SDKs


## Additional Documentation

- **[Quick Start Guide](/guides/quickstart)** - Step-by-step integration guide
- **[Architecture Overview](/guides/architecture-overview)** - System design and concepts
- **[Channels Guide](/guides/channels)** - Detailed notification setup


## Support

- **GitHub**: [github.com/vilna-io](https://github.com/vilna-io)
- **Documentation**: [Complete Guide](/guides/quickstart)