{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["cards","card"]},"type":"markdown"},"seo":{"title":"TypeScript SDK - Official Vilna API Client","projectTitle":"Vilna Docs","description":"Install and use the official TypeScript SDK for the Vilna API. Fully typed client generated from the OpenAPI specification with autocomplete support.","siteUrl":"https://docs.vilna.io","keywords":["crypto asset management","blockchain monitoring","digital asset security","cryptocurrency API","wallet tracking","blockchain analytics","enterprise crypto","real-time blockchain","CAIP-19","BIP44"],"lang":"en-US","image":"https://cdn.vilna.io/docs/previews/guides.png","meta":[{"name":"og:type","content":"website"},{"name":"og:site_name","content":"Vilna Documentation"},{"name":"og:image:width","content":"1200"},{"name":"og:image:height","content":"630"},{"name":"twitter:card","content":"summary_large_image"}],"llmstxt":{"title":"Vilna API Documentation","description":"Vilna is a blockchain monitoring and wallet management platform. It provides a single unified REST API for tracking addresses, transactions, balances, and activity across top blockchains - Bitcoin, Ethereum, Solana, TRON, TON, Cosmos, and others. The API uses CAIP-2/CAIP-19 standards for cross-chain identification, HD wallet management (BIP-32/44) for address derivation, and RFC 7807 for error responses. Authentication is via API key in the X-Api-Key header.\n","excludeFiles":["legal/**/*.md","@l10n/**/*.md"],"sections":[{"title":"Overview","description":"What Vilna is, supported blockchains, and target audience","includeFiles":["overview.md"],"excludeFiles":[]},{"title":"Getting Started","description":"Quickstart guide and core API concepts","includeFiles":["guides/quickstart.md","guides/dashboard.md","guides/core-concepts.md","guides/authentication.md"],"excludeFiles":[]},{"title":"API Reference","description":"Platform API and Management API endpoint documentation","includeFiles":["apis/platform/index.md","apis/mgmt/index.md","apis/rpc/index.md","apis/platform/api.yaml","apis/mgmt/api.yaml"],"excludeFiles":[]},{"title":"Developer Guides","description":"Integration patterns, events, notifications, SDK, and error handling","includeFiles":["guides/events.md","guides/channels.md","guides/integration-patterns.md","guides/sdk.md","guides/mcp.md","guides/errors.md","guides/simulation.md","guides/invoices.md"],"excludeFiles":[]},{"title":"Business","description":"Value proposition, use cases, and onboarding","includeFiles":["business/index.md","business/use-cases.md"],"excludeFiles":[]},{"title":"Optional","description":"Additional reference material","includeFiles":["guides/blockchain-basics.md","guides/faq.md","apis/mgmt/guide.md","guides/widget.md","guides/storage-client.md","apis/platform/caip-standards.md","apis/mgmt/authorization.md"],"excludeFiles":[]}],"hide":false},"priority":0.7,"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"Guides"},{"@type":"ListItem","position":3,"name":"SDK"}]},{"@type":"TechArticle","headline":"TypeScript SDK - Official Vilna API Client","description":"Install and use the official TypeScript SDK for the Vilna API. Fully typed client generated from the OpenAPI specification with autocomplete support.","url":"https://docs.vilna.io/guides/sdk","datePublished":"2025-09-17","dateModified":"2026-03-09","proficiencyLevel":"Intermediate","dependencies":"Node.js 18+, npm","image":"https://cdn.vilna.io/docs/previews/guides.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"typescript-sdk","__idx":0},"children":["TypeScript SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/mcp"},"children":["MCP server"]}," as an alternative integration approach."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Package:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.npmjs.com/package/@vilna/sdk"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@vilna/sdk"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["License:"]}," Apache-2.0"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Node.js:"]}," >= 18"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"installation","__idx":1},"children":["Installation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install @vilna/sdk\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-a-client","__idx":2},"children":["Creating a client"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { createVilnaClient } from \"@vilna/sdk\";\n\nconst client = createVilnaClient({\n  apiKey: \"your-api-key\",\n  // baseUrl: \"https://api.vilna.io/v1\", // optional override\n  // headers: { \"Custom-Header\": \"value\" }, // optional extra headers\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The default base URL is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.vilna.io/v1"]},". Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseUrl"]}," to override it for testing or custom deployments."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Under the hood the SDK uses ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://openapi-ts.dev/openapi-fetch/"},"children":["openapi-fetch"]}," and exposes the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," methods with full path autocompletion."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"usage-examples","__idx":3},"children":["Usage examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-blockchains","__idx":4},"children":["List blockchains"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data, error } = await client.GET(\"/blockchains\");\n\nif (data) {\n  for (const chain of data.items) {\n    console.log(chain.gid, chain.name, chain.is_active);\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"get-address-details","__idx":5},"children":["Get address details"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data } = await client.GET(\"/addresses/{address}\", {\n  params: {\n    path: { address: \"0x742d35Cc6634C0532925a3b844Bc9e7595f7B123\" },\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-an-external-address","__idx":6},"children":["Create an external address"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data } = await client.POST(\"/addresses/external\", {\n  body: {\n    value: \"0x742d35Cc6634C0532925a3b844Bc9e7595f7B123\",\n    chainFamily: \"evm\",\n    label: \"Treasury\",\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"query-balances","__idx":7},"children":["Query balances"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data } = await client.GET(\"/balances\", {\n  params: { query: { limit: 50 } },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"paginate-through-results","__idx":8},"children":["Paginate through results"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List endpoints return paginated responses with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]},". Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," query parameters to iterate through all pages:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Paginate through addresses\nlet page = 1;\nlet hasMore = true;\n\nwhile (hasMore) {\n  const { data } = await client.GET(\"/addresses\", {\n    params: { query: { page, limit: 100 } },\n  });\n  // process data.items\n  hasMore = page < data.meta.total_pages;\n  page++;\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-webhook-notification-channel","__idx":9},"children":["Create a webhook notification channel"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data } = await client.POST(\"/channels\", {\n  body: {\n    name: \"My Webhook\",\n    config: {\n      kind: \"webhook\",\n      url: \"https://example.com/webhook\",\n      headers: {\n        Authorization: \"Bearer secret\",\n      },\n    },\n  },\n});\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exported-types","__idx":10},"children":["Exported types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK re-exports several type aliases for convenience:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Export"},"children":["Export"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VilnaClient"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The client instance type returned by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createVilnaClient"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VilnaPaths"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Union of all API path strings"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VilnaComponents"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All component schemas from the OpenAPI spec"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreateVilnaClientOptions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Options accepted by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createVilnaClient"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Raw path definitions (same as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VilnaPaths"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Raw component definitions (same as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VilnaComponents"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operations"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operation-level types for request/response pairs"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VilnaComponents"]}," to reference specific schema types:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import type { VilnaComponents } from \"@vilna/sdk\";\n\ntype Address = VilnaComponents[\"schemas\"][\"Address\"];\ntype Transaction = VilnaComponents[\"schemas\"][\"Transaction\"];\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":11},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every call returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ data, error }"]},". When the request fails, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," follows the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tools.ietf.org/html/rfc7807"},"children":["RFC 7807 Problem Details"]}," format:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data, error } = await client.GET(\"/blockchains\");\n\nif (error) {\n  // error.type    - problem type URI\n  // error.title   - short summary (e.g. \"Not Found\")\n  // error.status  - HTTP status code\n  // error.detail  - human-readable explanation\n  console.error(error.title, error.detail);\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For validation errors (400), the response includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," array with per-field details:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const { data, error } = await client.POST(\"/addresses/external\", {\n  body: { /* ... */ },\n});\n\nif (error && error.status === 400) {\n  for (const field of error.fields ?? []) {\n    console.error(`${field.name}: ${field.reason}`);\n  }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/errors"},"children":["Errors & Troubleshooting"]}," for the full error reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"additional-exports","__idx":12},"children":["Additional exports"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK also exports two helper values:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { API_KEY_HEADER, DEFAULT_BASE_URL } from \"@vilna/sdk\";\n\nconsole.log(API_KEY_HEADER);              // \"X-Api-Key\"\nconsole.log(DEFAULT_BASE_URL);            // \"https://api.vilna.io/v1\"\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":13},"children":["Further reading"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Platform API","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/apis/platform/"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Complete endpoint documentation for all blockchain operations"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Authentication","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/authentication"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API key setup and webhook signature verification"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Errors","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/errors"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Error format reference and troubleshooting tips"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Quickstart","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/quickstart"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Step-by-step guide to your first API call"]}]}]}]},"headings":[{"value":"TypeScript SDK","id":"typescript-sdk","depth":1},{"value":"Installation","id":"installation","depth":2},{"value":"Creating a client","id":"creating-a-client","depth":2},{"value":"Usage examples","id":"usage-examples","depth":2},{"value":"List blockchains","id":"list-blockchains","depth":3},{"value":"Get address details","id":"get-address-details","depth":3},{"value":"Create an external address","id":"create-an-external-address","depth":3},{"value":"Query balances","id":"query-balances","depth":3},{"value":"Paginate through results","id":"paginate-through-results","depth":3},{"value":"Create a webhook notification channel","id":"create-a-webhook-notification-channel","depth":3},{"value":"Exported types","id":"exported-types","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Additional exports","id":"additional-exports","depth":2},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"TypeScript SDK - Official Vilna API Client","description":"Install and use the official TypeScript SDK for the Vilna API. Fully typed client generated from the OpenAPI specification with autocomplete support.","priority":0.7,"image":"https://cdn.vilna.io/docs/previews/guides.png","jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"Guides"},{"@type":"ListItem","position":3,"name":"SDK"}]},{"@type":"TechArticle","headline":"TypeScript SDK - Official Vilna API Client","description":"Install and use the official TypeScript SDK for the Vilna API. Fully typed client generated from the OpenAPI specification with autocomplete support.","url":"https://docs.vilna.io/guides/sdk","datePublished":"2025-09-17","dateModified":"2026-03-09","proficiencyLevel":"Intermediate","dependencies":"Node.js 18+, npm","image":"https://cdn.vilna.io/docs/previews/guides.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-04-21T06:44:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/sdk","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}