{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","cards","card"]},"type":"markdown"},"seo":{"title":"Core Concepts - Blockchains & Chain IDs","projectTitle":"Vilna Docs","description":"Learn key domain concepts in the Vilna API including blockchains, CAIP-2 chain IDs, namespaces, addresses, and how to identify networks.","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.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":"Guides"},{"@type":"ListItem","position":3,"name":"Core Concepts"}]},{"@type":"TechArticle","headline":"Core Concepts - Blockchains & Chain IDs","description":"Learn key domain concepts in the Vilna API including blockchains, CAIP-2 chain IDs, namespaces, addresses, and how to identify networks.","url":"https://docs.vilna.io/guides/core-concepts","datePublished":"2025-09-17","dateModified":"2026-05-26","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/previews/guides.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":["This page explains the key domain concepts you will encounter when working with the Vilna API. Each section describes what the concept is, how it is identified, and when you will use it. For full endpoint details, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/"},"children":["Platform API Reference"]},"."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart TD\n BC[\"Blockchain eip155:1\"] -->|has| ADDR[\"Address 0x...\"]\n BC -->|has| TOK[\"Token CAIP-19\"]\n ADDR -->|participates in| TX[Transaction]\n TX -->|contains| EV[\"Events transfer, fee, ...\"]\n EV -->|produces| ACT[\"Activity in/out + delta\"]\n ADDR -->|has| BAL[Balances]\n NC[\"Notification Channel Webhook / Telegram\"] -->|delivers| EV\n PK[\"Public Key xPub\"] -->|derives| ADDR\n","diagramHtml":"","diagramHtmlDark":""},"children":["flowchart TD\n BC[\"Blockchain eip155:1\"] -->|has| ADDR[\"Address 0x...\"]\n BC -->|has| TOK[\"Token CAIP-19\"]\n ADDR -->|participates in| TX[Transaction]\n TX -->|contains| EV[\"Events transfer, fee, ...\"]\n EV -->|produces| ACT[\"Activity in/out + delta\"]\n ADDR -->|has| BAL[Balances]\n NC[\"Notification Channel Webhook / Telegram\"] -->|delivers| EV\n PK[\"Public Key xPub\"] -->|derives| ADDR\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"blockchains-and-chain-ids-caip-2","__idx":1},"children":["Blockchains and chain IDs (CAIP-2)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna identifies every blockchain with a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md"},"children":["CAIP-2"]}," global identifier (GID). The format is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["namespace:reference"]}," - for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}," for Ethereum mainnet or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:137"]}," for Polygon."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can list all supported chains with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/blockchain/list-blockchains"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /blockchains"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common chain GIDs:"]},{"$$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":"GID"},"children":["GID"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Chain"},"children":["Chain"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ethereum"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:56"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BNB Smart Chain"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:137"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Polygon"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:42161"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Arbitrum One"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Solana"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the full CAIP standard reference, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/caip-standards"},"children":["CAIP Standards"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"addresses","__idx":2},"children":["Addresses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are new to blockchain addresses, keys, and derivation paths, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/blockchain-basics"},"children":["Blockchain Basics"]}," for a primer before continuing."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An address represents a blockchain account you want to monitor. There are two ways to add addresses:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["External addresses"]}," are standalone accounts you import individually with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/create-external-address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /addresses/external"]}]},". You provide the raw address value, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chainFamily"]}," (which assigns the address to all chains in that family automatically), and an optional label."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HD-derived addresses"]}," are generated from a public key (see the next section). These addresses are created sequentially and are automatically monitored once generated."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported address formats include:"]},{"$$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":"Format"},"children":["Format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example chains"},"children":["Example chains"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evm"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ethereum, Polygon, Arbitrum, BSC"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["p2pkh"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin (legacy)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["p2sh"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin (compatibility)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["p2wpkh"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin (native SegWit)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["p2wsh"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin (SegWit script)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["p2tr"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bitcoin (Taproot)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["solana"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Solana"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tron"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tron"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every address has a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}," field - a free-form JSON object where you can store application-specific data such as customer IDs, invoice numbers, or internal references. This metadata is returned in API responses and webhook payloads, so you can correlate blockchain events with your business logic."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"resolving-an-address-from-a-public-key","__idx":3},"children":["Resolving an address from a public key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have a raw public key and need the corresponding blockchain address, use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/resolve-external-address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /addresses/external/resolve"]}]},". This endpoint computes the address from the public key, creates an external address, and returns it. The public key is used only for derivation and is not stored. If an address with the computed value already exists, the existing one is returned."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.vilna.io/v1/addresses/external/resolve\" \\\n -H \"X-Api-Key: your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"publicKey\": \"02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5\",\n \"addressFormat\": \"evm\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["publicKey"]}," field accepts hex-encoded secp256k1 keys (compressed or uncompressed, with optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0x"]}," prefix) for EVM, Tron, and Bitcoin formats, or base58-encoded ed25519 keys for Solana. You can also pass optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}," fields, just like when creating an external address directly."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is useful when your system stores raw public keys (for example, from hardware wallets or key ceremonies) and you need to derive and register the on-chain address without doing the computation yourself."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List all addresses with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/list-addresses"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /addresses"]}]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"public-keys-and-hd-wallets","__idx":4},"children":["Public keys and HD wallets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you manage an HD wallet, you can import its extended public key (xPub, yPub, or zPub) with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/public_key/create-public-key"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /public_keys"]}]},". Vilna uses BIP-32 / BIP-44 / BIP-49 / BIP-84 / BIP-86 derivation paths to generate child addresses deterministically."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the public key is imported, call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/public_key/generate-next-public-key-address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /public_keys/{public_key_id}/addresses/next"]}]}," to generate the next unused address in the derivation sequence. The new address is automatically registered for monitoring on the chains associated with the public key."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This approach is ideal for exchanges and payment platforms that need a unique deposit address per customer without exposing the private key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tokens-and-assets-caip-19","__idx":5},"children":["Tokens and assets (CAIP-19)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every token or coin is identified with a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-19.md"},"children":["CAIP-19"]}," asset ID. The format is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chain_gid/asset_namespace:asset_reference"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Native tokens"]}," use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["slip44"]}," namespace:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"eip155:1/slip44:60 - ETH on Ethereum\neip155:56/slip44:60 - BNB on BSC\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Contract tokens"]}," use namespace matching the token standard:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"eip155:1/erc20:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 - USDC on Ethereum\neip155:56/erc20:0x55d398326f99059fF775485246999027B3197955 - USDT on BSC\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token metadata (name, symbol, decimals) is included in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references.tokens"]}," field of API responses."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"transactions-and-events","__idx":6},"children":["Transactions and events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A transaction represents a confirmed or pending on-chain operation. List transactions across all your addresses with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/transaction/list-transactions"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /transactions"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each transaction contains one or more ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["canonical events"]}," that describe what happened:"]},{"$$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":"Event kind"},"children":["Event kind"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token or native currency moved between addresses"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utxo_transfer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UTXO-based transfer with full input/output visibility (Bitcoin)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Gas or network fee paid"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approval"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ERC-20 spend allowance granted or changed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Smart contract method invoked"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract_create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["New smart contract deployed"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events are the building blocks for understanding what a transaction did. A single swap transaction, for example, might produce multiple ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," events and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}," event."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"activity","__idx":7},"children":["Activity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The activity feed (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/activity/list-activity"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /activity"]}]},") is a higher-level view that shows balance changes for your monitored addresses. Each entry includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["direction"]}," - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in"]}," (received) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["out"]}," (sent)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["amount"]}," - how much was gained or lost (see Amounts below)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["token"]}," - which asset changed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["address"]}," - which of your addresses was affected"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the activity feed when you need a simple \"what came in, what went out\" view without parsing raw transaction events."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"balances","__idx":8},"children":["Balances"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Query the current holdings of your addresses with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/balance/list-balances"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /balances"]}]}," (all addresses) or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/list-address-balances"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /addresses/{address}/balances"]}]}," (single address). The response lists each token held along with its amount."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Balances are updated automatically as new transactions are indexed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"amounts","__idx":9},"children":["Amounts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All monetary values in the API are returned as an object with two fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"base\": \"1000000\",\n \"formatted\": \"1.0\"\n}\n","lang":"json"},"children":[]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The raw integer amount in the token's smallest unit (e.g., wei for ETH, satoshi for BTC)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The human-readable decimal value after applying the token's decimal places"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," for arithmetic and storage. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," for display purposes only."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Use base for arithmetic"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," for calculations and storage. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]}," value is for display only and may lose precision for very large or very small amounts."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notification-channels","__idx":10},"children":["Notification channels"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A notification channel defines a destination for real-time event delivery. Vilna supports two channel kinds:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook"]}," - Vilna sends an HTTP POST to your URL whenever a relevant event occurs. Each delivery is signed with HMAC-SHA256 in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Signature"]}," header (Stripe format). See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication#webhook-signature-verification"},"children":["Authentication"]}," for verification details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Telegram"]}," - Events are delivered to a Telegram chat."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a channel with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/channel/create-channel"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /channels"]}]}," and test it with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/channel/test-channel"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /channels/{channel_id}/actions/test"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Channels are global to your project. All monitored addresses deliver events to all active channels."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-references-pattern","__idx":11},"children":["The references pattern"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List and detail responses include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," object that contains related entities so you can resolve IDs without extra API calls."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n API[API Response] --> ITEM[item / items]\n API --> REF[references]\n API --> META[\"meta page, limit, total\"]\n REF --> TOKENS[\"tokens name, symbol, decimals\"]\n REF --> CHAINS[\"blockchains name, gid\"]\n REF --> ADDRS[\"addresses label, meta\"]\n ITEM -.->|asset_gid| TOKENS\n ITEM -.->|chain_gid| CHAINS\n","diagramHtml":"","diagramHtmlDark":""},"children":["flowchart LR\n API[API Response] --> ITEM[item / items]\n API --> REF[references]\n API --> META[\"meta page, limit, total\"]\n REF --> TOKENS[\"tokens name, symbol, decimals\"]\n REF --> CHAINS[\"blockchains name, gid\"]\n REF --> ADDRS[\"addresses label, meta\"]\n ITEM -.->|asset_gid| TOKENS\n ITEM -.->|chain_gid| CHAINS\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a single-item response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"item\": { \"...\": \"...\" },\n \"references\": {\n \"tokens\": { \"eip155:1/slip44:60\": { \"name\": \"ETH\", \"...\": \"...\" } },\n \"blockchains\": { \"eip155:1\": { \"name\": \"Ethereum\", \"...\": \"...\" } },\n \"addresses\": { \"eip155:1:0x742d...\": { \"...\": \"...\" } }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a list response:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"items\": [ \"...\" ],\n \"meta\": {\n \"limit\": 30,\n \"page\": 1,\n \"total\": 142,\n \"total_pages\": 5\n },\n \"references\": { \"...\": \"...\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}," object provides pagination info. Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," query parameters to navigate pages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errors","__idx":12},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API returns errors in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tools.ietf.org/html/rfc7807"},"children":["RFC 7807"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/problem+json"]}," format:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"type\": \"https://docs.vilna.io/errors/validation\",\n \"title\": \"Validation Error\",\n \"status\": 422,\n \"detail\": \"One or more fields are invalid.\",\n \"fields\": [\n { \"name\": \"address.value\", \"reason\": \"must be a valid blockchain address\" }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fields"]}," array pinpoints exactly which inputs failed and why."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":13},"children":["Further reading"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"CAIP Standards","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/apis/platform/caip-standards"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Full reference for CAIP-2, CAIP-10, and CAIP-19 identifiers"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Authentication","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/authentication"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API keys, webhook signatures, and security best practices"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Integration Patterns","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/integration-patterns"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common architectures built on these concepts"]}]},{"$$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 key management endpoints"]}]}]}]},"headings":[{"value":"Core concepts","id":"core-concepts","depth":1},{"value":"Blockchains and chain IDs (CAIP-2)","id":"blockchains-and-chain-ids-caip-2","depth":2},{"value":"Addresses","id":"addresses","depth":2},{"value":"Resolving an address from a public key","id":"resolving-an-address-from-a-public-key","depth":3},{"value":"Public keys and HD wallets","id":"public-keys-and-hd-wallets","depth":2},{"value":"Tokens and assets (CAIP-19)","id":"tokens-and-assets-caip-19","depth":2},{"value":"Transactions and events","id":"transactions-and-events","depth":2},{"value":"Activity","id":"activity","depth":2},{"value":"Balances","id":"balances","depth":2},{"value":"Amounts","id":"amounts","depth":2},{"value":"Notification channels","id":"notification-channels","depth":2},{"value":"The references pattern","id":"the-references-pattern","depth":2},{"value":"Errors","id":"errors","depth":2},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"Core Concepts - Blockchains & Chain IDs","description":"Learn key domain concepts in the Vilna API including blockchains, CAIP-2 chain IDs, namespaces, addresses, and how to identify networks.","priority":0.7,"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":"Core Concepts"}]},{"@type":"TechArticle","headline":"Core Concepts - Blockchains & Chain IDs","description":"Learn key domain concepts in the Vilna API including blockchains, CAIP-2 chain IDs, namespaces, addresses, and how to identify networks.","url":"https://docs.vilna.io/guides/core-concepts","datePublished":"2025-09-17","dateModified":"2026-05-26","proficiencyLevel":"Beginner","image":"https://cdn.vilna.io/docs/previews/guides.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-05-26T20:25:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/core-concepts","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}