{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-get-started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"FAQ - Frequently Asked Questions","projectTitle":"Vilna Docs","description":"Answers to questions about the Vilna API - supported chains, the non-custodial model, authentication, monitoring, webhooks, standards and errors.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-faq.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"},{"name":"robots","content":"max-image-preview:large"}],"llmstxt":{"title":"Vilna API Documentation","description":"Vilna Platform API monitors public blockchain activity, balances and invoices and delivers signed webhooks. It does not sign or broadcast transactions. VKS separately coordinates account setup, signer approvals and signing, retains signed results and can submit a complete transaction to a node. Node acceptance is not blockchain confirmation. Each API uses its own scoped credential in X-Api-Key. Workspace setup and VKS-key issuance start in the Dashboard.\n","details":{"content":"**Platform monitoring.** Platform observes merchant-controlled addresses,\nsupplied directly or derived from the merchant's extended public key (xPub).\nInvoices report incoming on-chain activity; they do not initiate transfers.\n\n**APIs and their credentials.**\n\n- Platform API (api.vilna.io) - monitor addresses and extended public keys, read\n  balances and transactions, reconcile incoming payments, create invoices, and\n  receive events.\n- Blockchain RPC (rpc.vilna.io) - JSON-RPC and gRPC node access across every\n  supported network behind one key.\n- Management API (mgmt.vilna.io) - published workspace, project, member and key\n  operations, with Dashboard bootstrap and credential grant limits.\n- VKS API (vks.vilna.io) - workspace signers, vaults, accounts, signing requests,\n  signed results and optional asynchronous send. Uses a Dashboard-issued VKS key\n  with vks:access; the public Management API has no VKS-key issuance route.\n\n**Pages with no markdown source**, so they cannot be linked below:\n\n- Product overview: https://docs.vilna.io/\n- All guides: https://docs.vilna.io/guides\n"},"excludeFiles":["legal/terms.md","legal/privacy.md","legal/cookies.md","@l10n/ru/legal/terms.md","@l10n/ru/legal/privacy.md","@l10n/ru/legal/cookies.md"],"sections":[{"title":"Getting Started","description":"What the platform is, how to make a first call, and answers to common questions","includeFiles":["get-started/quickstart.md","get-started/dashboard.md","get-started/core-concepts.md","get-started/members.md","get-started/faq.md"]},{"title":"API Reference","description":"Authentication, permissions, idempotency, errors, standards, and per-service endpoint documentation","includeFiles":["apis/authentication.md","apis/permissions.md","apis/idempotency.md","apis/errors.md","apis/standards.md","apis/networks.md","apis/platform/@v2/index.md","apis/platform/@v2/webhooks.md","apis/platform/@v2/api.yaml","apis/mgmt/index.md","apis/mgmt/api.yaml","apis/vks/index.md","apis/vks/api.yaml","apis/rpc/index.md","apis/rpc/json-rpc.md","apis/rpc/grpc.md"]},{"title":"Developer Guides","description":"Integration patterns, events, notifications, and tooling","includeFiles":["guides/events.md","guides/channels.md","guides/tokens.md","guides/integration-patterns.md","guides/mcp.md","guides/simulation.md","guides/invoices.md","guides/vks.md"]},{"title":"Trust and custody","description":"The non-custodial model in plain terms","includeFiles":["legal/non-custodial.md"]},{"title":"Optional","description":"Background reading and release history","includeFiles":["get-started/blockchain-basics.md","changelog.md"]}]},"priority":0.5,"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":"Get Started","item":"https://docs.vilna.io/get-started"},{"@type":"ListItem","position":3,"name":"FAQ"}]},{"@type":"FAQPage","dateModified":"2026-11-01","mainEntity":[{"@type":"Question","name":"What blockchains does Vilna support?","acceptedAnswer":{"@type":"Answer","text":"Platform API supports 5 mainnets and 4 testnets. 7 networks support full monitoring; Solana Mainnet and Testnet support addresses and the token catalog only. See the networks table for CAIP-2 IDs and product support; GET /blockchains returns the live set."}},{"@type":"Question","name":"Is Vilna custodial? Does it hold my keys or funds?","acceptedAnswer":{"@type":"Answer","text":"Platform API monitors and reconciles public chain activity; it does not sign or broadcast transactions. VKS coordinates account setup, signer approvals and signing; a complete signed transaction can optionally be sent to a node through VKS. Node acceptance is not blockchain confirmation."}},{"@type":"Question","name":"What is the difference between the Platform API, Management API, VKS, and Blockchain RPC?","acceptedAnswer":{"@type":"Answer","text":"The Platform API is for blockchain monitoring (addresses, balances, transactions, invoices). The Management API is for administration (workspaces, projects, members, keys). Blockchain RPC is direct node access over JSON-RPC and gRPC. VKS coordinates signers, vaults, accounts and signing. Its public API requires a separate VKS key; the website uses your user session."}},{"@type":"Question","name":"How do I get started?","acceptedAnswer":{"@type":"Answer","text":"Sign up at app.vilna.io, create a workspace and a project, then generate an API key. The platform is free during the early access period."}},{"@type":"Question","name":"How do I authenticate?","acceptedAnswer":{"@type":"Answer","text":"Send an API key in the X-Api-Key header on every authenticated API request. There is no OAuth flow and no token to refresh."}},{"@type":"Question","name":"Are there rate limits?","acceptedAnswer":{"@type":"Answer","text":"Limits depend on the API and operation. A temporal limit returns 429; follow the operation’s retry rules and any Retry-After header. See Errors for the RPC response format."}},{"@type":"Question","name":"What is the difference between external and HD addresses?","acceptedAnswer":{"@type":"Answer","text":"External addresses are imported by providing the full address string. HD addresses are derived from an extended public key (xPub) using BIP-32/44, so you can generate new addresses programmatically without exposing private keys."}},{"@type":"Question","name":"Can I monitor the same address on multiple chains?","acceptedAnswer":{"@type":"Answer","text":"Yes. For EVM-compatible chains, setting input.chain_family to evm when you create the address monitors it on all active EVM networks at once."}},{"@type":"Question","name":"How are amounts represented?","acceptedAnswer":{"@type":"Answer","text":"Many transaction and balance amounts have base for exact calculations and formatted for display. Invoice fields differ between authenticated and public responses; see amount formats."}},{"@type":"Question","name":"Why is there no balance or notification for a token I see on chain?","acceptedAnswer":{"@type":"Answer","text":"Balances cover native coins and verified or trusted tokens. The default incoming-transfer notification filter uses the same marks, but a selected address’s own action can also qualify; disabling the noise filter admits unfamiliar tokens. Resolve the contract with POST /tokens/{chain_gid}/{asset_path}, then POST .../actions/trust. Trusting a token creates no notifications for past transactions."}},{"@type":"Question","name":"How real-time is monitoring, and when does an event fire?","acceptedAnswer":{"@type":"Answer","text":"A subscription chooses one trigger: block waits a fixed number of blocks after inclusion, network waits for the chain's own confirmation policy, mempool (Bitcoin only) fires before inclusion. Create two subscriptions with different triggers for an early signal and a later confirmation signal. Meeting the confirmation policy does not guarantee irreversibility."}},{"@type":"Question","name":"What notification methods are supported?","acceptedAnswer":{"@type":"Answer","text":"Two: webhooks (a signed HTTP POST to your endpoint) and Telegram (bot messages to a chat)."}},{"@type":"Question","name":"How do I verify a webhook is authentic?","acceptedAnswer":{"@type":"Answer","text":"Check the X-Webhook-Signature header (t=<unix>,v1=<hex>), an HMAC-SHA256 of the t value, a literal dot and the raw request-body bytes, keyed with webhook_secret. Reject deliveries with a stale timestamp and deduplicate by X-Webhook-Event-Id. The Webhooks page has the step-by-step algorithm."}},{"@type":"Question","name":"Can I test webhooks without real transactions?","acceptedAnswer":{"@type":"Answer","text":"Yes. A channel test sends a signed sample marked is_test: true, without a real transaction. The request returns 202 with a notification_id; inspect the notification to confirm delivery. See Testing a channel."}},{"@type":"Question","name":"What happens if my webhook endpoint is down?","acceptedAnswer":{"@type":"Answer","text":"Failed deliveries (non-2xx or timeout) are retried on a fixed schedule with a growing delay. Retries reuse the same event_id, so deduplication keeps them safe, and every attempt is recorded in the notification history. max_attempts bounds those retries; once it is used up the channel disables itself."}},{"@type":"Question","name":"Can I turn off automatic channel disabling?","acceptedAnswer":{"@type":"Answer","text":"No. The knob is max_attempts, 1 to 10 per channel, raised with PATCH /channels/{channel_id}. Once a notification uses up the budget the channel is disabled and its waiting notifications are cancelled; re-enabling admits new transactions only."}},{"@type":"Question","name":"My channel was disabled. Did I lose deposits?","acceptedAnswer":{"@type":"Answer","text":"No. Transactions, activity and balances are recorded whether or not a notification went out; only the deliveries were cancelled. Poll GET /channels for is_enabled. After re-enabling, list the cancelled notifications and the activity for that window, and resend the ones that still have a payload."}},{"@type":"Question","name":"Do I need a client library to use the API?","acceptedAnswer":{"@type":"Answer","text":"No. Vilna is a standard REST API you can call from any language over HTTP. If you want typed client code, generate it from the OpenAPI specification."}},{"@type":"Question","name":"Can I integrate faster with an AI assistant?","acceptedAnswer":{"@type":"Answer","text":"Yes. The Vilna docs MCP server lets Claude and other MCP clients read the full API reference in context and scaffold correct calls. See AI integration."}},{"@type":"Question","name":"What is CAIP?","acceptedAnswer":{"@type":"Answer","text":"Chain Agnostic Improvement Proposals - one identifier shape for chains (CAIP-2), accounts (CAIP-10) and assets (CAIP-19) across networks. Vilna uses them throughout the API."}},{"@type":"Question","name":"What error format does the API use?","acceptedAnswer":{"@type":"Answer","text":"The Platform, Management and VKS HTTP APIs use RFC 7807 Problem Details (application/problem+json). Branch on the machine-readable code; Blockchain RPC uses protocol errors. See Errors."}}]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"faq","__idx":0},"children":["FAQ"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"general","__idx":1},"children":["General"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-blockchains-does-vilna-support","__idx":2},"children":["What blockchains does Vilna support?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Platform API supports 5 mainnets and 4 testnets. 7 networks support full monitoring; Solana Mainnet and Testnet support addresses and the token catalog only. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/networks#table"},"children":["networks table"]}," for CAIP-2 IDs and product support; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /blockchains"]}," returns the live set."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"is-vilna-custodial-does-it-hold-my-keys-or-funds","__idx":3},"children":["Is Vilna custodial? Does it hold my keys or funds?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Platform API monitors and reconciles public chain activity; it does not sign or broadcast transactions. VKS coordinates account setup, signer approvals and signing; a complete signed transaction can optionally be sent to a node through VKS. Node acceptance is not blockchain confirmation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"whats-the-difference-between-the-platform-api-management-api-vks-and-blockchain-rpc","__idx":4},"children":["What's the difference between the Platform API, Management API, VKS, and Blockchain RPC?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For API calls, use a service-specific credential:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform"},"children":["Platform API"]}]}," - blockchain monitoring: addresses, balances, transactions, invoices, notifications."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/mgmt"},"children":["Management API"]}]}," - administration: workspaces, projects, members, and API-key lifecycle."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/vks"},"children":["VKS"]}]}," - signers, vaults, accounts and transaction signing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/rpc"},"children":["Blockchain RPC"]}]}," - direct node access over JSON-RPC and gRPC, one key for every chain."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-get-started","__idx":5},"children":["How do I get started?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.vilna.io"},"children":["Sign up at app.vilna.io"]},", create a workspace and a project, then generate an API key with the permissions you need. The platform is free during the early access period; see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/quickstart"},"children":["Quickstart"]},". For help, email ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@vilna.io"},"children":["support@vilna.io"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication--limits","__idx":6},"children":["Authentication & limits"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-authenticate","__idx":7},"children":["How do I authenticate?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send an API key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header on every authenticated API request - no OAuth flow, no token to refresh. Key types and scopes are covered in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"are-there-rate-limits","__idx":8},"children":["Are there rate limits?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Limits depend on the API and operation. A temporal limit returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},"; follow the operation's retry rules and any ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}," header. RPC has its own error formats and does not return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-*"]}," headers. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/errors#rate-limits"},"children":["Errors"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"addresses--monitoring","__idx":9},"children":["Addresses & monitoring"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-the-difference-between-external-and-hd-addresses","__idx":10},"children":["What is the difference between external and HD addresses?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["External addresses are imported directly: you provide the full address string. HD addresses are derived from an extended public key (xPub) using BIP-32/44, so you can generate new addresses programmatically without exposing private keys. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/blockchain-basics"},"children":["Blockchain basics"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-monitor-the-same-address-on-multiple-chains","__idx":11},"children":["Can I monitor the same address on multiple chains?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes. For EVM-compatible chains, setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["input.chain_family"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evm"]}," when you create the address monitors it on all active EVM networks at once."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-are-amounts-represented","__idx":12},"children":["How are amounts represented?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many transaction and balance amounts have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," for exact calculations and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," for display. Invoice fields differ between authenticated and public responses; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/core-concepts#amounts"},"children":["amount formats"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"why-is-there-no-balance-or-notification-for-a-token-i-see-on-chain","__idx":13},"children":["Why is there no balance or notification for a token I see on chain?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Balances cover native coins and tokens that are ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_verified"]}," (the shared list) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_trusted"]}," (your project's selection). The default incoming-transfer notification filter uses these marks, but a selected address's own action can also qualify; turning the filter off admits unfamiliar tokens without starting balances. Resolve the contract with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /tokens/{chain_gid}/{asset_path}"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST …/actions/trust"]},"; past transactions stay silent. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tokens"},"children":["Tokens and balances"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-real-time-is-monitoring-and-when-does-an-event-fire","__idx":14},"children":["How real-time is monitoring, and when does an event fire?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A subscription chooses one trigger: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block"]}," waits a fixed number of blocks after inclusion, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network"]}," waits for the chain's own confirmation policy, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mempool"]}," (Bitcoin only) fires before inclusion. For an early signal and a later confirmation signal, create two subscriptions with different triggers. Meeting the confirmation policy does not guarantee irreversibility. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/events"},"children":["Events & monitoring"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notifications","__idx":15},"children":["Notifications"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-notification-methods-does-vilna-support","__idx":16},"children":["What notification methods does Vilna support?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["webhooks"]}," (a signed HTTP POST to your endpoint) and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Telegram"]}," (bot messages to a chat). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/channels"},"children":["Notification channels"]}," for setup."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-verify-a-webhook-is-authentic","__idx":17},"children":["How do I verify a webhook is authentic?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Signature"]}," header: it carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t=<unix>,v1=<hex>"]},", an HMAC-SHA256 of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t"]}," value, a literal dot and the raw request-body bytes, keyed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_secret"]},". Reject deliveries whose timestamp is stale (replay protection) and deduplicate by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Id"]},". The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/webhooks#verify"},"children":["Webhooks page"]}," has the step-by-step algorithm."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-test-webhooks-without-real-transactions","__idx":18},"children":["Can I test webhooks without real transactions?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes. A channel test sends a signed sample marked ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_test: true"]},", without a real transaction. The request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["notification_id"]},"; inspect the notification to confirm delivery. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/channels#testing"},"children":["Testing a channel"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-happens-if-my-webhook-endpoint-is-down","__idx":19},"children":["What happens if my webhook endpoint is down?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A delivery that doesn't return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," (or times out) is retried on a fixed schedule with a growing delay. Retries reuse the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_id"]},", so your deduplication keeps them safe, and every attempt is recorded in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/channels#logs"},"children":["notification history"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max_attempts"]}," bounds those retries; once it is used up the channel disables itself - see the next two questions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-turn-off-automatic-channel-disabling","__idx":20},"children":["Can I turn off automatic channel disabling?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No. The knob is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["max_attempts"]},", 1 to 10 per channel, raised with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /channels/{channel_id}"]},". Once a notification uses up the budget the channel is disabled and its waiting notifications are cancelled; re-enabling admits new transactions only. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/channels#disabled"},"children":["when a channel switches itself off"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"my-channel-was-disabled-did-i-lose-deposits","__idx":21},"children":["My channel was disabled. Did I lose deposits?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No. Transactions, activity and balances are recorded whether or not a notification went out; only the deliveries were cancelled. Poll ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /channels"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_enabled: false"]},". After re-enabling, list the cancelled notifications and the activity for that window, and resend the ones that still have a payload. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/channels#payment-flow"},"children":["payment flow recipe"]}," walks through it."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tools","__idx":22},"children":["Tools"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"do-i-need-a-client-library-to-use-the-vilna-api","__idx":23},"children":["Do I need a client library to use the Vilna API?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No. Vilna is a standard REST API; call it directly from any language over HTTP. If you want typed client code, generate it from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api"},"children":["OpenAPI specification"]}," using a tool like ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://openapi-generator.tech/"},"children":["openapi-generator"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-integrate-faster-with-an-ai-assistant","__idx":24},"children":["Can I integrate faster with an AI assistant?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes. The Vilna docs MCP server lets Claude and other MCP clients read the full API reference in context and scaffold correct calls. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/mcp"},"children":["AI integration"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"standards--errors","__idx":25},"children":["Standards & errors"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-caip","__idx":26},"children":["What is CAIP?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Chain Agnostic Improvement Proposals give every chain, account and asset one identifier shape: CAIP-2 for chains, CAIP-10 for accounts, CAIP-19 for assets. Vilna uses them as ids throughout the API. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/standards#caip"},"children":["Standards"]}," for how each one is built."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-error-format-does-the-vilna-api-use","__idx":27},"children":["What error format does the Vilna API use?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Platform, Management and VKS HTTP APIs use RFC 7807 Problem Details (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]},"). Branch on the machine-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},"; Blockchain RPC uses protocol errors. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/errors"},"children":["Errors"]},"."]}]},"headings":[{"value":"FAQ","id":"faq","depth":1},{"value":"General","id":"general","depth":2},{"value":"What blockchains does Vilna support?","id":"what-blockchains-does-vilna-support","depth":3},{"value":"Is Vilna custodial? Does it hold my keys or funds?","id":"is-vilna-custodial-does-it-hold-my-keys-or-funds","depth":3},{"value":"What's the difference between the Platform API, Management API, VKS, and Blockchain RPC?","id":"whats-the-difference-between-the-platform-api-management-api-vks-and-blockchain-rpc","depth":3},{"value":"How do I get started?","id":"how-do-i-get-started","depth":3},{"value":"Authentication & limits","id":"authentication--limits","depth":2},{"value":"How do I authenticate?","id":"how-do-i-authenticate","depth":3},{"value":"Are there rate limits?","id":"are-there-rate-limits","depth":3},{"value":"Addresses & monitoring","id":"addresses--monitoring","depth":2},{"value":"What is the difference between external and HD addresses?","id":"what-is-the-difference-between-external-and-hd-addresses","depth":3},{"value":"Can I monitor the same address on multiple chains?","id":"can-i-monitor-the-same-address-on-multiple-chains","depth":3},{"value":"How are amounts represented?","id":"how-are-amounts-represented","depth":3},{"value":"Why is there no balance or notification for a token I see on chain?","id":"why-is-there-no-balance-or-notification-for-a-token-i-see-on-chain","depth":3},{"value":"How real-time is monitoring, and when does an event fire?","id":"how-real-time-is-monitoring-and-when-does-an-event-fire","depth":3},{"value":"Notifications","id":"notifications","depth":2},{"value":"What notification methods does Vilna support?","id":"what-notification-methods-does-vilna-support","depth":3},{"value":"How do I verify a webhook is authentic?","id":"how-do-i-verify-a-webhook-is-authentic","depth":3},{"value":"Can I test webhooks without real transactions?","id":"can-i-test-webhooks-without-real-transactions","depth":3},{"value":"What happens if my webhook endpoint is down?","id":"what-happens-if-my-webhook-endpoint-is-down","depth":3},{"value":"Can I turn off automatic channel disabling?","id":"can-i-turn-off-automatic-channel-disabling","depth":3},{"value":"My channel was disabled. Did I lose deposits?","id":"my-channel-was-disabled-did-i-lose-deposits","depth":3},{"value":"Tools","id":"tools","depth":2},{"value":"Do I need a client library to use the Vilna API?","id":"do-i-need-a-client-library-to-use-the-vilna-api","depth":3},{"value":"Can I integrate faster with an AI assistant?","id":"can-i-integrate-faster-with-an-ai-assistant","depth":3},{"value":"Standards & errors","id":"standards--errors","depth":2},{"value":"What is CAIP?","id":"what-is-caip","depth":3},{"value":"What error format does the Vilna API use?","id":"what-error-format-does-the-vilna-api-use","depth":3}],"frontmatter":{"seo":{"title":"FAQ - Frequently Asked Questions","description":"Answers to questions about the Vilna API - supported chains, the non-custodial model, authentication, monitoring, webhooks, standards and errors.","priority":0.5,"image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-faq.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":"Get Started","item":"https://docs.vilna.io/get-started"},{"@type":"ListItem","position":3,"name":"FAQ"}]},{"@type":"FAQPage","dateModified":"2026-11-01","mainEntity":[{"@type":"Question","name":"What blockchains does Vilna support?","acceptedAnswer":{"@type":"Answer","text":"Platform API supports 5 mainnets and 4 testnets. 7 networks support full monitoring; Solana Mainnet and Testnet support addresses and the token catalog only. See the networks table for CAIP-2 IDs and product support; GET /blockchains returns the live set."}},{"@type":"Question","name":"Is Vilna custodial? Does it hold my keys or funds?","acceptedAnswer":{"@type":"Answer","text":"Platform API monitors and reconciles public chain activity; it does not sign or broadcast transactions. VKS coordinates account setup, signer approvals and signing; a complete signed transaction can optionally be sent to a node through VKS. Node acceptance is not blockchain confirmation."}},{"@type":"Question","name":"What is the difference between the Platform API, Management API, VKS, and Blockchain RPC?","acceptedAnswer":{"@type":"Answer","text":"The Platform API is for blockchain monitoring (addresses, balances, transactions, invoices). The Management API is for administration (workspaces, projects, members, keys). Blockchain RPC is direct node access over JSON-RPC and gRPC. VKS coordinates signers, vaults, accounts and signing. Its public API requires a separate VKS key; the website uses your user session."}},{"@type":"Question","name":"How do I get started?","acceptedAnswer":{"@type":"Answer","text":"Sign up at app.vilna.io, create a workspace and a project, then generate an API key. The platform is free during the early access period."}},{"@type":"Question","name":"How do I authenticate?","acceptedAnswer":{"@type":"Answer","text":"Send an API key in the X-Api-Key header on every authenticated API request. There is no OAuth flow and no token to refresh."}},{"@type":"Question","name":"Are there rate limits?","acceptedAnswer":{"@type":"Answer","text":"Limits depend on the API and operation. A temporal limit returns 429; follow the operation’s retry rules and any Retry-After header. See Errors for the RPC response format."}},{"@type":"Question","name":"What is the difference between external and HD addresses?","acceptedAnswer":{"@type":"Answer","text":"External addresses are imported by providing the full address string. HD addresses are derived from an extended public key (xPub) using BIP-32/44, so you can generate new addresses programmatically without exposing private keys."}},{"@type":"Question","name":"Can I monitor the same address on multiple chains?","acceptedAnswer":{"@type":"Answer","text":"Yes. For EVM-compatible chains, setting input.chain_family to evm when you create the address monitors it on all active EVM networks at once."}},{"@type":"Question","name":"How are amounts represented?","acceptedAnswer":{"@type":"Answer","text":"Many transaction and balance amounts have base for exact calculations and formatted for display. Invoice fields differ between authenticated and public responses; see amount formats."}},{"@type":"Question","name":"Why is there no balance or notification for a token I see on chain?","acceptedAnswer":{"@type":"Answer","text":"Balances cover native coins and verified or trusted tokens. The default incoming-transfer notification filter uses the same marks, but a selected address’s own action can also qualify; disabling the noise filter admits unfamiliar tokens. Resolve the contract with POST /tokens/{chain_gid}/{asset_path}, then POST .../actions/trust. Trusting a token creates no notifications for past transactions."}},{"@type":"Question","name":"How real-time is monitoring, and when does an event fire?","acceptedAnswer":{"@type":"Answer","text":"A subscription chooses one trigger: block waits a fixed number of blocks after inclusion, network waits for the chain's own confirmation policy, mempool (Bitcoin only) fires before inclusion. Create two subscriptions with different triggers for an early signal and a later confirmation signal. Meeting the confirmation policy does not guarantee irreversibility."}},{"@type":"Question","name":"What notification methods are supported?","acceptedAnswer":{"@type":"Answer","text":"Two: webhooks (a signed HTTP POST to your endpoint) and Telegram (bot messages to a chat)."}},{"@type":"Question","name":"How do I verify a webhook is authentic?","acceptedAnswer":{"@type":"Answer","text":"Check the X-Webhook-Signature header (t=<unix>,v1=<hex>), an HMAC-SHA256 of the t value, a literal dot and the raw request-body bytes, keyed with webhook_secret. Reject deliveries with a stale timestamp and deduplicate by X-Webhook-Event-Id. The Webhooks page has the step-by-step algorithm."}},{"@type":"Question","name":"Can I test webhooks without real transactions?","acceptedAnswer":{"@type":"Answer","text":"Yes. A channel test sends a signed sample marked is_test: true, without a real transaction. The request returns 202 with a notification_id; inspect the notification to confirm delivery. See Testing a channel."}},{"@type":"Question","name":"What happens if my webhook endpoint is down?","acceptedAnswer":{"@type":"Answer","text":"Failed deliveries (non-2xx or timeout) are retried on a fixed schedule with a growing delay. Retries reuse the same event_id, so deduplication keeps them safe, and every attempt is recorded in the notification history. max_attempts bounds those retries; once it is used up the channel disables itself."}},{"@type":"Question","name":"Can I turn off automatic channel disabling?","acceptedAnswer":{"@type":"Answer","text":"No. The knob is max_attempts, 1 to 10 per channel, raised with PATCH /channels/{channel_id}. Once a notification uses up the budget the channel is disabled and its waiting notifications are cancelled; re-enabling admits new transactions only."}},{"@type":"Question","name":"My channel was disabled. Did I lose deposits?","acceptedAnswer":{"@type":"Answer","text":"No. Transactions, activity and balances are recorded whether or not a notification went out; only the deliveries were cancelled. Poll GET /channels for is_enabled. After re-enabling, list the cancelled notifications and the activity for that window, and resend the ones that still have a payload."}},{"@type":"Question","name":"Do I need a client library to use the API?","acceptedAnswer":{"@type":"Answer","text":"No. Vilna is a standard REST API you can call from any language over HTTP. If you want typed client code, generate it from the OpenAPI specification."}},{"@type":"Question","name":"Can I integrate faster with an AI assistant?","acceptedAnswer":{"@type":"Answer","text":"Yes. The Vilna docs MCP server lets Claude and other MCP clients read the full API reference in context and scaffold correct calls. See AI integration."}},{"@type":"Question","name":"What is CAIP?","acceptedAnswer":{"@type":"Answer","text":"Chain Agnostic Improvement Proposals - one identifier shape for chains (CAIP-2), accounts (CAIP-10) and assets (CAIP-19) across networks. Vilna uses them throughout the API."}},{"@type":"Question","name":"What error format does the API use?","acceptedAnswer":{"@type":"Answer","text":"The Platform, Management and VKS HTTP APIs use RFC 7807 Problem Details (application/problem+json). Branch on the machine-readable code; Blockchain RPC uses protocol errors. See Errors."}}]}]}}},"lastModified":"2026-10-31T22:26:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/get-started/faq","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}