Quickstart

Most quickstarts hide the first working response behind a pile of setup: signup, SDK install, webhook config. Not this one. One curl call confirms the API works for you, then we add capability one piece at a time. The TypeScript SDK is at the end as an optional convenience.

1. Sign up at app.vilna.io and create a workspace, then a project inside it. Each project has its own addresses, balances, and events.
2. Generate an API key in the project settings.
3. Store it in an environment variable so the examples below run as-is:

export VILNA_API_KEY="your-api-key"

Your "hello world" - one request that confirms the key works and shows what the API can see.

curl "https://api.vilna.io/v1/blockchains" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

You'll get back the supported networks with their CAIP-2 IDs, names, and capability flags:

{
  "items": [
    { "gid": "eip155:1", "name": "ethereum", "is_active": true },
    { "gid": "eip155:56", "name": "bsc", "is_active": true },
    { "gid": "bip122:000000000019d6689c085ae165831e93", "name": "bitcoin", "is_active": true }
  ],
  "meta": { "page": 1, "total": 31 }
}

If you see this response, setup is done. Everything below adds capability one piece at a time, but the key already works.

Reference: GET /blockchains.

Register an address you want to track. The API watches it on every chain in the family you pick - one call covers all EVM networks, all Bitcoin-like chains, and so on.

curl -X POST "https://api.vilna.io/v1/addresses/external" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
    "chainFamily": "evm",
    "label": "Treasury"
  }'

chainFamily accepts evm, bitcoin, solana, or tron. The response returns an address ID and confirms which chains it's registered on. From this point Vilna indexes the address's history and tracks new transactions in real time.

References: POST /addresses/external. For the difference between external and HD addresses, see Core Concepts.

Once an address is registered, two read-only endpoints cover most needs.

Current holdings across all your monitored addresses:

curl "https://api.vilna.io/v1/balances?limit=10" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Each entry has an asset GID and a structured amount with base (raw integer string) and formatted (human-readable). Use base for math, formatted for display.

Recent activity - balance changes across all addresses, paginated:

curl "https://api.vilna.io/v1/activity?limit=10" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

Each entry has a direction (in/out), the asset, and the delta. Good for "did anything happen recently" without scanning every transaction.

References: GET /balances, GET /activity. Amount format details: Core Concepts - Amounts.

Polling works for some workflows, but most production integrations want push delivery. Vilna sends events to your endpoint as soon as they confirm on chain.

Create a webhook channel pointing at an HTTP endpoint you control:

curl -X POST "https://api.vilna.io/v1/channels" \
  -H "X-Api-Key: ${VILNA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Webhook",
    "config": {
      "kind": "webhook",
      "url": "https://your-app.example.com/vilna-webhook"
    }
  }'

Save the channel id from the response into an env var, then trigger a test delivery to confirm your endpoint is reachable:

export CHANNEL_ID="<paste-id-from-response>"
curl -X POST "https://api.vilna.io/v1/channels/${CHANNEL_ID}/actions/test" \
  -H "X-Api-Key: ${VILNA_API_KEY}"

If your endpoint returns 2xx, you're set. Vilna will deliver real events to it whenever your monitored addresses see activity.

References: POST /channels, POST /channels/{channel_id}/actions/test. Payload schema and channel lifecycle: Notification Channels. Event types: Events & Monitoring.

If TypeScript is your stack, the official SDK gives you typed clients generated from the OpenAPI spec.

npm install @vilna/sdk

import { createVilnaClient } from "@vilna/sdk";

const client = createVilnaClient({
  apiKey: process.env.VILNA_API_KEY!,
});

const { data, error } = await client.GET("/blockchains");

Every call returns { data, error } with full type safety. Full SDK guide: TypeScript SDK. For other languages, generate a client from the OpenAPI specification.