{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-get-started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Quickstart - Your First Platform API Request","projectTitle":"Vilna Docs","description":"Create a workspace and API key, query balances, register a monitoring address and configure webhook notifications.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-quickstart.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.9,"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":"Quickstart"}]},{"@type":"TechArticle","headline":"Quickstart - Your First Platform API Request","description":"Create a workspace and API key, query balances, register a monitoring address and configure webhook notifications.","url":"https://docs.vilna.io/get-started/quickstart","datePublished":"2025-09-17","dateModified":"2026-10-31","proficiencyLevel":"Beginner","dependencies":"Vilna account, browser, HTTPS webhook receiver","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-quickstart.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":"quickstart","__idx":0},"children":["Quickstart"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Register an address you control, read its balances and receive a signed webhook. Use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Try it"]}," on each linked API operation to send requests; its schema and generated examples describe the request format."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before starting, choose an EVM address you control and prepare a publicly reachable HTTPS receiver. It must accept POST requests, verify webhook signatures using the raw request body and return 2xx after safely recording a delivery. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/webhooks#verify"},"children":["signature verification"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"key","level":2,"__idx":1},"children":["Get a key "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.vilna.io"},"children":["Sign up in the dashboard"]},", create a workspace and a project, then issue a project API key. Grant ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:blockchain:read"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:address:write"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:balance:read"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:activity:read"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:channel:write"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:subscription:write"]}," for this walkthrough."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Save the full key in a secrets manager: later reads expose only a preview and metadata. Enter it as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," in the reference's authorization control. Keep it separate from the credentials used by your receiver. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before each mutation, persist a distinct ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," with the exact request body and the operation it represents. If the response is lost, retry that intent with the same key and body. Do not create a fresh key for an unknown outcome. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/idempotency"},"children":["Idempotency"]}," for replay windows and recovery."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"verify","level":2,"__idx":2},"children":["Confirm it works "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/blockchain/list-blockchains"},"children":["List blockchains"]}," and send the request with Try it. A successful response confirms that the key can read the network catalog. Save the CAIP-2 identifier of a supported EVM network for the address you chose, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}," for Ethereum. Follow pagination when reading the catalog."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"monitor","level":2,"__idx":3},"children":["Monitor an address "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/create-external-address"},"children":["Create external address"]},". Select the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from_address"]}," example, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["input.value"]}," to your own EVM address, keep ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["input.chain_family"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evm"]}," and choose a label you can recognize. Supply the saved idempotency key and send the request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the returned canonical address ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," and label for subsequent requests and reconciliation. Registration applies to its chain family; it does not transfer funds or grant Vilna signing authority. Other families have different support: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["solana"]}," registration and token resolution do not include balances or transaction monitoring. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/core-concepts"},"children":["Core concepts"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"read","level":2,"__idx":4},"children":["Read balances & activity "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/balance/summarize-balances"},"children":["Summarize balances"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["family=evm"]}," for project holdings, or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/balance/search-balances"},"children":["Search balances"]}," with the returned address in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addresses"]}," to inspect this address. Optionally restrict the search to the selected network with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chain_gids"]},". Both results are paginated and scoped to one family; request other supported families separately."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/activity/list-activity"},"children":["List activity"]}," to read balance changes. An unused address can have no balance entries or activity. Use integer strings in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," for arithmetic and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," for display; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/core-concepts#amounts"},"children":["Amounts"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"events","level":2,"__idx":5},"children":["Receive events "]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/channel/create-channel"},"children":["Create channel"]},". Give it a recognizable name, select webhook configuration, set your receiver's HTTPS URL and choose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payload_version: v2"]},". Send it with its own persisted idempotency key. Save the returned channel ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", name and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_secret"]}," immediately. Secret-bearing creation responses have a limited replay window; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/idempotency"},"children":["Idempotency"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/channel/test-channel"},"children":["Test channel"]},", supply the saved channel ID and choose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["family=evm"]},". Use a separate persisted idempotency key. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," response means the test was accepted, not delivered. Check your receiver for the signed test delivery and its 2xx response. This test checks delivery without waiting for blockchain activity and does not create a subscription."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/subscription/create-subscription"},"children":["Create subscription"]},". Give it a name, use the saved ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["channel_id"]},", set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["family=evm"]}," and select a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block"]}," trigger with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["after_blocks: 0"]},". To restrict it to the chosen network, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filters.chain_gids"]}," to that network ID. Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_noise_filtered: true"]},". Persist this intent and body before sending. Keep the returned subscription ID and name. A new configuration returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]},"; an exact configuration match can return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wait for a matching new transaction involving a monitored address. A subscription does not create blockchain activity. Confirm that your receiver verifies and records a real event, distinguished from the channel test by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_test: false"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["after_blocks: 0"]}," notification is an early inclusion signal, not finality. Apply your confirmation policy and reconcile transaction state before crediting funds. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/events#triggers"},"children":["Events and monitoring"]}," and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/channels#payment-flow"},"children":["reconciliation workflow"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the event ID for duplicate handling and the channel and subscription IDs for later management. Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/integration-patterns"},"children":["Integration patterns"]}," to extend this setup for deposits, treasury views or invoices."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"id":"next"},"children":[]}]}]},"headings":[{"value":"Quickstart","id":"quickstart","depth":1},{"value":"Get a key","id":"key","depth":2},{"value":"Confirm it works","id":"verify","depth":2},{"value":"Monitor an address","id":"monitor","depth":2},{"value":"Read balances & activity","id":"read","depth":2},{"value":"Receive events","id":"events","depth":2}],"frontmatter":{"seo":{"title":"Quickstart - Your First Platform API Request","description":"Create a workspace and API key, query balances, register a monitoring address and configure webhook notifications.","priority":0.9,"image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-quickstart.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":"Quickstart"}]},{"@type":"TechArticle","headline":"Quickstart - Your First Platform API Request","description":"Create a workspace and API key, query balances, register a monitoring address and configure webhook notifications.","url":"https://docs.vilna.io/get-started/quickstart","datePublished":"2025-09-17","dateModified":"2026-10-31","proficiencyLevel":"Beginner","dependencies":"Vilna account, browser, HTTPS webhook receiver","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-quickstart.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/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}