{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-get-started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["quickfacts","fact","tilegrid","tile","intent","intentcell","admonition","flow","step","hdtree","format","part","endpoint"]},"type":"markdown"},"seo":{"title":"Blockchain Basics - Keys, Addresses, Chains","projectTitle":"Vilna Docs","description":"A primer on the blockchain concepts behind Vilna - addresses, keys, HD wallets, derivation paths, chain and asset IDs, amounts and confirmations.","siteUrl":"https://docs.vilna.io","lang":"en-US","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-blockchain-basics.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":"Blockchain Basics"}]},{"@type":"TechArticle","headline":"Blockchain Basics - Keys, Addresses, Chains","description":"A from-zero primer on the blockchain concepts behind Vilna - addresses, keys, HD wallets, derivation paths, chain and asset IDs, amounts and confirmations.","url":"https://docs.vilna.io/get-started/blockchain-basics","datePublished":"2025-09-17","dateModified":"2026-11-01","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-blockchain-basics.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":"blockchain-basics-for-developers","__idx":0},"children":["Blockchain basics for developers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Learn how addresses, public keys, amounts and confirmations appear in Vilna’s API. No blockchain experience is required. Already familiar with these concepts? Start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/core-concepts"},"children":["Core concepts"]},"."]},{"$$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"]}," - Vilna never holds funds"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"shield-check"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Read-only"]}," - public keys only"]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"globe"},"children":["One shape across ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every chain"]}]}," ",{"$$mdtype":"Tag","name":"Fact","attributes":{"icon":"layers"},"children":["Built on open standards"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"mental-model","level":2,"__idx":1},"children":["What a blockchain is "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Forget the hype for a moment. For an integration, a blockchain is just a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["shared record book"]}," that everyone can read and no one can secretly edit. New transactions extend that record; reorganizations can replace recent blocks."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Three properties are all you need to hold in your head:"]},{"$$mdtype":"Tag","name":"TileGrid","attributes":{"cols":"3"},"children":[{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"globe","title":"Public"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every transaction and balance is visible to anyone. There are no private queries to run; you just read the chain."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"database","title":"Append-only"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Blocks normally extend the chain, but a reorganization can replace recent blocks and change which transactions are included. Reconcile current state before relying on a receipt."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"layers","title":"Grouped into blocks"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["New records are bundled into ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["blocks"]}," added one after another. A block's position is its place in time."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A public ledger can be monitored using an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["address"]},", without the wallet owner's permission. Platform monitoring reads that public data."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"vilnas-role","level":3,"__idx":2},"children":["Where Platform monitoring sits "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reading a chain yourself means running nodes, indexing blocks, handling reorgs and decoding every transaction format, all of it per chain. Platform does that for supported networks and returns normalized data. Platform monitoring ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["observes"]}," the chain:"]},{"$$mdtype":"Tag","name":"Intent","attributes":{},"children":[{"$$mdtype":"Tag","name":"IntentCell","attributes":{"label":"What Platform monitoring needs","icon":"shield-check"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["address"]}," or a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["public key"]},". That is enough to watch balances, detect incoming funds and notify you."]}]},{"$$mdtype":"Tag","name":"IntentCell","attributes":{"label":"What Platform monitoring does not need","icon":"lock"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["private key"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["seed phrase"]},". Platform monitoring does not sign transactions, broadcast them or move funds."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Non-custodial means non-custodial"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Platform monitoring reads public chain data and reports what happened. VKS is a separate workflow for signer approvals, signing and optional transaction submission; see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/vks"},"children":["VKS guide"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"keys-addresses","level":2,"__idx":3},"children":["Keys and addresses "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For an address controlled by one private key, the relationship between the key and address looks like this:"]},{"$$mdtype":"Tag","name":"Flow","attributes":{},"children":[{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Private key"]}," - the secret used to sign transactions for the corresponding blockchain account. Whoever holds it can spend the funds, so it must never leave your control."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Public key"]}," - derived from the private key with one-way math. Safe to share. You can go from private to public, but never back."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Address"]}," - a short, shareable identifier derived from the public key. This is the \"account number\" people send funds to."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The takeaway for integration: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["the address and public key are safe to share; the private key is not."]}," Platform monitoring uses the public side: provide a public key or address to watch it. It does not need the private key."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Guard the private key"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Anyone with the private key (or the seed phrase it comes from) controls the funds. Never put it in code, logs, screenshots, or a request to any API, including Vilna. Platform monitoring does not need it."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"address-formats","level":3,"__idx":4},"children":["Reading an address "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Address formats can suggest a chain family, but the address alone does not identify the network. Check the chain identifier as well as the address before sending:"]},{"$$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":"Chain family"},"children":["Chain family"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Looks like"},"children":["Looks like"]},{"$$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":["EVM (Ethereum, Polygon, BSC, Arbitrum, Base…)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0x"]}," + 40 hex chars"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0x742d…7B123"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin - Legacy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1A1zP1…DivfNa"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin - SegWit-compatible"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3J98t1…hWNLy"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin - Native SegWit"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bc1q"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bc1qar0…f5mdq"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin - Taproot"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bc1p"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bc1p5d7…g3s7p"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TRON"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["T"]},", 34 chars"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TXk7…m4Qa"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Solana"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["base58, ~44 chars"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5eykt4…KvdpZ"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One convenient detail of EVM chains: a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0x…"]}," address works on ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["every"]}," EVM network. The same Ethereum address can receive funds on Polygon, Arbitrum or Base without any change."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you register an address with Vilna you pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["input.chain_family"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evm"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bitcoin"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tron"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["solana"]}," registers the address and resolves its tokens, without balances or transactions) and the exact format is auto-detected from the value; see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform"},"children":["Platform API"]}," for the endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"hd-wallets","level":2,"__idx":5},"children":["One wallet, many addresses "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Real products need a fresh address per customer, sometimes thousands of them. Generating and backing up thousands of independent secrets is unmanageable. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HD wallets"]}," (Hierarchical Deterministic) solve this with a single starting secret."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You begin with one ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["seed phrase"]},", typically 12 or 24 words. From that seed, the wallet can generate an unlimited tree of key pairs. ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Deterministic"]}," means the same seed always produces the same keys, in the same order, forever. A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["derivation path"]}," is the route down that tree to one specific key: pick a branch at each level and you arrive at a single address:"]},{"$$mdtype":"Tag","name":"HdTree","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One seed backup covers the derived addresses; a fresh address per customer is the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/integration-patterns#exchanges"},"children":["exchange monitoring pattern"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"xpub-paths","level":2,"__idx":6},"children":["Extended public keys and derivation paths "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To let Vilna generate and watch that tree of addresses without ever touching the secret, you share an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["extended public key"]},": a special public key that can produce child addresses (and only addresses, never signatures). Bitcoin has three flavours, one per address style:"]},{"$$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":"Key prefix"},"children":["Key prefix"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Standard"},"children":["Standard"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Generates"},"children":["Generates"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["xPub"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-44"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Legacy addresses (start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yPub"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-49"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["SegWit-compatible addresses (start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zPub"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-84"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Native SegWit addresses (start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bc1q"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For EVM chains you use an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["xPub"]}," (BIP-44). For Bitcoin Taproot there is no single-letter prefix; use an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["xPub"]}," with the Taproot path below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"derivation-paths","level":3,"__idx":7},"children":["How a derivation path works "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A derivation path is the \"address inside the tree\", like a folder path that points at one exact key. It reads left to right, narrowing from the master key down to a single address:"]},{"$$mdtype":"Tag","name":"Format","attributes":{"line":"m/44'/60'/0'/0/0","result":"one address"},"children":[{"$$mdtype":"Tag","name":"Part","attributes":{"token":"m","eg":"master key"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The root of the tree - your wallet's master key. Everything descends from here."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"44'","eg":"BIP-44"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Purpose"]}," - which standard the path follows: 44, 49, 84 or 86."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"60'","eg":"Ethereum"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Coin type"]}," - which blockchain, from the SLIP-44 registry: 60 = ETH, 0 = BTC, 195 = TRON, 501 = Solana."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"0'","eg":"account #0"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account"]}," - lets one wallet hold separate sub-wallets. Almost always 0."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"0","eg":"receiving"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Change"]}," - 0 for addresses that receive funds, 1 for internal change addresses."]}]},{"$$mdtype":"Tag","name":"Part","attributes":{"token":"0","eg":"first address"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Index"]}," - the address number. Bump it for each new address: 0, 1, 2, 3…"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The apostrophe (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'"]},") after a number means ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["hardened"]},": a safety feature that stops a child key from being used to work backward to its parent. You will mostly copy known-good paths rather than hand-build them:"]},{"$$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":"Path"},"children":["Path"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use it for"},"children":["Use it for"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Standard"},"children":["Standard"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["m/44'/60'/0'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ethereum and all EVM chains"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-44"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["m/84'/0'/0'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin - Native SegWit"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-84"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["m/86'/0'/0'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin - Taproot"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-86"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["m/44'/0'/0'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin - Legacy"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-44"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["m/44'/195'/0'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TRON"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-44"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["m/44'/501'/0'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Solana"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BIP-44"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Match your wallet"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Export the extended public key for the account and address format you plan to monitor. Keep the wallet's derivation path with it; the table lists common account-level paths."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Import the extended public key with ",{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"/public-keys"},"children":[]},", then call ",{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"/public-keys/{public_key_id}/addresses"},"children":[]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"chain_family\": \"evm\", \"selection\": {\"kind\": \"next\"}"]}," in the body to mint the next address in the sequence. Each one is registered for monitoring automatically."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"get-xpub","level":3,"__idx":8},"children":["Getting your xPub "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most wallets can export an extended public key. The three most common sources:"]},{"$$mdtype":"Tag","name":"TileGrid","attributes":{"cols":"3"},"children":[{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"shield","title":"Ledger Live"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open an account, go to Advanced settings, and copy the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Extended Public Key"]},"."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"shield","title":"Trezor Suite"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Open an account and choose ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Show xPub"]},"."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"alert","title":"MetaMask"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Account-based, so it can't export an xPub. Import individual addresses into Vilna instead."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Export the public key using your wallet. Never send a seed phrase or private key to Vilna. Then ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/public_key/create-public-key"},"children":["register the extended public key"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/public_key/generate-public-key-addresses"},"children":["derive addresses"]},"; the operation pages contain parameters and request examples."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"The seed is the keys"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The mnemonic (seed phrase) can regenerate every private key in the wallet. Never expose it in code, logs or version control. For HD address derivation, Platform monitoring needs the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["xPub"]},", not the mnemonic."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"identifiers","level":2,"__idx":9},"children":["Naming chains and assets "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With dozens of chains and thousands of tokens, a phrase like \"USDT on BSC\" isn't precise enough for code to act on: there are test networks, bridged copies and look-alike contracts. So Vilna leans on two open standards that turn any chain or asset into ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one exact, unambiguous string"]}," you and the API both agree on: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CAIP-2"]}," names a chain, and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CAIP-19"]}," names an asset on that chain."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You rarely type these by hand; Vilna returns them ready-made in every response. The goal here is just to ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["recognize"]}," one when you see it. Read it left to right: a chain, optionally followed by the asset living on it."]},{"$$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":"What you mean"},"children":["What you mean"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"The ID Vilna uses"},"children":["The ID Vilna uses"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ethereum, the network"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BNB Smart Chain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:56"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BTC, the native coin"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bip122:…/slip44:0"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["USDT on Ethereum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1/erc20:0xdAC17…831ec7"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Don't memorize the structure"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You don't need to learn how these IDs are built to use the API. When you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["do"]}," need the segment-by-segment anatomy of CAIP-2 (chains), CAIP-10 (accounts) and CAIP-19 (assets), it's all in one place: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/standards#caip"},"children":["Standards"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"coins-vs-tokens","level":3,"__idx":10},"children":["Native coins vs tokens "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One distinction worth holding onto, because it shapes how balances and fees work. Every chain has one built-in currency, plus any number of tokens layered on top:"]},{"$$mdtype":"Tag","name":"TileGrid","attributes":{"cols":"2"},"children":[{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"zap","title":"Native coin"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The chain's own currency, used to pay transaction fees: ETH on Ethereum, BTC on Bitcoin, SOL on Solana, TRX on TRON. There is exactly one per chain."]}]},{"$$mdtype":"Tag","name":"Tile","attributes":{"icon":"database","title":"Token"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A currency built on top of a chain via a smart contract: USDT, USDC, DAI and thousands more. On EVM these follow the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ERC-20"]}," standard (fungible) or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ERC-721"]}," (NFTs); TRON calls its equivalent ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TRC-20"]},". A chain can carry unlimited tokens."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The supported chain list is available from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform"},"children":["Platform API"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"amounts","level":2,"__idx":11},"children":["Reading amounts "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Blockchains store amounts as whole numbers in a coin's smallest unit (think cents, not dollars, but often with 18 decimal places). Many transaction and balance amounts have two fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"base\": \"1500000000000000000\",\n  \"formatted\": \"1.5\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}]}," - the raw integer in the smallest unit (wei for ETH, satoshi for BTC). Exact, never rounded."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}]}," - the human-readable decimal, ready to print in a UI."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Always do math on base"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," for every calculation, comparison and stored balance; it can't lose precision. Treat ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," as display-only; it may round very large or very small values."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Invoice amount fields differ; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/get-started/core-concepts#amounts"},"children":["Core concepts"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"confirmations","level":2,"__idx":12},"children":["From pending to final "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A transaction isn't trustworthy the instant it's sent. It earns certainty as the chain grows on top of it. Understanding these stages is what stops you from crediting money that later disappears:"]},{"$$mdtype":"Tag","name":"Flow","attributes":{},"children":[{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Broadcast."]}," The transaction is sent to the network and waits in a holding area called the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mempool"]},". At this point it is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},": visible, but not yet part of the chain."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["First confirmation."]}," A miner or validator packs it into a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["block"]},". It is now on-chain: that is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1 confirmation"]},"."]}]},{"$$mdtype":"Tag","name":"Step","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["More confirmations."]}," Every new block stacked on top adds another confirmation. The more confirmations, the smaller the chance the transaction is ever reversed."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confirmation and finality rules differ by network. Choose a confirmation policy for your application rather than treating a fixed block count as a universal guarantee."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Vilna tracks this for you"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You don't count confirmations yourself: Vilna notifies once per subscription. A subscription's trigger decides the moment: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block"]}," waits a fixed number of blocks after inclusion (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["after_blocks: 0"]}," reports the transaction as seen, not final), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["network"]}," waits for the chain's own confirmation policy, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mempool"]}," (Bitcoin) fires before inclusion. Want both an early and a later confirmation signal? Create two subscriptions with different triggers. A reported transaction can still drop out in a reorganization; there is no follow-up notice, check the API if you need certainty. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/events#lifecycle"},"children":["Events & monitoring"]}," for the full trigger model."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"span","attributes":{"id":"next"},"children":[]}]}]},"headings":[{"value":"Blockchain basics for developers","id":"blockchain-basics-for-developers","depth":1},{"value":"What a blockchain is","id":"mental-model","depth":2},{"value":"Where Platform monitoring sits","id":"vilnas-role","depth":3},{"value":"Keys and addresses","id":"keys-addresses","depth":2},{"value":"Reading an address","id":"address-formats","depth":3},{"value":"One wallet, many addresses","id":"hd-wallets","depth":2},{"value":"Extended public keys and derivation paths","id":"xpub-paths","depth":2},{"value":"How a derivation path works","id":"derivation-paths","depth":3},{"value":"Getting your xPub","id":"get-xpub","depth":3},{"value":"Naming chains and assets","id":"identifiers","depth":2},{"value":"Native coins vs tokens","id":"coins-vs-tokens","depth":3},{"value":"Reading amounts","id":"amounts","depth":2},{"value":"From pending to final","id":"confirmations","depth":2}],"frontmatter":{"seo":{"title":"Blockchain Basics - Keys, Addresses, Chains","description":"A primer on the blockchain concepts behind Vilna - addresses, keys, HD wallets, derivation paths, chain and asset IDs, amounts and confirmations.","priority":0.5,"image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-blockchain-basics.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":"Blockchain Basics"}]},{"@type":"TechArticle","headline":"Blockchain Basics - Keys, Addresses, Chains","description":"A from-zero primer on the blockchain concepts behind Vilna - addresses, keys, HD wallets, derivation paths, chain and asset IDs, amounts and confirmations.","url":"https://docs.vilna.io/get-started/blockchain-basics","datePublished":"2025-09-17","dateModified":"2026-11-01","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/og/26103121/en/get-started-blockchain-basics.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-10-31T22:57:01.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/get-started/blockchain-basics","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}