# TypeScript SDK

The official TypeScript SDK for the Vilna API. It provides a fully typed client generated from the OpenAPI specification, so every endpoint, request body, and response is type-checked at compile time. If you prefer AI-assisted exploration, Vilna also offers an [MCP server](/guides/mcp) as an alternative integration approach.

- **Package:** [`@vilna/sdk`](https://www.npmjs.com/package/@vilna/sdk)
- **License:** Apache-2.0
- **Node.js:** >= 18


## Installation


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

## Creating a client


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

const client = createVilnaClient({
  apiKey: "your-api-key",
  // baseUrl: "https://api.vilna.io/v1", // optional override
  // headers: { "Custom-Header": "value" }, // optional extra headers
});
```

The default base URL is `https://api.vilna.io/v1`. Pass `baseUrl` to override it for testing or custom deployments.

Under the hood the SDK uses [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) and exposes the same `GET`, `POST`, `PUT`, `DELETE` methods with full path autocompletion.

## Usage examples

### List blockchains


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

if (data) {
  for (const chain of data.items) {
    console.log(chain.gid, chain.name, chain.is_active);
  }
}
```

### Get address details


```typescript
const { data } = await client.GET("/addresses/{address}", {
  params: {
    path: { address: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123" },
  },
});
```

### Create an external address


```typescript
const { data } = await client.POST("/addresses/external", {
  body: {
    value: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
    chainFamily: "evm",
    label: "Treasury",
  },
});
```

### Query balances


```typescript
const { data } = await client.GET("/balances", {
  params: { query: { limit: 50 } },
});
```

### Paginate through results

List endpoints return paginated responses with `items` and `meta`. Use the `page` and `limit` query parameters to iterate through all pages:


```typescript
// Paginate through addresses
let page = 1;
let hasMore = true;

while (hasMore) {
  const { data } = await client.GET("/addresses", {
    params: { query: { page, limit: 100 } },
  });
  // process data.items
  hasMore = page < data.meta.total_pages;
  page++;
}
```

### Create a webhook notification channel


```typescript
const { data } = await client.POST("/channels", {
  body: {
    name: "My Webhook",
    config: {
      kind: "webhook",
      url: "https://example.com/webhook",
      headers: {
        Authorization: "Bearer secret",
      },
    },
  },
});
```

## Exported types

The SDK re-exports several type aliases for convenience:

| Export | Description |
|  --- | --- |
| `VilnaClient` | The client instance type returned by `createVilnaClient` |
| `VilnaPaths` | Union of all API path strings |
| `VilnaComponents` | All component schemas from the OpenAPI spec |
| `CreateVilnaClientOptions` | Options accepted by `createVilnaClient` |
| `paths` | Raw path definitions (same as `VilnaPaths`) |
| `components` | Raw component definitions (same as `VilnaComponents`) |
| `operations` | Operation-level types for request/response pairs |


You can use `VilnaComponents` to reference specific schema types:


```typescript
import type { VilnaComponents } from "@vilna/sdk";

type Address = VilnaComponents["schemas"]["Address"];
type Transaction = VilnaComponents["schemas"]["Transaction"];
```

## Error handling

Every call returns `{ data, error }`. When the request fails, `error` follows the [RFC 7807 Problem Details](https://tools.ietf.org/html/rfc7807) format:


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

if (error) {
  // error.type    - problem type URI
  // error.title   - short summary (e.g. "Not Found")
  // error.status  - HTTP status code
  // error.detail  - human-readable explanation
  console.error(error.title, error.detail);
}
```

For validation errors (400), the response includes a `fields` array with per-field details:


```typescript
const { data, error } = await client.POST("/addresses/external", {
  body: { /* ... */ },
});

if (error && error.status === 400) {
  for (const field of error.fields ?? []) {
    console.error(`${field.name}: ${field.reason}`);
  }
}
```

See [Errors & Troubleshooting](/guides/errors) for the full error reference.

## Additional exports

The SDK also exports two helper values:


```typescript
import { API_KEY_HEADER, DEFAULT_BASE_URL } from "@vilna/sdk";

console.log(API_KEY_HEADER);              // "X-Api-Key"
console.log(DEFAULT_BASE_URL);            // "https://api.vilna.io/v1"
```

## Further reading

Platform API
Complete endpoint documentation for all blockchain operations

Authentication
API key setup and webhook signature verification

Errors
Error format reference and troubleshooting tips

Quickstart
Step-by-step guide to your first API call