{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","cards","card"]},"type":"markdown"},"seo":{"title":"Transaction Simulation - EVM Preview","projectTitle":"Vilna Docs","description":"Simulate EVM transactions before broadcasting. Preview balance changes, gas fees, token transfers, and detect reverts using the Vilna API.","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.5,"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://docs.vilna.io/"},{"@type":"ListItem","position":2,"name":"Guides"},{"@type":"ListItem","position":3,"name":"Simulation"}]},{"@type":"TechArticle","headline":"Transaction Simulation - EVM Preview","description":"Simulate EVM transactions before broadcasting. Preview balance changes, gas fees, token transfers, and detect reverts using the Vilna API.","url":"https://docs.vilna.io/guides/simulation","datePublished":"2026-01-15","dateModified":"2026-02-22","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":"transaction-simulation","__idx":0},"children":["Transaction simulation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Simulate EVM transactions against the current chain state without broadcasting them. The API executes your calls in a sandboxed environment and returns predicted balance changes, emitted events, gas estimates, and revert errors."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-simulation","__idx":1},"children":["When to use simulation"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Pre-flight checks"]}," - verify a transaction will succeed before asking a user to sign it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fee estimation"]}," - get accurate gas costs for complex contract interactions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Balance previews"]}," - show users exactly which tokens will move and by how much."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Batch validation"]}," - test multiple calls in a single block to catch ordering issues."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"make-a-simulation-request","__idx":2},"children":["Make a simulation request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send one or more calls to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis/platform/api/simulate/simulate-evm"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /simulate/evm/{chain_gid}"]}]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chain_gid"]}," is a CAIP-2 identifier such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:1"]}," (Ethereum) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eip155:137"]}," (Polygon). All fields in each call - ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["from"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["to"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," - are required. Values are hex-encoded."]},{"$$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":"curl -X POST \"https://api.vilna.io/v1/simulate/evm/eip155:1\" \\\n  -H \"X-Api-Key: ${VILNA_API_KEY}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"block_state_calls\": [\n      {\n        \"calls\": [\n          {\n            \"from\": \"0x974caa59e49682cda0ad2bbe82983419a2ecc400\",\n            \"to\": \"0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n            \"value\": \"0x0\",\n            \"data\": \"0xa9059cbb000000000000000000000000d0930a8fc56fd94038250bb93dbac0e13da4eb99000000000000000000000000000000000000000000000000000000003b9aca00\"\n          }\n        ]\n      }\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":"const { data, error } = await client.POST(\"/simulate/evm/{chain_gid}\", {\n  params: { path: { chain_gid: \"eip155:1\" } },\n  body: {\n    block_state_calls: [\n      {\n        calls: [\n          {\n            from: \"0x974caa59e49682cda0ad2bbe82983419a2ecc400\",\n            to: \"0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n            value: \"0x0\",\n            data: \"0xa9059cbb000000000000000000000000d0930a8fc56fd94038250bb93dbac0e13da4eb99000000000000000000000000000000000000000000000000000000003b9aca00\",\n          },\n        ],\n      },\n    ],\n  },\n});\n","lang":"typescript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can include multiple calls in a single ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block_state_calls"]}," entry to simulate them sequentially within the same block. This is useful for testing approval-then-transfer flows."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"understand-the-response","__idx":3},"children":["Understand the response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response contains an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items"]}," array with one ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SimulatedTransaction"]}," per input call, plus a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," map with token and blockchain metadata."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each simulated transaction includes:"]},{"$$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":["is_success"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Whether the call executed without reverting."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["events"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Canonical events (transfers, approvals, fees) that would be emitted."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["activity"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Predicted balance changes per address and asset, with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["direction"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["in"]},"/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["out"]},") and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delta"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Present only on failure. Contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]},", and hex-encoded ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," for revert decoding."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chain_gid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The chain the transaction was simulated on."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A synthetic transaction hash for correlation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["block_number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The block height used for simulation."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["references"]}," object maps asset GIDs to token details (symbol, decimals) and chain GIDs to blockchain metadata, so you can resolve human-readable names without extra API calls."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"limitations","__idx":4},"children":["Limitations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["EVM chains only. Non-EVM chains (Solana, Tron, Bitcoin) are not supported."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Simulation reflects state at the current block. The actual outcome may differ if state changes between simulation and broadcast."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Requires the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api:blockchain:read"]}," permission on your API key."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":5},"children":["Next steps"]},{"$$mdtype":"Tag","name":"Cards","attributes":{"columns":2,"cardMinWidth":240},"children":[{"$$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":["Amounts, references, and the response envelope 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 other common workflows"]}]}]}]},"headings":[{"value":"Transaction simulation","id":"transaction-simulation","depth":1},{"value":"When to use simulation","id":"when-to-use-simulation","depth":2},{"value":"Make a simulation request","id":"make-a-simulation-request","depth":2},{"value":"Understand the response","id":"understand-the-response","depth":2},{"value":"Limitations","id":"limitations","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Transaction Simulation - EVM Preview","description":"Simulate EVM transactions before broadcasting. Preview balance changes, gas fees, token transfers, and detect reverts using the Vilna API.","priority":0.5,"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":"Simulation"}]},{"@type":"TechArticle","headline":"Transaction Simulation - EVM Preview","description":"Simulate EVM transactions before broadcasting. Preview balance changes, gas fees, token transfers, and detect reverts using the Vilna API.","url":"https://docs.vilna.io/guides/simulation","datePublished":"2026-01-15","dateModified":"2026-02-22","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-01T21:35:16.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/simulation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}