# FAQ

## General

### What blockchains does Vilna support?

Vilna supports Bitcoin, Ethereum, BNB Smart Chain, Polygon, Avalanche, Arbitrum, Optimism, Base, Solana, TRON, TON, and more. Call [`GET /blockchains`](/apis/platform/api/blockchain/list-blockchains) for the current list.

### How do I get started with the Vilna API?

[Sign up at app.vilna.io](https://app.vilna.io), create a workspace and project, then generate an API key with the permissions you need. The platform is free to use during the early access period. For help, contact [support@vilna.io](mailto:support@vilna.io).

### What authentication method does the Vilna API use?

The Vilna API requires an API key sent in the `X-Api-Key` header for all requests. See the [Authentication guide](/guides/authentication) for details.

## Addresses and wallets

### What is the difference between external and HD addresses?

External addresses are imported directly - you provide the full address string. HD addresses are derived from an extended public key (xPub) using BIP-32/44 standards, allowing you to generate new addresses programmatically without exposing private keys.

### Can I monitor the same address on multiple chains?

Yes. For EVM-compatible chains, specifying `chainFamily: "evm"` when creating the address in Vilna automatically monitors it on all active EVM networks.

### How are amounts represented in the Vilna API?

All amounts in the Vilna API have two fields:

- `base` - the raw integer value as a string (e.g., `"1000000"`)
- `formatted` - human-readable value with decimals applied (e.g., `"1.0"` for USDT with 6 decimals)


Always use `base` for calculations and `formatted` for display.

## Notifications

### What notification methods does Vilna support?

Vilna supports two notification types: **Webhooks** (HTTP POST to your endpoint) and **Telegram** (bot messages to a chat). See the [Notification Channels guide](/guides/channels) for setup instructions.

### How do I verify Vilna webhook authenticity?

Check the `X-Webhook-Signature` header, which contains an HMAC-SHA256 digest of the request body. Also validate the `X-Webhook-Timestamp` to prevent replay attacks and use `X-Webhook-Idempotency-Key` for deduplication. See [Authentication](/guides/authentication#webhook-signature-verification) for code examples.

> **Note:** Webhook signature verification is a planned feature. The headers described above are not yet available in production.


### Can I test webhooks without real transactions?

Yes. Use the Vilna test action to send a sample payload to your channel:


```bash
curl -X POST "https://api.vilna.io/v1/channels/{channel_id}/actions/test" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "message_type": "transaction_alert" }'
```

## SDK and tools

### Which programming languages does the Vilna SDK support?

The official [TypeScript SDK](/guides/sdk) (`@vilna/sdk`) is available on npm. For other languages, you can generate a client from the [OpenAPI specification](/apis/platform/) using tools like [openapi-generator](https://openapi-generator.tech/) or [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen).

### Do I need the SDK to use the Vilna API?

No. The Vilna SDK provides convenience methods and full TypeScript type safety, but you can call the REST API directly from any language using standard HTTP.

### What is the Vilna Storage Client?

The [`@vilna-io/storage-client`](/guides/storage-client) is a separate npm package for web applications that need to interact with the Vilna Storage browser extension (wallet). It handles extension detection, connection, and transaction signing.

## Standards

### What is CAIP?

Chain Agnostic Improvement Proposals (CAIP) is a set of standards for identifying blockchains, accounts, and assets across different networks. Vilna uses CAIP throughout its API:

| Standard | Purpose | Example |
|  --- | --- | --- |
| CAIP-2 | Chain identifier | `eip155:1` (Ethereum mainnet) |
| CAIP-10 | Account identifier | `eip155:1:0x742d...` |
| CAIP-19 | Asset identifier | `eip155:1/erc20:0xa0b8...` |


See [CAIP Standards](/apis/platform/caip-standards) for the full reference.

### What error format does the Vilna API use?

The Vilna API returns all errors in [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807) format. See [Errors & Troubleshooting](/guides/errors) for the full error reference and troubleshooting tips.

## Further reading

Quickstart
Get up and running in 10 minutes

TypeScript SDK
Install and use the official typed API client

Platform API
Complete endpoint documentation

Management API
Workspace, project, and API key management