Core concepts

This page explains the key domain concepts you will encounter when working with the Vilna API. Each section describes what the concept is, how it is identified, and when you will use it. For full endpoint details, see the Platform API Reference.

Vilna identifies every blockchain with a CAIP-2 global identifier (GID). The format is namespace:reference - for example, eip155:1 for Ethereum mainnet or eip155:137 for Polygon.

You can list all supported chains with GET /blockchains.

Common chain GIDs:

For the full CAIP standard reference, see CAIP Standards.

If you are new to blockchain addresses, keys, and derivation paths, see Blockchain Basics for a primer before continuing.

An address represents a blockchain account you want to monitor. There are two ways to add addresses:

External addresses are standalone accounts you import individually with POST /addresses/external. You provide the raw address value, a chainFamily (which assigns the address to all chains in that family automatically), and an optional label.

HD-derived addresses are generated from a public key (see the next section). These addresses are created sequentially and are automatically monitored once generated.

Supported address formats include:

Every address has a meta field - a free-form JSON object where you can store application-specific data such as customer IDs, invoice numbers, or internal references. This metadata is returned in API responses and webhook payloads, so you can correlate blockchain events with your business logic.

If you have a raw public key and need the corresponding blockchain address, use POST /addresses/external/resolve. This endpoint computes the address from the public key, creates an external address, and returns it. The public key is used only for derivation and is not stored. If an address with the computed value already exists, the existing one is returned.

curl -X POST "https://api.vilna.io/v1/addresses/external/resolve" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "publicKey": "02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5",
    "addressFormat": "evm"
  }'

The publicKey field accepts hex-encoded secp256k1 keys (compressed or uncompressed, with optional 0x prefix) for EVM, Tron, and Bitcoin formats, or base58-encoded ed25519 keys for Solana. You can also pass optional label and meta fields, just like when creating an external address directly.

This is useful when your system stores raw public keys (for example, from hardware wallets or key ceremonies) and you need to derive and register the on-chain address without doing the computation yourself.

List all addresses with GET /addresses.

If you manage an HD wallet, you can import its extended public key (xPub, yPub, or zPub) with POST /public_keys. Vilna uses BIP-32 / BIP-44 / BIP-49 / BIP-84 / BIP-86 derivation paths to generate child addresses deterministically.

Once the public key is imported, call POST /public_keys/{public_key_id}/addresses/next to generate the next unused address in the derivation sequence. The new address is automatically registered for monitoring on the chains associated with the public key.

This approach is ideal for exchanges and payment platforms that need a unique deposit address per customer without exposing the private key.

Every token or coin is identified with a CAIP-19 asset ID. The format is chain_gid/asset_namespace:asset_reference.

Native tokens use the slip44 namespace:

eip155:1/slip44:60          - ETH on Ethereum
eip155:56/slip44:60         - BNB on BSC

Contract tokens use namespace matching the token standard:

eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48   - USDC on Ethereum
eip155:56/erc20:0x55d398326f99059fF775485246999027B3197955    - USDT on BSC

Token metadata (name, symbol, decimals) is included in the references.tokens field of API responses.

A transaction represents a confirmed or pending on-chain operation. List transactions across all your addresses with GET /transactions.

Each transaction contains one or more canonical events that describe what happened:

Events are the building blocks for understanding what a transaction did. A single swap transaction, for example, might produce multiple transfer events and a fee event.

The activity feed (GET /activity) is a higher-level view that shows balance changes for your monitored addresses. Each entry includes:

• direction - in (received) or out (sent)
• amount - how much was gained or lost (see Amounts below)
• token - which asset changed
• address - which of your addresses was affected

Use the activity feed when you need a simple "what came in, what went out" view without parsing raw transaction events.

Query the current holdings of your addresses with GET /balances (all addresses) or GET /addresses/{address}/balances (single address). The response lists each token held along with its amount.

Balances are updated automatically as new transactions are indexed.

All monetary values in the API are returned as an object with two fields:

{
  "base": "1000000",
  "formatted": "1.0"
}

Always use base for arithmetic and storage. Use formatted for display purposes only.

A notification channel defines a destination for real-time event delivery. Vilna supports two channel kinds:

Webhook - Vilna sends an HTTP POST to your URL whenever a relevant event occurs. Each delivery is signed with HMAC-SHA256 in the X-Webhook-Signature header (Stripe format). See Authentication for verification details.

Telegram - Events are delivered to a Telegram chat.

Create a channel with POST /channels and test it with POST /channels/{channel_id}/actions/test.

Channels are global to your project. All monitored addresses deliver events to all active channels.

List and detail responses include a references object that contains related entities so you can resolve IDs without extra API calls.

For a single-item response:

{
  "item": { "...": "..." },
  "references": {
    "tokens": { "eip155:1/slip44:60": { "name": "ETH", "...": "..." } },
    "blockchains": { "eip155:1": { "name": "Ethereum", "...": "..." } },
    "addresses": { "eip155:1:0x742d...": { "...": "..." } }
  }
}

For a list response:

{
  "items": [ "..." ],
  "meta": {
    "limit": 30,
    "page": 1,
    "total": 142,
    "total_pages": 5
  },
  "references": { "...": "..." }
}

The meta object provides pagination info. Use the limit and page query parameters to navigate pages.

The API returns errors in RFC 7807 application/problem+json format:

{
  "type": "https://docs.vilna.io/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "fields": [
    { "name": "address.value", "reason": "must be a valid blockchain address" }
  ]
}

The fields array pinpoints exactly which inputs failed and why.