# Simulate EVM transactions

Simulate one or more EVM transactions and return execution results.

Endpoint: POST /simulate/evm/{chain_gid}
Version: 0.23.9
Security: Auth

## Path parameters:

  - `chain_gid` (string, required)
    Blockchain identifier in CAIP-2 format (namespace:reference).

## Request fields (application/json):

  - `validation` (boolean)
    When true, the simulation checks sender balance, nonce sequence, and
fee consistency the same way a real submission would. When false
(default), missing parameters are filled with permissive defaults
and balance is not checked.

  - `block_state_calls` (array, required)
    Blocks to simulate.

  - `block_state_calls.calls` (array, required)
    Calls in this block.

  - `block_state_calls.calls.from` (string, required)
    Sender address.
    Example: "0x974caa59e49682cda0ad2bbe82983419a2ecc400"

  - `block_state_calls.calls.to` (string, required)
    Recipient address.
    Example: "0xd0930a8fc56fd94038250bb93dbac0e13da4eb99"

  - `block_state_calls.calls.value` (string)
    Transfer value in wei (decimal or 0x hex).
    Example: "10000000000000000"

  - `block_state_calls.calls.data` (string)
    Call data (hex).
    Example: "0xa9059cbb000000000000000000000000d0930a8fc56fd94038250bb93dbac0e13da4eb99000000000000000000000000000000000000000000000000000000003b9aca00"

  - `block_state_calls.calls.nonce` (string)
    Sender nonce (decimal or 0x hex). If omitted, the current nonce is used.
    Example: "1"

  - `block_state_calls.calls.gas` (string)
    Gas limit (decimal or 0x hex). If omitted, no limit is enforced.
    Example: "21000"

  - `block_state_calls.calls.gas_price` (string)
    Gas price in wei (decimal or 0x hex). Legacy transactions only. Mutually exclusive with max_fee_per_gas / max_priority_fee_per_gas.
    Example: "1000000000"

  - `block_state_calls.calls.max_fee_per_gas` (string)
    Max fee per gas in wei (decimal or 0x hex). EIP-1559 only. Mutually exclusive with gas_price.
    Example: "2000000000"

  - `block_state_calls.calls.max_priority_fee_per_gas` (string)
    Priority fee (tip) per gas in wei (decimal or 0x hex). EIP-1559 only. Mutually exclusive with gas_price.
    Example: "1000000000"

## Response 200 fields (application/json):

  - `items` (array, required)
    List of simulated transaction results, one per input call in submission order.
    Example: [{"chain_gid":"eip155:1","hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","block_number":18500000,"is_success":true,"confirmed_at":null,"created_at":"2024-01-15T10:30:00Z"}]

  - `items.chain_gid` (string, required)
    Blockchain identifier in [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) format.

Format: {namespace}:{reference}
- namespace: Ecosystem identifier (3-8 chars, lowercase)
- reference: Blockchain identifier within namespace (1-32 chars)

Examples:
- eip155:1 — Ethereum mainnet
- eip155:56 — BNB Smart Chain mainnet
- eip155:137 — Polygon mainnet
- bip122:000000000019d6689c085ae165831e93 — Bitcoin mainnet
- tron:mainnet — Tron mainnet
    Example: "eip155:1"

  - `items.hash` (string, required)
    Transaction hash identifier on the blockchain.
    Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

  - `items.block_number` (integer, required)
    Block number/height on the blockchain.
    Example: 18500000

  - `items.is_success` (boolean, required)
    Transaction execution status.
    Example: true

  - `items.confirmed_at` (any, required)
    Timestamp when the transaction reached required confirmations. Null if the transaction is not yet confirmed.

  - `items.created_at` (string, required)
    Timestamp when the resource was created.
    Example: "2024-01-15T10:30:00Z"

  - `items.events` (array, required)
    Canonical events that would be emitted, ordered by sequence.
    Example: [{"hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","sequence":0,"kind":"transfer","data":{"kind":"transfer","asset_gid":"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7","from":"0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4","to":"0x95212290dd7278aa3ddd389cc1e1d165cc4bafe5","amount":{"base":"1000000","formatted":"1.0"},"source":"contract"}}]

  - `items.events.hash` (string, required)
    Transaction hash identifier on the blockchain.
    Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

  - `items.events.sequence` (integer, required)
    Event position within the transaction (0-based).

  - `items.events.kind` (string, required)
    Type of canonical event.
    Enum: "transfer", "utxo_transfer", "fee", "approval", "call", "contract_create"

  - `items.events.data` (any, required)
    Example: {"kind":"transfer","asset_gid":"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7","from":"0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4","to":"0x95212290dd7278aa3ddd389cc1e1d165cc4bafe5","amount":{"base":"1000000","formatted":"1.0"},"source":"contract"}

  - `items.activity` (array, required)
    Predicted balance changes for involved addresses.
    Example: [{"chain_gid":"eip155:1","hash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","address":"0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4","asset_gid":"eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7","direction":"out","delta":{"base":"-1000000","formatted":"-1.0"},"created_at":"2024-01-15T10:30:00Z"}]

  - `items.activity.chain_gid` (string, required)
    Blockchain identifier in [CAIP-2](https://chainagnostic.org/CAIPs/caip-2) format.

Format: {namespace}:{reference}
- namespace: Ecosystem identifier (3-8 chars, lowercase)
- reference: Blockchain identifier within namespace (1-32 chars)

Examples:
- eip155:1 — Ethereum mainnet
- eip155:56 — BNB Smart Chain mainnet
- eip155:137 — Polygon mainnet
- bip122:000000000019d6689c085ae165831e93 — Bitcoin mainnet
- tron:mainnet — Tron mainnet
    Example: "eip155:1"

  - `items.activity.hash` (string, required)
    Transaction hash identifier on the blockchain.
    Example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

  - `items.activity.address` (string, required)
    Blockchain address in its native format.

Format by network:
- EVM: 0x + 40 hex chars (normalized to [EIP-55](https://eips.ethereum.org/EIPS/eip-55) checksum on import)
- Bitcoin: P2PKH (1...), P2SH (3...), P2WPKH (bc1...)
- Solana: Base58, 32-44 chars
- Tron: Base58, starts with T
    Example: "0x742d35cc6634c0532925a3b8d1e1d78d8E15e5c4"

  - `items.activity.asset_gid` (string, required)
    Global asset identifier in [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) format.

Format: {chain_gid}/{asset_path}

Examples:
- eip155:1/slip44:60 — ETH on Ethereum
- eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7 — USDT on Ethereum
- eip155:56/bep20:0x55d398326f99059fF775485246999027B3197955 — USDT on BNB Smart Chain
- tron:0x2b6653dc/trc20:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t — USDT on Tron
- eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 — USDC on Polygon
    Example: "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7"

  - `items.activity.direction` (string, required)
    Direction of the asset movement relative to the tracked address.
    Enum: "in", "out"

  - `items.activity.delta` (object, required)
    Signed balance change in base units, plus a human-readable value
when we know the token's decimals.
    Example: {"base":"-1000000","formatted":"-1.0"}

  - `items.activity.delta.base` (string, required)
    Signed amount in the smallest asset unit.
    Example: "-1000000"

  - `items.activity.delta.formatted` (string)
    Human-readable signed amount.
    Example: "-1.0"

  - `items.activity.created_at` (string, required)
    Timestamp when the resource was created.
    Example: "2024-01-15T10:30:00Z"

  - `items.error` (object)
    Error details for a failed simulation.

  - `items.error.code` (integer, required)
    Error code from the EVM execution.
    Example: -32000

  - `items.error.message` (string, required)
    Human-readable error message.
    Example: "execution reverted"

  - `items.error.data` (string)
    Raw revert data (hex-encoded) for detailed error decoding.
    Example: "0x08c379a00000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001a4e6f7420656e6f75676820746f6b656e2062616c616e636500000000000000"

  - `references` (object, required)
    Related objects included in the response, keyed by ID.

  - `references.tokens` (object)
    Map of tokens indexed by their CAIP-19 Asset GID.

  - `references.blockchains` (object)
    Map of blockchains indexed by their CAIP-2 Chain GID.

  - `references.addresses` (object)
    Map of tracked addresses to labels. Presence in this map means the address is tracked; value is label or null.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/invalid-request"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Invalid Request"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "Validation error"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "blockchain.name_too_long"

  - `fields` (array)
    List of invalid fields in the request

  - `fields.name` (string, required)
    The name of the invalid field
    Example: "meta"

  - `fields.reason` (string, required)
    Why this field is invalid
    Example: "Exceeded maximum data size — must not exceed 1000 characters"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/unauthorized"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Unauthorized"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 401

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "Missing or invalid authentication credentials"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "auth.unauthorized"

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/forbidden"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Forbidden"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 403

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "You do not have permission to perform this action"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "chain.not_allowed"

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/not-found"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Not Found"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 404

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "The requested resource was not found"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "blockchain.not_found"

## Response 422 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.
    Example: "https://docs.vilna.io/apis/problems/precondition-failed"

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.
    Example: "Precondition Failed"

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 422

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: "The request cannot be processed due to failed business rule validation"

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.
    Example: "simulation.failed"

  - `fields` (array)
    List of fields that failed precondition validation

  - `fields.name` (string, required)
    The name of the field that failed validation
    Example: "status"

  - `fields.reason` (string, required)
    Why the precondition failed for this field
    Example: "Cannot transition from archived to active state"

## Response default fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
Open it in a browser to read about this category of error.

  - `title` (string, required)
    A short summary of the error type.
Use detail for information specific to this occurrence.

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.

  - `code` (string, required)
    Stable machine-readable error code ({domain}.{reason}) for programmatic error handling. Unlike the HTTP status or free-form detail, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to unspecified when the server has not assigned a specific code.