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 as an alternative integration approach.
- Package:
@vilna/sdk - License: Apache-2.0
- Node.js: >= 18
npm install @vilna/sdkimport { 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 and exposes the same GET, POST, PUT, DELETE methods with full path autocompletion.
const { data, error } = await client.GET("/blockchains");
if (data) {
for (const chain of data.items) {
console.log(chain.gid, chain.name, chain.is_active);
}
}const { data } = await client.GET("/addresses/{address}", {
params: {
path: { address: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123" },
},
});const { data } = await client.POST("/addresses/external", {
body: {
value: "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123",
chainFamily: "evm",
label: "Treasury",
},
});const { data } = await client.GET("/balances", {
params: { query: { limit: 50 } },
});List endpoints return paginated responses with items and meta. Use the page and limit query parameters to iterate through all pages:
// 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++;
}const { data } = await client.POST("/channels", {
body: {
name: "My Webhook",
config: {
kind: "webhook",
url: "https://example.com/webhook",
headers: {
Authorization: "Bearer secret",
},
},
},
});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:
import type { VilnaComponents } from "@vilna/sdk";
type Address = VilnaComponents["schemas"]["Address"];
type Transaction = VilnaComponents["schemas"]["Transaction"];Every call returns { data, error }. When the request fails, error follows the RFC 7807 Problem Details format:
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:
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 for the full error reference.
The SDK also exports two helper values:
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"