{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["cards","card"]},"type":"markdown"},"seo":{"title":"FAQ - Frequently Asked Questions","projectTitle":"Vilna Docs","description":"Answers to common questions about Vilna API including supported blockchains, getting started, authentication, and API key management.","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.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":"Guides"},{"@type":"ListItem","position":3,"name":"FAQ"}]},{"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"What blockchains does Vilna support?","acceptedAnswer":{"@type":"Answer","text":"Bitcoin, Ethereum, BNB Smart Chain, Polygon, Avalanche, Arbitrum, Optimism, Base, Solana, TRON, TON, and more. Call GET /blockchains for the current list."}},{"@type":"Question","name":"How do I get started?","acceptedAnswer":{"@type":"Answer","text":"Sign up at app.vilna.io, create a workspace and project, then generate an API key. The platform is free to use during the early access period."}},{"@type":"Question","name":"What authentication method does the API use?","acceptedAnswer":{"@type":"Answer","text":"All requests require an API key sent in the X-Api-Key header."}},{"@type":"Question","name":"What is the difference between external and HD addresses?","acceptedAnswer":{"@type":"Answer","text":"External addresses are imported directly by providing the full address string. HD addresses are derived from an extended public key (xPub) using BIP-32/44 standards, allowing programmatic generation 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, specifying chainFamily evm when creating the address automatically monitors it on all active EVM networks."}},{"@type":"Question","name":"How are amounts represented?","acceptedAnswer":{"@type":"Answer","text":"All amounts have a base field (raw integer as a string) and a formatted field (human-readable with decimals). Use base for calculations and formatted for display."}},{"@type":"Question","name":"What notification methods are supported?","acceptedAnswer":{"@type":"Answer","text":"Two types: Webhooks (HTTP POST to your endpoint) and Telegram (bot messages to a chat)."}},{"@type":"Question","name":"How do I verify webhook authenticity?","acceptedAnswer":{"@type":"Answer","text":"Every webhook delivery includes an X-Webhook-Signature header in Stripe format (t=<unix-seconds>,v1=<hex>) carrying the HMAC-SHA256 of the request body. The timestamp inside the header guards against replay attacks, and X-Webhook-Event-Id gives you a stable deduplication key across retries."}},{"@type":"Question","name":"Can I test webhooks without real transactions?","acceptedAnswer":{"@type":"Answer","text":"Yes. Use the test action endpoint to send a sample payload to your notification channel."}},{"@type":"Question","name":"Which programming languages are supported?","acceptedAnswer":{"@type":"Answer","text":"The official TypeScript SDK (@vilna/sdk) is available on npm. For other languages, generate a client from the OpenAPI specification using tools like openapi-generator."}},{"@type":"Question","name":"Do I need the SDK to use the API?","acceptedAnswer":{"@type":"Answer","text":"No. The SDK provides convenience methods and TypeScript type safety, but you can call the REST API directly from any language using standard HTTP."}},{"@type":"Question","name":"What is the Storage Client?","acceptedAnswer":{"@type":"Answer","text":"The @vilna-io/storage-client is an npm package for web applications that need to interact with the Vilna Storage browser extension for extension detection, connection, and transaction signing."}},{"@type":"Question","name":"What is CAIP?","acceptedAnswer":{"@type":"Answer","text":"Chain Agnostic Improvement Proposals, a set of standards for identifying blockchains, accounts, and assets across different networks. Vilna uses CAIP-2 for chains, CAIP-10 for accounts, and CAIP-19 for assets."}},{"@type":"Question","name":"What error format does the API use?","acceptedAnswer":{"@type":"Answer","text":"All errors follow RFC 7807 Problem Details, a standard format for machine-readable error responses."}}]}]}},"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":["Vilna supports Bitcoin, Ethereum, BNB Smart Chain, Polygon, Avalanche, Arbitrum, Optimism, Base, Solana, TRON, TON, and more. Call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/blockchain/list-blockchains"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /blockchains"]}]}," for the current list."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-get-started-with-the-vilna-api","__idx":3},"children":["How do I get started with the Vilna API?"]},{"$$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 project, then generate an API key with the permissions you need. The platform is free to use during the early access period. For help, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@vilna.io"},"children":["support@vilna.io"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-authentication-method-does-the-vilna-api-use","__idx":4},"children":["What authentication method does the Vilna API use?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Vilna API requires an API key sent in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header for all requests. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication guide"]}," for details."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"addresses-and-wallets","__idx":5},"children":["Addresses and wallets"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-the-difference-between-external-and-hd-addresses","__idx":6},"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 standards, allowing you to generate new addresses programmatically without exposing private keys."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-monitor-the-same-address-on-multiple-chains","__idx":7},"children":["Can I monitor the same address on multiple chains?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes. For EVM-compatible chains, specifying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chainFamily: \"evm\""]}," when creating the address in Vilna automatically monitors it on all active EVM networks."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-are-amounts-represented-in-the-vilna-api","__idx":8},"children":["How are amounts represented in the Vilna API?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All amounts in the Vilna API have two fields:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," - the raw integer value as a string (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"1000000\""]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," - human-readable value with decimals applied (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"1.0\""]}," for USDT with 6 decimals)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," for calculations and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," for display."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notifications","__idx":9},"children":["Notifications"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-notification-methods-does-vilna-support","__idx":10},"children":["What notification methods does Vilna support?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna supports two notification types: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhooks"]}," (HTTP POST to your endpoint) and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Telegram"]}," (bot messages to a chat). See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/channels"},"children":["Notification Channels guide"]}," for setup instructions."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-verify-vilna-webhook-authenticity","__idx":11},"children":["How do I verify Vilna webhook authenticity?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Signature"]}," header — it has Stripe format ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t=<unix-seconds>,v1=<hex>"]}," and carries the HMAC-SHA256 of the raw request body. The timestamp inside the header is what you compare against the current time to reject replays; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Id"]}," is your dedup key across retries. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication#webhook-signature-verification"},"children":["Authentication"]}," for the full verification code and required client behaviors."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-test-webhooks-without-real-transactions","__idx":12},"children":["Can I test webhooks without real transactions?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes. Use the Vilna test action to send a sample payload to your channel:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.vilna.io/v1/channels/{channel_id}/actions/test\" \\\n  -H \"X-Api-Key: your-api-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"event_type\": \"transaction_detected\" }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sdk-and-tools","__idx":13},"children":["SDK and tools"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"which-programming-languages-does-the-vilna-sdk-support","__idx":14},"children":["Which programming languages does the Vilna SDK support?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The official ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/sdk"},"children":["TypeScript SDK"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@vilna/sdk"]},") is available on npm. For other languages, you can generate a client from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/"},"children":["OpenAPI specification"]}," using tools like ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://openapi-generator.tech/"},"children":["openapi-generator"]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/oapi-codegen/oapi-codegen"},"children":["oapi-codegen"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"do-i-need-the-sdk-to-use-the-vilna-api","__idx":15},"children":["Do I need the SDK to use the Vilna API?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No. The Vilna SDK provides convenience methods and full TypeScript type safety, but you can call the REST API directly from any language using standard HTTP."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-the-vilna-storage-client","__idx":16},"children":["What is the Vilna Storage Client?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/storage-client"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@vilna-io/storage-client"]}]}," is a separate npm package for web applications that need to interact with the Vilna Storage browser extension (wallet). It handles extension detection, connection, and transaction signing."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"standards","__idx":17},"children":["Standards"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-caip","__idx":18},"children":["What is CAIP?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Chain Agnostic Improvement Proposals (CAIP) is a set of standards for identifying blockchains, accounts, and assets across different networks. Vilna uses CAIP throughout its API:"]},{"$$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":"Standard"},"children":["Standard"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example"},"children":["Example"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CAIP-2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chain identifier"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}," (Ethereum mainnet)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CAIP-10"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Account identifier"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1:0x742d..."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CAIP-19"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Asset identifier"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1/erc20:0xa0b8..."]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/caip-standards"},"children":["CAIP Standards"]}," for the full reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-error-format-does-the-vilna-api-use","__idx":19},"children":["What error format does the Vilna API use?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Vilna API returns all errors in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tools.ietf.org/html/rfc7807"},"children":["RFC 7807 Problem Details"]}," format. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/errors"},"children":["Errors & Troubleshooting"]}," for the full error reference and troubleshooting tips."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":20},"children":["Further reading"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$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":["Get up and running in 10 minutes"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"TypeScript SDK","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/sdk"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install and use the official typed API client"]}]},{"$$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"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Management API","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/apis/mgmt/"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Workspace, project, and API key management"]}]}]}]},"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":"How do I get started with the Vilna API?","id":"how-do-i-get-started-with-the-vilna-api","depth":3},{"value":"What authentication method does the Vilna API use?","id":"what-authentication-method-does-the-vilna-api-use","depth":3},{"value":"Addresses and wallets","id":"addresses-and-wallets","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 in the Vilna API?","id":"how-are-amounts-represented-in-the-vilna-api","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 Vilna webhook authenticity?","id":"how-do-i-verify-vilna-webhook-authenticity","depth":3},{"value":"Can I test webhooks without real transactions?","id":"can-i-test-webhooks-without-real-transactions","depth":3},{"value":"SDK and tools","id":"sdk-and-tools","depth":2},{"value":"Which programming languages does the Vilna SDK support?","id":"which-programming-languages-does-the-vilna-sdk-support","depth":3},{"value":"Do I need the SDK to use the Vilna API?","id":"do-i-need-the-sdk-to-use-the-vilna-api","depth":3},{"value":"What is the Vilna Storage Client?","id":"what-is-the-vilna-storage-client","depth":3},{"value":"Standards","id":"standards","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},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"FAQ - Frequently Asked Questions","description":"Answers to common questions about Vilna API including supported blockchains, getting started, authentication, and API key management.","priority":0.5,"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":"FAQ"}]},{"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"What blockchains does Vilna support?","acceptedAnswer":{"@type":"Answer","text":"Bitcoin, Ethereum, BNB Smart Chain, Polygon, Avalanche, Arbitrum, Optimism, Base, Solana, TRON, TON, and more. Call GET /blockchains for the current list."}},{"@type":"Question","name":"How do I get started?","acceptedAnswer":{"@type":"Answer","text":"Sign up at app.vilna.io, create a workspace and project, then generate an API key. The platform is free to use during the early access period."}},{"@type":"Question","name":"What authentication method does the API use?","acceptedAnswer":{"@type":"Answer","text":"All requests require an API key sent in the X-Api-Key header."}},{"@type":"Question","name":"What is the difference between external and HD addresses?","acceptedAnswer":{"@type":"Answer","text":"External addresses are imported directly by providing the full address string. HD addresses are derived from an extended public key (xPub) using BIP-32/44 standards, allowing programmatic generation 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, specifying chainFamily evm when creating the address automatically monitors it on all active EVM networks."}},{"@type":"Question","name":"How are amounts represented?","acceptedAnswer":{"@type":"Answer","text":"All amounts have a base field (raw integer as a string) and a formatted field (human-readable with decimals). Use base for calculations and formatted for display."}},{"@type":"Question","name":"What notification methods are supported?","acceptedAnswer":{"@type":"Answer","text":"Two types: Webhooks (HTTP POST to your endpoint) and Telegram (bot messages to a chat)."}},{"@type":"Question","name":"How do I verify webhook authenticity?","acceptedAnswer":{"@type":"Answer","text":"Every webhook delivery includes an X-Webhook-Signature header in Stripe format (t=<unix-seconds>,v1=<hex>) carrying the HMAC-SHA256 of the request body. The timestamp inside the header guards against replay attacks, and X-Webhook-Event-Id gives you a stable deduplication key across retries."}},{"@type":"Question","name":"Can I test webhooks without real transactions?","acceptedAnswer":{"@type":"Answer","text":"Yes. Use the test action endpoint to send a sample payload to your notification channel."}},{"@type":"Question","name":"Which programming languages are supported?","acceptedAnswer":{"@type":"Answer","text":"The official TypeScript SDK (@vilna/sdk) is available on npm. For other languages, generate a client from the OpenAPI specification using tools like openapi-generator."}},{"@type":"Question","name":"Do I need the SDK to use the API?","acceptedAnswer":{"@type":"Answer","text":"No. The SDK provides convenience methods and TypeScript type safety, but you can call the REST API directly from any language using standard HTTP."}},{"@type":"Question","name":"What is the Storage Client?","acceptedAnswer":{"@type":"Answer","text":"The @vilna-io/storage-client is an npm package for web applications that need to interact with the Vilna Storage browser extension for extension detection, connection, and transaction signing."}},{"@type":"Question","name":"What is CAIP?","acceptedAnswer":{"@type":"Answer","text":"Chain Agnostic Improvement Proposals, a set of standards for identifying blockchains, accounts, and assets across different networks. Vilna uses CAIP-2 for chains, CAIP-10 for accounts, and CAIP-19 for assets."}},{"@type":"Question","name":"What error format does the API use?","acceptedAnswer":{"@type":"Answer","text":"All errors follow RFC 7807 Problem Details, a standard format for machine-readable error responses."}}]}]}}},"lastModified":"2026-05-16T22:49:23.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/faq","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}