{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","cards","card"]},"type":"markdown"},"seo":{"title":"Events - Real-Time Transaction Monitoring","projectTitle":"Vilna Docs","description":"Understand Vilna's event model that breaks blockchain transactions into granular canonical events for detailed monitoring and alerting.","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":"Events"}]},{"@type":"TechArticle","headline":"Events - Real-Time Transaction Monitoring","description":"Understand Vilna's event model that breaks blockchain transactions into granular canonical events for detailed monitoring and alerting.","url":"https://docs.vilna.io/guides/events","datePublished":"2025-09-17","dateModified":"2026-05-17","proficiencyLevel":"Intermediate","dependencies":"Vilna API key, Webhook endpoint","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":"events--transaction-monitoring","__idx":0},"children":["Events & transaction monitoring"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a transaction occurs on a blockchain, it is rarely a single action. An EVM transaction might transfer ETH, pay a gas fee, trigger a token approval, and call a smart contract - all in one atomic operation. If your system only tracks \"money moved from A to B,\" you are missing most of what happened."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna breaks every transaction into individual ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["canonical events"]}," - one event per meaningful action. This page explains the event model, what each event type means, how notifications work, and how to build on top of them. For real-world examples of event monitoring in action, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/business/use-cases"},"children":["use cases"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-are-events","__idx":1},"children":["What are events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A blockchain transaction is a container. Inside it, multiple things happen: value moves, fees are paid, permissions are granted, contracts are called. Vilna parses each transaction and extracts every discrete action into a separate event object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each event has:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}]}," - the type of action (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utxo_transfer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approval"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract_create"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence"]}]}," - a 0-based position within the transaction, so you know the order of operations"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]}," - a payload specific to the event kind, containing addresses, amounts, and asset identifiers"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A simple ETH transfer produces two events: a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]},". A DeFi swap might produce five or more: a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}," to the router contract, multiple ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," events as tokens move through liquidity pools, and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}," event for gas."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This granularity means your system can react to exactly what happened, not just approximate it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-types","__idx":2},"children":["Event types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna normalizes all on-chain activity into canonical event types. Regardless of which blockchain a transaction occurs on, the events always follow the same structure."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n TX[Transaction] --> T[\"transfer
assets moved\"]\n TX --> UT[\"utxo_transfer
UTXO inputs/outputs\"]\n TX --> F[\"fee
gas paid\"]\n TX --> A[\"approval
spend permission\"]\n TX --> C[\"call
contract invoked\"]\n TX --> CC[\"contract_create
new contract\"]\n","diagramHtml":"

Transaction

transfer
assets moved

utxo_transfer
UTXO inputs/outputs

fee
gas paid

approval
spend permission

call
contract invoked

contract_create
new contract

","diagramHtmlDark":"

Transaction

transfer
assets moved

utxo_transfer
UTXO inputs/outputs

fee
gas paid

approval
spend permission

call
contract invoked

contract_create
new contract

"},"children":["flowchart LR\n TX[Transaction] --> T[\"transfer
assets moved\"]\n TX --> UT[\"utxo_transfer
UTXO inputs/outputs\"]\n TX --> F[\"fee
gas paid\"]\n TX --> A[\"approval
spend permission\"]\n TX --> C[\"call
contract invoked\"]\n TX --> CC[\"contract_create
new contract\"]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transfer","__idx":3},"children":["transfer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Assets moved from one address to another."]},{"$$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":["asset_gid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CAIP-19 identifier of the transferred asset"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sender address"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Recipient address"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer amount (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Origin of the transfer: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["native"]}," (chain-level), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract"]}," (token contract), or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal"]}," (internal transaction)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token identifier for NFTs (ERC-721/ERC-1155), if applicable"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example scenario:"]}," A user sends 1,000 USDT to a merchant wallet. Vilna emits a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," event with the sender, recipient, token, and exact amount. Your deposit detection system matches the recipient to a customer and credits their account."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"kind\": \"transfer\",\n \"asset_gid\": \"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n \"from\": \"0x742d35cc6634c0532925a3b844Bc9e7595f7B123\",\n \"to\": \"0x8ba1f109551bd432803012645ac136c0d1e5c400\",\n \"amount\": { \"base\": \"1000000000\", \"formatted\": \"1000.0\" },\n \"source\": \"contract\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"utxo_transfer","__idx":4},"children":["utxo_transfer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A UTXO-based transfer with full input/output visibility. Used for Bitcoin and other UTXO chains instead of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]},", providing complete details of all funding sources and all destinations in a single event."]},{"$$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":["asset_gid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CAIP-19 identifier of the transferred asset"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inputs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of transaction inputs, each with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]},"), and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outputs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of transaction outputs, each with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]},"), and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index"]}]}]},{"$$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":["Transaction fee (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example scenario:"]}," A user consolidates two UTXOs into a single payment. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utxo_transfer"]}," event shows both input addresses (funding sources), the recipient output, the change output, and the miner fee - all in one event."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"kind\": \"utxo_transfer\",\n \"asset_gid\": \"bip122:000000000019d6689c085ae165831e93/slip44:0\",\n \"inputs\": [\n { \"address\": \"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq\", \"amount\": { \"base\": \"50000\", \"formatted\": \"0.0005\" }, \"index\": 0 },\n { \"address\": \"bc1q5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8\", \"amount\": { \"base\": \"30000\", \"formatted\": \"0.0003\" }, \"index\": 1 }\n ],\n \"outputs\": [\n { \"address\": \"bc1p5d7rjq7g6rdk2yhzks9smlaqtedr4dekq08ge8ztwac72sfr9rusxg3s7p\", \"amount\": { \"base\": \"70000\", \"formatted\": \"0.0007\" }, \"index\": 0 },\n { \"address\": \"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq\", \"amount\": { \"base\": \"8000\", \"formatted\": \"0.00008\" }, \"index\": 1 }\n ],\n \"fee\": { \"base\": \"2000\", \"formatted\": \"0.00002\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This structure is important for compliance workflows - AML screening requires checking all input addresses (funding sources), not just a single sender."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"fee","__idx":5},"children":["fee"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A network fee was paid to process the transaction."]},{"$$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":["asset_gid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CAIP-19 identifier of the fee asset (always the chain's native currency)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address that paid the fee"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fee amount (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example scenario:"]}," Every Ethereum transaction costs gas. Your accounting system needs to track fee expenditure separately from transfers to calculate true cost per transaction. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}," event gives you the exact amount paid, without manual calculation."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"kind\": \"fee\",\n \"asset_gid\": \"eip155:1/slip44:60\",\n \"payer\": \"0x742d35cc6634c0532925a3b844Bc9e7595f7B123\",\n \"amount\": { \"base\": \"2100000000000000\", \"formatted\": \"0.0021\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"approval","__idx":6},"children":["approval"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A token spending permission was granted or changed."]},{"$$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":["asset_gid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CAIP-19 identifier of the approved token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owner"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address granting the permission"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spender"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address receiving the permission to spend"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Approved spending limit (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["base"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["formatted"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token identifier for NFT approvals (ERC-721/ERC-1155), if applicable"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example scenario:"]}," A user approves a DEX router to spend their USDT. For a custodial platform, this is a security-critical event - someone just authorized a third party to move tokens from a monitored address. Your compliance system should flag and review unlimited approvals."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"kind\": \"approval\",\n \"asset_gid\": \"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n \"owner\": \"0x742d35cc6634c0532925a3b844Bc9e7595f7B123\",\n \"spender\": \"0x1f9840a85d5af5bf1d1762f925bdaddc4201f984\",\n \"amount\": { \"base\": \"115792089237316195423570985008687907853269984665640564039457584007913129639935\", \"formatted\": \"unlimited\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"call","__idx":7},"children":["call"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A smart contract function was executed."]},{"$$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":["caller"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address that initiated the call"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contract address that was called"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example scenario:"]}," A monitored address interacts with an unknown smart contract. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}," event tells your risk system that a contract interaction occurred, even if no tokens moved directly. This is important for detecting phishing contracts, tracking DeFi positions, and maintaining complete audit trails."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"kind\": \"call\",\n \"caller\": \"0x742d35cc6634c0532925a3b844Bc9e7595f7B123\",\n \"target\": \"0x1f9840a85d5af5bf1d1762f925bdaddc4201f984\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"contract_create","__idx":8},"children":["contract_create"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A new smart contract was deployed."]},{"$$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":["creator"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address that deployed the contract"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_address"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address of the newly deployed contract"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example scenario:"]}," One of your monitored addresses deploys a new smart contract. For compliance teams, contract deployment is a significant action that should be logged and reviewed. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract_create"]}," event captures exactly who deployed what and where."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"kind\": \"contract_create\",\n \"creator\": \"0x742d35cc6634c0532925a3b844Bc9e7595f7B123\",\n \"created_address\": \"0x1f9840a85d5af5bf1d1762f925bdaddc4201f984\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-track-crypto-transactions-beyond-transfers","__idx":9},"children":["Why track crypto transactions beyond transfers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Many blockchain monitoring solutions only track token transfers. Vilna tracks all canonical event types because real-world use cases demand it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"security","__idx":10},"children":["Security"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approval"]}," event means someone authorized a third party to spend tokens from a monitored address. For a crypto bank, exchange, or custodial wallet, this is a security-critical event. If an attacker gains access to one of your addresses and grants themselves an unlimited token approval, a transfer-only system would not notice until the tokens are actually moved - by which time it is too late. Monitoring approvals gives you an early warning window."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"compliance","__idx":11},"children":["Compliance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Regulators expect complete audit trails. A transfer-only log misses contract interactions that move value in indirect ways - liquidity pool deposits, staking operations, and DAO governance calls all affect your exposure without producing a simple \"A sent X to B\" event. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract_create"]}," events fill these gaps."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"defi-visibility","__idx":12},"children":["DeFi visibility"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In DeFi, value moves through smart contract calls, not just simple transfers. A user might call a swap router that then triggers three internal transfers across two liquidity pools. Without the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}," event, you see tokens appearing and disappearing with no explanation. With it, you have the full context: which contract was called, which address initiated it, and what transfers resulted."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"multi-chain-consistency","__idx":13},"children":["Multi-chain consistency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Different blockchains represent the same actions differently. Ethereum uses ERC-20 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Transfer"]}," events; Tron uses TRC-20 events; Bitcoin uses UTXO inputs and outputs. Vilna normalizes everything into the same canonical event types. Your code handles an Ethereum transfer and a Bitcoin transfer with the same approach - consistent field naming and predictable structure across chains."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"complete-picture","__idx":14},"children":["Complete picture"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single transaction can contain many events. Consider a user swapping tokens on a DEX:"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant U as User\n participant R as DEX Router\n participant LP as Liquidity Pool\n participant BC as Blockchain\n\n U->>R: 1. call (swap)\n R->>LP: 2. transfer (input tokens)\n LP->>U: 3. transfer (output tokens)\n U->>BC: 4. fee (gas)\n Note over U,BC: 1 transaction → 4 events\n","diagramHtml":"BlockchainLiquidity PoolDEX RouterUserBlockchainLiquidity PoolDEX RouterUser1 transaction → 4 events1. call (swap)2. transfer (input tokens)3. transfer (output tokens)4. fee (gas)","diagramHtmlDark":"BlockchainLiquidity PoolDEX RouterUserBlockchainLiquidity PoolDEX RouterUser1 transaction → 4 events1. call (swap)2. transfer (input tokens)3. transfer (output tokens)4. fee (gas)"},"children":["sequenceDiagram\n participant U as User\n participant R as DEX Router\n participant LP as Liquidity Pool\n participant BC as Blockchain\n\n U->>R: 1. call (swap)\n R->>LP: 2. transfer (input tokens)\n LP->>U: 3. transfer (output tokens)\n U->>BC: 4. fee (gas)\n Note over U,BC: 1 transaction → 4 events\n"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}," - the user calls the swap router contract"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," - the user's input tokens move to the liquidity pool"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," - the output tokens move from the pool to the user"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}," - the gas fee is paid"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you only tracked transfers, you would see tokens coming and going but miss the contract interaction that caused them. You would also miss the fee, making it impossible to calculate the true cost of the operation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-is-tracked-per-chain-family","__idx":15},"children":["What is tracked per chain family"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Different blockchains have different capabilities. Here is what Vilna tracks for each chain family:"]},{"$$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":"Capability"},"children":["Capability"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"EVM"},"children":["EVM"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Bitcoin"},"children":["Bitcoin"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"TRON"},"children":["TRON"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Solana"},"children":["Solana"]}]}]},{"$$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":["Native + ERC-20 tokens"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["N/A"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Native + TRC-20 tokens"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Native + SPL tokens"]}]},{"$$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":["N/A"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["BTC (full UTXO inputs/outputs)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["N/A"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["N/A"]}]},{"$$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 fees"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Miner fees"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bandwidth/energy fees"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction fees"]}]},{"$$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 approvals"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["N/A"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["TRC-20 approvals"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["N/A"]}]},{"$$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 calls"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["N/A"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Smart contract calls"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Program interactions"]}]},{"$$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":["Contract deployment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["N/A"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contract deployment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Program deployment"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["EVM chains"]}," (Ethereum, Polygon, Arbitrum, BSC, etc.) support ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approval"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract_create"]},", including internal transactions and ERC-721/ERC-1155 NFT events."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bitcoin"]}," supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utxo_transfer"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}," events. Bitcoin does not have smart contracts in the EVM sense, so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approval"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract_create"]}," do not apply. Bitcoin uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utxo_transfer"]}," instead of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," to provide full visibility into all inputs (funding sources) and outputs (destinations) - this is essential for AML compliance and accurate accounting."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TRON"]}," is similar to EVM - it supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approval"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contract_create"]}," for TRC-20 tokens and smart contract interactions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solana"]}," supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}," events, with program-level interaction tracking for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["call"]}," events."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The complete and current list of supported chains and their capabilities is available via ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/blockchain/list-blockchains"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /blockchains"]}]}," in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/"},"children":["Platform API"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notification-lifecycle","__idx":16},"children":["Notification lifecycle"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a transaction touches one of your monitored addresses, Vilna sends notifications at specific lifecycle stages. Understanding this lifecycle is essential for building reliable systems."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-flow","__idx":17},"children":["The flow"]},{"$$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 System\n\n BC->>V: New block\n V->>V: Parse transactions\n V->>V: Extract canonical events\n V->>V: Match monitored addresses\n V->>S: transaction_detected (fast, not final)\n loop Confirmations\n BC->>V: Block +1, +2, ... +N\n V->>V: Count confirmations\n end\n V->>S: transaction_confirmed (reliable)\n","diagramHtml":"Your SystemVilnaBlockchainYour SystemVilnaBlockchainloop[Confirmations]New blockParse transactionsExtract canonical eventsMatch monitored addressestransaction_detected (fast, not final)Block +1, +2, ... +NCount confirmationstransaction_confirmed (reliable)","diagramHtmlDark":"Your SystemVilnaBlockchainYour SystemVilnaBlockchainloop[Confirmations]New blockParse transactionsExtract canonical eventsMatch monitored addressestransaction_detected (fast, not final)Block +1, +2, ... +NCount confirmationstransaction_confirmed (reliable)"},"children":["sequenceDiagram\n participant BC as Blockchain\n participant V as Vilna\n participant S as Your System\n\n BC->>V: New block\n V->>V: Parse transactions\n V->>V: Extract canonical events\n V->>V: Match monitored addresses\n V->>S: transaction_detected (fast, not final)\n loop Confirmations\n BC->>V: Block +1, +2, ... +N\n V->>V: Count confirmations\n end\n V->>S: transaction_confirmed (reliable)\n"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A transaction is included in a block on the blockchain."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Vilna detects the block, parses every transaction, and extracts canonical events."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Vilna checks if any monitored addresses are involved in the transaction's events or activity."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If a match is found, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_detected"]}," notification is sent via all configured channels (webhook and Telegram). The transaction's block status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processed"]}," (detected but not yet confirmed)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["As new blocks are added on top, the transaction accumulates confirmations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When the required confirmation count is reached, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_confirmed"]}," notification is sent. The block status is now ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If a blockchain reorganization occurs (rare, but possible), the block status transitions to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reorged"]},". The block is reprocessed from the new chain state."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"detection-vs-confirmation","__idx":18},"children":["Detection vs. confirmation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notifications are sent at ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["two key moments"]},", and your system should handle them differently:"]},{"$$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 type"},"children":["Event type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Block status"},"children":["Block status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Speed"},"children":["Speed"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Finality"},"children":["Finality"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use for"},"children":["Use for"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_detected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fast (seconds after block)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not final - could be reorged"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UI updates, provisional display, alerting humans"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_confirmed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slower (minutes, depends on chain)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Final - safe to act on"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Crediting accounts, triggering business logic, updating balances"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Design your system around this distinction."]}," Show detected transactions in your UI immediately so users see responsive feedback. But do not credit accounts, trigger payouts, or update ledgers until you receive the confirmation notification. This two-phase approach gives you both speed and safety."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not act on detected events"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Show detected alerts (block status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processed"]},") in your UI for responsiveness, but ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["never"]}," credit accounts, trigger payouts, or update ledgers until you receive a confirmed alert (block status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-notifications-in-practice","__idx":19},"children":["Webhook notifications in practice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a notification fires, your webhook receives a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransactionAlertPayload"]}," - a self-contained JSON object with everything you need to process the event without making additional API calls."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payload-structure","__idx":20},"children":["Payload structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The payload has four top-level fields:"]},{"$$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":["event_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUIDv5 matching the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Id"]}," header. Stable across retries — use it as your deduplication key."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The full transaction object, including all events and activity records"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lookup maps for tokens, blockchains, and addresses referenced in the transaction"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_test_message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," if sent by the test action, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," for real blockchain events"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-payload","__idx":21},"children":["Example payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is a realistic webhook payload for a 1,000 USDT transfer on Ethereum. The transaction contains two events (the token transfer and the gas fee) and one activity record showing the net impact on the monitored address:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"event_id\": \"f47ac10b-58cc-5372-a567-0e02b2c3d479\",\n \"item\": {\n \"chain_gid\": \"eip155:1\",\n \"txid\": \"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\",\n \"block_number\": 19500000,\n \"is_success\": true,\n \"confirmed_at\": \"2025-03-15T10:30:00Z\",\n \"events\": [\n {\n \"txid\": \"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\",\n \"sequence\": 0,\n \"kind\": \"transfer\",\n \"data\": {\n \"kind\": \"transfer\",\n \"asset_gid\": \"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n \"from\": \"0x742d35cc6634c0532925a3b844Bc9e7595f7B123\",\n \"to\": \"0x8ba1f109551bd432803012645ac136c0d1e5c400\",\n \"amount\": { \"base\": \"1000000000\", \"formatted\": \"1000.0\" },\n \"source\": \"contract\"\n }\n },\n {\n \"txid\": \"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\",\n \"sequence\": 1,\n \"kind\": \"fee\",\n \"data\": {\n \"kind\": \"fee\",\n \"asset_gid\": \"eip155:1/slip44:60\",\n \"payer\": \"0x742d35cc6634c0532925a3b844Bc9e7595f7B123\",\n \"amount\": { \"base\": \"2100000000000000\", \"formatted\": \"0.0021\" }\n }\n }\n ],\n \"activity\": [\n {\n \"chain_gid\": \"eip155:1\",\n \"txid\": \"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\",\n \"address\": \"0x8ba1f109551bd432803012645ac136c0d1e5c400\",\n \"asset_gid\": \"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n \"direction\": \"in\",\n \"delta\": { \"base\": \"1000000000\", \"formatted\": \"1000.0\" },\n \"created_at\": \"2025-03-15T10:30:00Z\"\n }\n ]\n },\n \"references\": {\n \"tokens\": {\n \"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7\": {\n \"gid\": \"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n \"name\": \"Tether USD\",\n \"symbol\": \"USDT\",\n \"decimals\": 6\n },\n \"eip155:1/slip44:60\": {\n \"gid\": \"eip155:1/slip44:60\",\n \"name\": \"Ethereum\",\n \"symbol\": \"ETH\",\n \"decimals\": 18\n }\n },\n \"blockchains\": {\n \"eip155:1\": {\n \"gid\": \"eip155:1\",\n \"name\": \"ethereum\",\n \"short_name\": \"eth\"\n }\n },\n \"addresses\": {\n \"0x8ba1f109551bd432803012645ac136c0d1e5c400\": \"merchant_wallet\"\n }\n },\n \"is_test_message\": false\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key things to notice:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["events"]}," array contains every canonical event in the transaction. You can filter by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}," to process only the event types you care about."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activity"]}," array shows the net balance impact on your monitored addresses. Each entry tells you which address was affected, which asset changed, the direction (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["out"]},"), and the exact delta."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," object lets you resolve token symbols, names, decimals, and blockchain metadata without calling the API. Everything you need for display and processing is in the payload."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"routing-notifications-beyond-webhooks","__idx":22},"children":["Routing notifications beyond webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Vilna delivers notifications natively to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["webhooks"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Telegram"]},". But a webhook is just an HTTP POST - you can route that data anywhere your architecture needs it."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Message queues"]}," - Point your webhook URL at a lightweight proxy that enqueues messages into RabbitMQ, AWS SQS, or Google Pub/Sub. This decouples event ingestion from processing and gives you backpressure handling for free."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Slack / Discord"]}," - Your webhook handler can reformat the payload and forward it to Slack or Discord incoming webhook URLs. This is useful for operations teams who want human-readable transaction alerts in their chat channels."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PagerDuty / OpsGenie"]}," - Forward high-value events (large transfers, unexpected approvals, contract deployments) to alerting systems for on-call escalation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Custom backends"]}," - Any system that accepts HTTP POST can receive Vilna events. Point the webhook at your internal API, a serverless function, or a data pipeline ingestion endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Native adapters for Slack, Discord, and popular message queues are in development. If you need a specific integration, contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:support@vilna.io"},"children":["support@vilna.io"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-delivery-and-retries","__idx":23},"children":["Webhook delivery and retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When Vilna sends a webhook notification, it expects your endpoint to return a 2xx status code within ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["10 seconds"]},". A delivery is considered failed if the connection cannot be established, the response times out, or the endpoint returns a 4xx/5xx status code."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Failed deliveries are retried on the following schedule:"]},{"$$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":"Attempt"},"children":["Attempt"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Delay"},"children":["Delay"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Immediate"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["30 seconds"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2 minutes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10 minutes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["30 minutes"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If all five attempts fail, the event is marked as undelivered. A single undelivered event does not disable the channel - transient failures are expected. However, if an endpoint fails repeatedly across multiple events, Vilna disables the channel to stop wasting resources. A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["410 Gone"]}," response immediately disables the channel on the first attempt."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Delivery ordering:"]}," Notifications are dispatched in the order events occur, but delivery is not strictly ordered. If your endpoint is slow to respond, a later event may arrive before an earlier retry completes. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block_number"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sequence"]}," from the payload to reconstruct the correct order on your side."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"designing-your-webhook-handler","__idx":24},"children":["Designing your webhook handler"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A well-built webhook handler is reliable, idempotent, and fast. Follow these practices to avoid common pitfalls."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"respond-immediately-process-later","__idx":25},"children":["Respond immediately, process later"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your webhook endpoint should return HTTP 2xx as fast as possible. Enqueue the payload for asynchronous processing rather than doing heavy work in the request handler."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Best practice"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return HTTP 200 immediately and enqueue the payload for async processing. Heavy work in the request handler risks timeouts and missed deliveries."]}]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"flowchart LR\n V[Vilna] -->|POST| E[Your Endpoint]\n E -->|200 OK| V\n E --> Q[Queue]\n Q --> W[Async Worker]\n W --> BL[Business Logic]\n","diagramHtml":"

POST

200 OK

Vilna

Your Endpoint

Queue

Async Worker

Business Logic

","diagramHtmlDark":"

POST

200 OK

Vilna

Your Endpoint

Queue

Async Worker

Business Logic

"},"children":["flowchart LR\n V[Vilna] -->|POST| E[Your Endpoint]\n E -->|200 OK| V\n E --> Q[Queue]\n Q --> W[Async Worker]\n W --> BL[Business Logic]\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verify-the-signature","__idx":26},"children":["Verify the signature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every delivery carries an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Signature"]}," header in Stripe format (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t=,v1="]},") with an HMAC-SHA256 of the raw request body. Verify it before processing — both to confirm the payload came from Vilna and to reject replays via the timestamp inside the header. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication#webhook-signature-verification"},"children":["Authentication — Webhook signature verification"]}," for the verification function and required client behaviors."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"deduplicate-by-event_id","__idx":27},"children":["Deduplicate by event_id"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_id"]}," from the body (or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Id"]}," from the headers — they are the same value) to detect duplicate deliveries. Store processed IDs in a database or cache and skip any you have already seen. This is critical for financial operations — you never want to credit an account twice for the same transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"filter-by-event-kind","__idx":28},"children":["Filter by event kind"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your system only cares about transfers, filter the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["events"]}," array by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kind"]}," and ignore the rest. For EVM/TRON/Solana chains, look for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer"]},"; for Bitcoin, look for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["utxo_transfer"]},". This keeps your processing logic focused:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const transfers = payload.item.events.filter(\n (event) => event.kind === \"transfer\" || event.kind === \"utxo_transfer\"\n);\n\nfor (const event of transfers) {\n if (event.kind === \"utxo_transfer\") {\n // Bitcoin: full UTXO inputs/outputs\n await processUtxoTransfer(event.data);\n } else {\n // EVM/TRON/Solana: single from→to transfer\n await processTransfer(event.data);\n }\n}\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-the-references-object","__idx":29},"children":["Use the references object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," field contains token metadata (name, symbol, decimals) and blockchain information for every asset and chain mentioned in the transaction. Use this data directly instead of making extra API calls:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"typescript","header":{"controls":{"copy":{}}},"source":"const tokenGid = event.data.asset_gid;\nconst token = payload.references.tokens[tokenGid];\nconsole.log(`Received ${event.data.amount.formatted} ${token.symbol}`);\n","lang":"typescript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"summary-of-webhook-headers","__idx":30},"children":["Summary of webhook headers"]},{"$$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":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stripe-format HMAC-SHA256 signature: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t=,v1="]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Event name in dot notation: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.detected"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction.confirmed"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Event-Id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUIDv5, stable across retries — use as dedup key"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Webhook-Delivery-Id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID, changes on every attempt — for support correlation only"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":31},"children":["Further reading"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Notification Channels","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/channels"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating and managing webhook and Telegram channels"]}]},{"$$mdtype":"Tag","name":"Card","attributes":{"title":"Authentication","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/authentication#webhook-signature-verification"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook signature verification with code examples"]}]},{"$$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":"Integration Patterns","imagePosition":"start","iconPosition":"auto","layout":"vertical","align":"start","variant":"filled","to":"/guides/integration-patterns"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deposit detection, portfolio tracking, and transaction alerts"]}]}]}]},"headings":[{"value":"Events & transaction monitoring","id":"events--transaction-monitoring","depth":1},{"value":"What are events","id":"what-are-events","depth":2},{"value":"Event types","id":"event-types","depth":2},{"value":"transfer","id":"transfer","depth":3},{"value":"utxo_transfer","id":"utxo_transfer","depth":3},{"value":"fee","id":"fee","depth":3},{"value":"approval","id":"approval","depth":3},{"value":"call","id":"call","depth":3},{"value":"contract_create","id":"contract_create","depth":3},{"value":"Why track crypto transactions beyond transfers","id":"why-track-crypto-transactions-beyond-transfers","depth":2},{"value":"Security","id":"security","depth":3},{"value":"Compliance","id":"compliance","depth":3},{"value":"DeFi visibility","id":"defi-visibility","depth":3},{"value":"Multi-chain consistency","id":"multi-chain-consistency","depth":3},{"value":"Complete picture","id":"complete-picture","depth":3},{"value":"What is tracked per chain family","id":"what-is-tracked-per-chain-family","depth":2},{"value":"Notification lifecycle","id":"notification-lifecycle","depth":2},{"value":"The flow","id":"the-flow","depth":3},{"value":"Detection vs. confirmation","id":"detection-vs-confirmation","depth":3},{"value":"Webhook notifications in practice","id":"webhook-notifications-in-practice","depth":2},{"value":"Payload structure","id":"payload-structure","depth":3},{"value":"Example payload","id":"example-payload","depth":3},{"value":"Routing notifications beyond webhooks","id":"routing-notifications-beyond-webhooks","depth":2},{"value":"Webhook delivery and retries","id":"webhook-delivery-and-retries","depth":2},{"value":"Designing your webhook handler","id":"designing-your-webhook-handler","depth":2},{"value":"Respond immediately, process later","id":"respond-immediately-process-later","depth":3},{"value":"Verify the signature","id":"verify-the-signature","depth":3},{"value":"Deduplicate by event_id","id":"deduplicate-by-event_id","depth":3},{"value":"Filter by event kind","id":"filter-by-event-kind","depth":3},{"value":"Use the references object","id":"use-the-references-object","depth":3},{"value":"Summary of webhook headers","id":"summary-of-webhook-headers","depth":3},{"value":"Further reading","id":"further-reading","depth":2}],"frontmatter":{"seo":{"title":"Events - Real-Time Transaction Monitoring","description":"Understand Vilna's event model that breaks blockchain transactions into granular canonical events for detailed monitoring and alerting.","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":"Events"}]},{"@type":"TechArticle","headline":"Events - Real-Time Transaction Monitoring","description":"Understand Vilna's event model that breaks blockchain transactions into granular canonical events for detailed monitoring and alerting.","url":"https://docs.vilna.io/guides/events","datePublished":"2025-09-17","dateModified":"2026-05-17","proficiencyLevel":"Intermediate","dependencies":"Vilna API key, Webhook endpoint","image":"https://cdn.vilna.io/docs/previews/guides.png","author":{"@id":"https://vilna.io/#organization"},"publisher":{"@id":"https://vilna.io/#organization"}}]}}},"lastModified":"2026-05-17T22:07:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/events","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}