{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","cards","card"]},"type":"markdown"},"seo":{"title":"Integration Patterns - Common API Use Cases","projectTitle":"Vilna Docs","description":"Five common integration scenarios with step-by-step API call sequences for typical Vilna use cases like deposit monitoring and balance tracking.","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":"Integration Patterns"}]},{"@type":"TechArticle","headline":"Integration Patterns - Common API Use Cases","description":"Five common integration scenarios with step-by-step API call sequences for typical Vilna use cases like deposit monitoring and balance tracking.","url":"https://docs.vilna.io/guides/integration-patterns","datePublished":"2025-09-17","dateModified":"2026-05-26","proficiencyLevel":"Intermediate","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":"integration-patterns","__idx":0},"children":["Integration patterns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide walks through five common integration scenarios. Each pattern describes the goal, the API calls involved, and the sequence of operations. For full request and response schemas, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/"},"children":["Platform API Reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-blockchain-deposit-detection","__idx":1},"children":["1. Blockchain deposit detection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Goal:"]}," Monitor customer deposit addresses and react to incoming funds in real time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When to use:"]}," Payment platforms, exchange deposit flows, and any service that needs to credit user accounts when crypto arrives."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works","__idx":2},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Import your HD wallet public key (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/public_key/create-public-key"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /public_keys"]}]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate a unique deposit address for each customer (",{"$$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"]}]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a webhook notification channel (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/channel/create-channel"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /channels"]}]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When funds arrive, Vilna delivers a webhook event to your server."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your server verifies the signature, matches the address to a customer, and credits their account."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sequence","__idx":3},"children":["Sequence"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant C as Customer\n participant S as Your Server\n participant V as Vilna\n participant BC as Blockchain\n\n C->>S: Request deposit address\n S->>V: POST /public_keys/{public_key_id}/addresses/next\n V-->>S: New address\n S-->>C: Show address\n C->>BC: Send funds\n BC->>V: Detect transaction\n V->>S: Webhook POST\n S->>S: Verify signature\n S->>S: Credit account\n S-->>C: Deposit confirmed\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant C as Customer\n participant S as Your Server\n participant V as Vilna\n participant BC as Blockchain\n\n C->>S: Request deposit address\n S->>V: POST /public_keys/{public_key_id}/addresses/next\n V-->>S: New address\n S-->>C: Show address\n C->>BC: Send funds\n BC->>V: Detect transaction\n V->>S: Webhook POST\n S->>S: Verify signature\n S->>S: Credit account\n S-->>C: Deposit confirmed\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-code","__idx":4},"children":["Key code"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# 1. Import xPub\ncurl -X POST \"https://api.vilna.io/v1/public_keys\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"value\": \"xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...\",\n \"label\": \"Customer Deposits\",\n \"derivation_path\": \"m/84h/0h/0h\"\n }'\n\n# 2. Generate next address for a new customer\ncurl -X POST \"https://api.vilna.io/v1/public_keys/{pubkey_id}/addresses/next\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\"\n\n# 3. Create webhook channel\ncurl -X POST \"https://api.vilna.io/v1/channels\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Deposit Webhooks\",\n \"config\": {\n \"kind\": \"webhook\",\n \"url\": \"https://your-app.example.com/deposits/webhook\",\n \"headers\": {}\n }\n }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"import { createVilnaClient } from \"@vilna/sdk\";\n\nconst client = createVilnaClient({\n apiKey: process.env.VILNA_API_KEY!,\n});\n\n// 1. Import xPub\nconst { data: pubKey } = await client.POST(\"/public_keys\", {\n body: {\n value: \"xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...\",\n label: \"Customer Deposits\",\n derivation_path: \"m/84'/0'/0'\",\n },\n});\n\n// 2. Generate next deposit address\nconst { data: address } = await client.POST(\n \"/public_keys/{public_key_id}/addresses/next\",\n { params: { path: { public_key_id: pubKey!.item.id } } }\n);\nconsole.log(\"Deposit address:\", address?.item.value);\n\n// 3. Create webhook channel\nawait client.POST(\"/channels\", {\n body: {\n name: \"Deposit Webhooks\",\n config: {\n kind: \"webhook\",\n url: \"https://your-app.example.com/deposits/webhook\",\n headers: {},\n },\n },\n});\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"design-considerations","__idx":5},"children":["Design considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Id"]}," (or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_id"]}," body field) to prevent double-crediting on retries — it is stable across retry attempts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store the mapping between generated addresses and customer IDs in your database."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify webhook signatures before processing. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication#webhook-signature-verification"},"children":["Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-portfolio-tracker","__idx":6},"children":["2. Portfolio tracker"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Goal:"]}," Show users an aggregated view of their holdings and recent activity across multiple chains."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When to use:"]}," Wallet dashboards, accounting tools, and portfolio analytics products."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works-1","__idx":7},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Import each user address with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/create-external-address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /addresses/external"]}]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Poll ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/balance/list-balances"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /balances"]}]}," for current holdings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Poll ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/activity/list-activity"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /activity"]}]}," for recent balance changes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references.tokens"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references.blockchains"]}," from the response to display token names and chain info without extra lookups."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sequence-1","__idx":8},"children":["Sequence"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant A as Your App\n participant V as Vilna\n\n A->>V: POST /addresses/external (for each address)\n V-->>A: Address created\n A->>V: GET /balances\n V-->>A: Balance list\n A->>V: GET /activity?limit=50\n V-->>A: Activity feed\n A->>A: Render dashboard\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant A as Your App\n participant V as Vilna\n\n A->>V: POST /addresses/external (for each address)\n V-->>A: Address created\n A->>V: GET /balances\n V-->>A: Balance list\n A->>V: GET /activity?limit=50\n V-->>A: Activity feed\n A->>A: Render dashboard\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-code-1","__idx":9},"children":["Key code"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Add an address\ncurl -X POST \"https://api.vilna.io/v1/addresses/external\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"value\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n \"chainFamily\": \"evm\",\n \"label\": \"Main Wallet\"\n }'\n\n# Fetch balances\ncurl \"https://api.vilna.io/v1/balances?limit=30&page=1\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\"\n\n# Fetch recent activity\ncurl \"https://api.vilna.io/v1/activity?limit=50&page=1\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Add an address for monitoring on all EVM chains\nawait client.POST(\"/addresses/external\", {\n body: {\n value: \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n chainFamily: \"evm\",\n label: \"Main Wallet\",\n },\n});\n\n// Fetch aggregated balances\nconst { data: balances } = await client.GET(\"/balances\", {\n params: { query: { limit: 30, page: 1 } },\n});\n\n// Fetch recent activity\nconst { data: activity } = await client.GET(\"/activity\", {\n params: { query: { limit: 50, page: 1 } },\n});\n\n// Token details are already keyed by GID in references\nconst tokens = balances?.references.tokens ?? {};\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"design-considerations-1","__idx":10},"children":["Design considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta.total_pages"]}," value to implement pagination or infinite scroll."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," object in each response includes token and chain metadata, so you don't need extra API calls for display names."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For real-time updates, combine polling with a webhook channel."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-hd-wallet-management","__idx":11},"children":["3. HD wallet management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Goal:"]}," Manage a hierarchical deterministic wallet where new addresses are derived on demand and automatically monitored."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When to use:"]}," Custody platforms, exchange hot wallets, and any system that generates addresses from a master public key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works-2","__idx":12},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Import the extended public key (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/public_key/create-public-key"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /public_keys"]}]},") with its derivation path."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Whenever you need a fresh address, 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"]}]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Vilna tracks the derivation index and starts monitoring the new address immediately."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Query balances and transactions across all derived addresses using ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/balance/list-balances"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /balances"]}]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/transaction/list-transactions"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /transactions"]}]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sequence-2","__idx":13},"children":["Sequence"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant S as Your Server\n participant V as Vilna\n\n S->>V: POST /public_keys (xpub + derivation path)\n V-->>S: Public key ID\n S->>V: POST /public_keys/{public_key_id}/addresses/next\n V-->>S: Derived address\n S->>V: GET /addresses\n V-->>S: Address list\n S->>V: GET /balances\n V-->>S: Aggregated balances\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant S as Your Server\n participant V as Vilna\n\n S->>V: POST /public_keys (xpub + derivation path)\n V-->>S: Public key ID\n S->>V: POST /public_keys/{public_key_id}/addresses/next\n V-->>S: Derived address\n S->>V: GET /addresses\n V-->>S: Address list\n S->>V: GET /balances\n V-->>S: Aggregated balances\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-code-2","__idx":14},"children":["Key code"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Import the extended public key\ncurl -X POST \"https://api.vilna.io/v1/public_keys\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"value\": \"xpub6BosfCnifzxRT1QKLpFfcUrgWmLqoJcGt...\",\n \"label\": \"Exchange Hot Wallet\",\n \"derivation_path\": \"m/44h/60h/0h\"\n }'\n\n# Generate addresses as needed\ncurl -X POST \"https://api.vilna.io/v1/public_keys/{pubkey_id}/addresses/next\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Import xPub\nconst { data: pubKey } = await client.POST(\"/public_keys\", {\n body: {\n value: \"xpub6BosfCnifzxRT1QKLpFfcUrgWmLqoJcGt...\",\n label: \"Exchange Hot Wallet\",\n derivation_path: \"m/44'/60'/0'\",\n },\n});\n\n// Generate the next address in sequence\nconst { data: nextAddr } = await client.POST(\n \"/public_keys/{public_key_id}/addresses/next\",\n { params: { path: { public_key_id: pubKey!.item.id } } }\n);\n\nconsole.log(\"New address:\", nextAddr?.item.value);\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"design-considerations-2","__idx":15},"children":["Design considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Vilna supports BIP-32, BIP-44, BIP-49, BIP-84, and BIP-86 derivation paths."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can import xPub, yPub, or zPub keys depending on the address format you need (legacy, SegWit, native SegWit, Taproot)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The public key never leaves Vilna unencrypted - private keys are never required."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-multi-chain-monitoring","__idx":16},"children":["4. Multi-chain monitoring"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Goal:"]}," Track addresses across several blockchains and filter activity by chain."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When to use:"]}," Multi-chain wallets, cross-chain analytics dashboards, and compliance monitoring tools."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works-3","__idx":17},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check which blockchains are available (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/blockchain/list-blockchains"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /blockchains"]}]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Register addresses with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chainFamily"]}," to monitor them on all chains in that family."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Query ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/activity/list-activity"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /activity"]}]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/transaction/list-transactions"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /transactions"]}]}," and filter by chain as needed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references.blockchains"]}," to display chain metadata."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sequence-3","__idx":18},"children":["Sequence"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant A as Your App\n participant V as Vilna\n\n A->>V: GET /blockchains\n V-->>A: Chain list\n A->>V: POST /addresses/external (chainFamily: \"evm\")\n V-->>A: Address created\n A->>V: GET /activity\n V-->>A: Activity feed (includes chain info)\n A->>A: Filter by chain\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant A as Your App\n participant V as Vilna\n\n A->>V: GET /blockchains\n V-->>A: Chain list\n A->>V: POST /addresses/external (chainFamily: \"evm\")\n V-->>A: Address created\n A->>V: GET /activity\n V-->>A: Activity feed (includes chain info)\n A->>A: Filter by chain\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-code-3","__idx":19},"children":["Key code"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# List supported chains\ncurl \"https://api.vilna.io/v1/blockchains\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\"\n\n# Monitor an address on all EVM chains (Ethereum, Polygon, Arbitrum, etc.)\ncurl -X POST \"https://api.vilna.io/v1/addresses/external\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"value\": \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n \"chainFamily\": \"evm\",\n \"label\": \"Multi-chain Wallet\"\n }'\n\n# Get activity across all chains\ncurl \"https://api.vilna.io/v1/activity?limit=30&page=1\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// List available chains\nconst { data: chains } = await client.GET(\"/blockchains\");\nconsole.log(\"Active chains:\", chains?.items.map((c) => c.gid));\n\n// Register an address on all EVM chains\nawait client.POST(\"/addresses/external\", {\n body: {\n value: \"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\",\n chainFamily: \"evm\",\n label: \"Multi-chain Wallet\",\n },\n});\n\n// Fetch activity and group by chain\nconst { data: activity } = await client.GET(\"/activity\", {\n params: { query: { limit: 30, page: 1 } },\n});\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"design-considerations-3","__idx":20},"children":["Design considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["EVM addresses (0x-prefixed) can be monitored on all EVM-compatible chains with a single ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/create-external-address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /addresses/external"]}]}," call by specifying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chainFamily: \"evm\""]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Non-EVM chains (Bitcoin, Solana, Tron) require chain-specific address formats."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each chain is indexed independently, so a single address may have different balances and transaction histories on different chains."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"5-transaction-alerts","__idx":21},"children":["5. Transaction alerts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Goal:"]}," Receive real-time notifications through multiple channels whenever blockchain activity occurs on monitored addresses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["When to use:"]}," Treasury monitoring, compliance alerts, operational dashboards, and on-call systems."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works-4","__idx":22},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add the addresses you want to watch (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/address/create-external-address"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /addresses/external"]}]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a webhook channel for your backend (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/channel/create-channel"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /channels"]}]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind: \"webhook\""]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optionally create a Telegram channel for human operators (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/channel/create-channel"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /channels"]}]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind: \"telegram\""]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test both channels (",{"$$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":"li","attributes":{},"children":["All events on monitored addresses are delivered to every active channel."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sequence-4","__idx":23},"children":["Sequence"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant BC as Blockchain\n participant V as Vilna\n participant S as Your Server\n participant TG as Telegram\n\n BC->>V: New transaction\n V->>S: Webhook POST\n V->>TG: Telegram message\n Note over S,TG: Both channels receive the same event\n","diagramHtml":"","diagramHtmlDark":""},"children":["sequenceDiagram\n participant BC as Blockchain\n participant V as Vilna\n participant S as Your Server\n participant TG as Telegram\n\n BC->>V: New transaction\n V->>S: Webhook POST\n V->>TG: Telegram message\n Note over S,TG: Both channels receive the same event\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-code-4","__idx":24},"children":["Key code"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"curl","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Create a webhook channel\ncurl -X POST \"https://api.vilna.io/v1/channels\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Backend Alerts\",\n \"config\": {\n \"kind\": \"webhook\",\n \"url\": \"https://your-app.example.com/alerts/webhook\",\n \"headers\": {}\n }\n }'\n\n# Create a Telegram channel\ncurl -X POST \"https://api.vilna.io/v1/channels\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Ops Team Telegram\",\n \"config\": {\n \"kind\": \"telegram\",\n \"bot_token\": \"987654321:ABCdefGHIjklMNOpqrsTUVwxyz123456789\",\n \"chat_id\": -1001234567890,\n \"language\": \"en\",\n \"thread_id\": 0\n }\n }'\n\n# Test the webhook channel\ncurl -X POST \"https://api.vilna.io/v1/channels/{channel_id}/actions/test\" \\\n -H \"X-Api-Key: ${VILNA_API_KEY}\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"// Create a webhook channel\nconst { data: webhook } = await client.POST(\"/channels\", {\n body: {\n name: \"Backend Alerts\",\n config: {\n kind: \"webhook\",\n url: \"https://your-app.example.com/alerts/webhook\",\n headers: {},\n },\n },\n});\n\n// Create a Telegram channel\nconst { data: telegram } = await client.POST(\"/channels\", {\n body: {\n name: \"Ops Team Telegram\",\n config: {\n kind: \"telegram\",\n bot_token: \"987654321:ABCdefGHIjklMNOpqrsTUVwxyz123456789\",\n chat_id: -1001234567890,\n language: \"en\",\n thread_id: 0,\n },\n },\n});\n\n// Test both channels\nawait client.POST(\"/channels/{channel_id}/actions/test\", {\n params: { path: { channel_id: webhook!.item.id } },\n});\nawait client.POST(\"/channels/{channel_id}/actions/test\", {\n params: { path: { channel_id: telegram!.item.id } },\n});\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"design-considerations-4","__idx":25},"children":["Design considerations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All active channels receive all events. Use server-side filtering in your webhook handler to route or suppress events as needed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhook channels include HMAC-SHA256 signatures so your backend can verify each delivery. Telegram channels have no equivalent — Telegram is the endpoint, so trust is anchored in who has access to the chat and the bot."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For high-value accounts, use both channels so that human operators get Telegram alerts while your backend processes events automatically."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":26},"children":["Further reading"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Quickstart","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/quickstart"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set up your first integration end-to-end"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Core Concepts","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/core-concepts"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Addresses, tokens, amounts, and the references pattern"]}]},{"$$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 key usage and webhook signature verification"]}]},{"$$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 with request/response schemas"]}]}]}]},"headings":[{"value":"Integration patterns","id":"integration-patterns","depth":1},{"value":"1. Blockchain deposit detection","id":"1-blockchain-deposit-detection","depth":2},{"value":"How it works","id":"how-it-works","depth":3},{"value":"Sequence","id":"sequence","depth":3},{"value":"Key code","id":"key-code","depth":3},{"value":"Design considerations","id":"design-considerations","depth":3},{"value":"2. Portfolio tracker","id":"2-portfolio-tracker","depth":2},{"value":"How it works","id":"how-it-works-1","depth":3},{"value":"Sequence","id":"sequence-1","depth":3},{"value":"Key code","id":"key-code-1","depth":3},{"value":"Design considerations","id":"design-considerations-1","depth":3},{"value":"3. HD wallet management","id":"3-hd-wallet-management","depth":2},{"value":"How it works","id":"how-it-works-2","depth":3},{"value":"Sequence","id":"sequence-2","depth":3},{"value":"Key code","id":"key-code-2","depth":3},{"value":"Design considerations","id":"design-considerations-2","depth":3},{"value":"4. Multi-chain monitoring","id":"4-multi-chain-monitoring","depth":2},{"value":"How it works","id":"how-it-works-3","depth":3},{"value":"Sequence","id":"sequence-3","depth":3},{"value":"Key code","id":"key-code-3","depth":3},{"value":"Design considerations","id":"design-considerations-3","depth":3},{"value":"5. Transaction alerts","id":"5-transaction-alerts","depth":2},{"value":"How it works","id":"how-it-works-4","depth":3},{"value":"Sequence","id":"sequence-4","depth":3},{"value":"Key code","id":"key-code-4","depth":3},{"value":"Design considerations","id":"design-considerations-4","depth":3},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"Integration Patterns - Common API Use Cases","description":"Five common integration scenarios with step-by-step API call sequences for typical Vilna use cases like deposit monitoring and balance tracking.","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":"Integration Patterns"}]},{"@type":"TechArticle","headline":"Integration Patterns - Common API Use Cases","description":"Five common integration scenarios with step-by-step API call sequences for typical Vilna use cases like deposit monitoring and balance tracking.","url":"https://docs.vilna.io/guides/integration-patterns","datePublished":"2025-09-17","dateModified":"2026-05-26","proficiencyLevel":"Intermediate","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/integration-patterns","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}