{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-get-started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["quickfacts","fact","howvilna","trust","trustcell","patternfinder","patterncard"]},"type":"markdown"},"seo":{"title":"Core Concepts - How the Vilna Platform Works","projectTitle":"Vilna Docs","description":"Platform monitoring, RPC access, workspace administration and the separate VKS signing workflow.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-core-concepts.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.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":"Get Started","item":"https://docs.vilna.io/get-started"},{"@type":"ListItem","position":3,"name":"Core Concepts"}]},{"@type":"TechArticle","headline":"Core Concepts - How the Vilna Platform Works","description":"Platform monitoring, RPC access, workspace administration and the separate VKS signing workflow.","url":"https://docs.vilna.io/get-started/core-concepts","datePublished":"2025-09-17","dateModified":"2026-10-31","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-core-concepts.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":"core-concepts","__idx":0},"children":["Core concepts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Vilna Platform API monitors addresses, wallets and incoming payments and returns normalized data through a REST API and event notifications. It uses public chain data. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/networks#table"},"children":["Networks"]}," for supported mainnets and testnets; Solana supports address registration and the token catalog only."]},{"$$mdtype":"Tag","name":"QuickFacts","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"lock"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Non-custodial"]}," by design"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"globe"},"children":["One API, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["9"]}," networks"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"check-double"},"children":["Open ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["standards"]}]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"scale"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No cut"]}," of your funds"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"how","level":2,"__idx":1},"children":["How Vilna works "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Platform API provides normalized public-chain data for your application. Depending on the network, it registers addresses, reads balances and transactions, tracks confirmations and sends notifications at your selected trigger. Check the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/networks"},"children":["network matrix"]}," for the available capabilities."]},{"$$mdtype":"Tag","name":"HowVilna","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because it only ever reads chain data, the Platform API works exclusively with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["public information"]},": blockchain addresses and extended public keys. It never asks for, holds, or stores private keys or seed phrases, and it cannot sign or broadcast a transaction. Your keys and funds stay exactly where they are."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These monitoring principles describe Platform API. VKS is a separate signing workflow; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#surfaces"},"children":["APIs for different tasks"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"principles","level":2,"__idx":2},"children":["Built safely and openly "]},{"$$mdtype":"Tag","name":"Trust","attributes":{"title":"Core guarantees","icon":"shield"},"children":[{"$$mdtype":"Tag","name":"TrustCell","attributes":{"title":"Non-custodial","icon":"lock"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Platform monitoring uses public chain data: addresses and public keys, never private keys or seed phrases. It cannot move your funds."]}]},{"$$mdtype":"Tag","name":"TrustCell","attributes":{"title":"No cut of your funds","icon":"scale"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because Platform monitoring never touches your money, it never takes a percentage of any payment or transaction it observes."]}]},{"$$mdtype":"Tag","name":"TrustCell","attributes":{"title":"Standards-first","icon":"check-double"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open specifications throughout: CAIP ids for chains and assets, BIP-32/44 derivation, RFC 7807 errors. No proprietary formats."]}]},{"$$mdtype":"Tag","name":"TrustCell","attributes":{"title":"Chain-agnostic","icon":"globe"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One REST API and one response shape across every network. Adding a chain doesn't change your integration."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"surfaces","level":2,"__idx":3},"children":["APIs for different tasks "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each service has its own credential and scope. Create the workspace and keys in the Dashboard, then use the documented public operations:"]},{"$$mdtype":"Tag","name":"PatternFinder","attributes":{},"children":[{"$$mdtype":"Tag","name":"PatternCard","attributes":{"to":"/apis/platform","title":"Platform API","tags":"Addresses, Balances, Transactions, Invoices, Webhooks"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Monitor addresses and wallets, read balances and transactions, reconcile incoming payments, and get notified on activity."]}]},{"$$mdtype":"Tag","name":"PatternCard","attributes":{"to":"/apis/rpc","title":"Blockchain RPC","tags":"JSON-RPC, gRPC, Every chain"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Talk to blockchain nodes directly across every supported network through a single endpoint and one key, with no infrastructure to run."]}]},{"$$mdtype":"Tag","name":"PatternCard","attributes":{"to":"/apis/mgmt","title":"Management API","tags":"Workspaces, Projects, Members, Keys"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use published workspace, project and member operations; credential bootstrap and some key actions require the Dashboard."]}]},{"$$mdtype":"Tag","name":"PatternCard","attributes":{"to":"/apis/vks","title":"VKS API","tags":"Signers, Vaults, Accounts, Signing"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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":"p","attributes":{},"children":["New to the underlying ideas - addresses, keys and HD derivation? Start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/blockchain-basics"},"children":["Blockchain basics"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"amounts","level":2,"__idx":4},"children":["Data you can rely on "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For Platform API events, whatever chain an event comes from, the response shape is the same, so your code is written once, not once per network."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Amounts."]}," Many transaction and balance fields carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," (an integer string in the token's smallest unit) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," (display text). Authenticated invoice ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["received_amount"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed_amount"]}," are plain base-unit strings; the public invoice view instead has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," and optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]},". Follow each field's schema. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BigInt"]}," or an exact decimal library for calculations, and the exact token's metadata decimals for display. See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/invoices#check-invoice-status"},"children":["invoice formatter"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resolved references."]}," Responses include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," object with the related tokens, chains and addresses, so you can render a result without extra lookups."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stable identifiers."]}," Chains, accounts and assets are named with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/standards#caip"},"children":["CAIP"]}," ids, one identifier shape everywhere."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform"},"children":["Platform API"]}," for the full resource reference and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/standards"},"children":["Standards"]}," for the identifier formats."]}]},"headings":[{"value":"Core concepts","id":"core-concepts","depth":1},{"value":"How Vilna works","id":"how","depth":2},{"value":"Built safely and openly","id":"principles","depth":2},{"value":"APIs for different tasks","id":"surfaces","depth":2},{"value":"Data you can rely on","id":"amounts","depth":2}],"frontmatter":{"seo":{"title":"Core Concepts - How the Vilna Platform Works","description":"Platform monitoring, RPC access, workspace administration and the separate VKS signing workflow.","priority":0.7,"image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-core-concepts.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":"Core Concepts"}]},{"@type":"TechArticle","headline":"Core Concepts - How the Vilna Platform Works","description":"Platform monitoring, RPC access, workspace administration and the separate VKS signing workflow.","url":"https://docs.vilna.io/get-started/core-concepts","datePublished":"2025-09-17","dateModified":"2026-10-31","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-core-concepts.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-10-31T22:07:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/get-started/core-concepts","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}