# 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.

## Get an API key

1. [Sign up at app.vilna.io](https://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:



```bash
export VILNA_API_KEY="your-api-key"
```

The key is shown once
Save it to a secret manager immediately. You cannot retrieve it later, only revoke and create a new one.

## Sanity check: list supported blockchains

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


```bash
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:


```json
{
  "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`](/apis/platform/api/blockchain/list-blockchains).

## Continue: monitor an address

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.


```bash
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`](/apis/platform/api/address/create-external-address). For the difference between external and HD addresses, see [Core Concepts](/guides/core-concepts).

## Continue: read balances and activity

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

**Current holdings** across all your monitored addresses:


```bash
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:


```bash
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`](/apis/platform/api/balance/list-balances), [`GET /activity`](/apis/platform/api/activity/list-activity). Amount format details: [Core Concepts - Amounts](/guides/core-concepts#amounts).

## Continue: receive events

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:


```bash
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:


```bash
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`](/apis/platform/api/channel/create-channel), [`POST /channels/{channel_id}/actions/test`](/apis/platform/api/channel/test-channel). Payload schema and channel lifecycle: [Notification Channels](/guides/channels). Event types: [Events & Monitoring](/guides/events).

## Use the SDK (optional)

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


```bash
npm install @vilna/sdk
```


```typescript
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](/guides/sdk). For other languages, generate a client from the [OpenAPI specification](/apis/platform/api).

## Next steps

Core Concepts
Blockchains, addresses, tokens, amounts, and the references pattern

Authentication
API key management and security best practices

Integration Patterns
Deposit detection, portfolio tracking, HD wallet management, and more

Platform API
Full endpoint catalog with request/response schemas

Management API
Workspace, project, and key management