Console

POSTeth_simulateV1

Polygon Mainnethttps://polygon-mainnet.nodit.io/

Simulates the execution of multiple transactions across one or more blocks without broadcasting them to the network. Similar to eth_call, but lets you run a sequence of calls with the block context (block number, timestamp, base fee, and so on) and account state overridden with arbitrary values. Use it to debug smart contract interactions, estimate gas usage, or validate bundled transactions.

Request Body
idintegerrequired
jsonrpcstringrequired
methodstringrequired
paramsoneOf[]required

Enter the following parameters as an array according to their types.

  1. simulation payload - The block and call definitions to simulate (blockStateCalls) and the simulation options (traceTransfers, validation, returnFullTransactions).
  2. block identifier - The parent block used as the base of the simulation. You can enter a block number, block hash, or block tag. Defaults to latest when omitted.
params[0]object
blockStateCallsobject[]required

Array of block definitions to simulate. Up to 256 blocks can be specified, and each block is executed sequentially.

blockOverridesobject

Overrides the block context used for the simulation.

numberstring

The block number to simulate, as a hex string. Block numbers must increase; skipped block numbers are included in the response as empty blocks.

timestring

The block timestamp as a hex string.

gasLimitstring

The block gas limit as a hex string.

feeRecipientstring

The address that receives the fees, as a string.

prevRandaostring

The PREVRANDAO value of the block, as a hex string.

baseFeePerGasstring

The base fee per gas of the block, as a hex string.

blobBaseFeestring

The blob base fee of the block, as a hex string.

withdrawalsobject[]

List of validator withdrawals to include in the block. (EIP-4895)

stateOverridesobject

Overrides account state with arbitrary values for the duration of the simulation only, without changing on-chain state. Each key is a target address, and its value can contain the following fields.

  • balance: A hex string that overrides the account balance.
  • nonce: A hex string that overrides the account nonce.
  • code: Fake EVM bytecode to inject into the account, as a hex string.
  • state: A set of key-value pairs that replaces the entire account storage. Each key and value is a hex string.
  • stateDiff: A set of key-value pairs that overrides individual account storage slots. Similar to state, but used when only specific slots should be changed.
  • movePrecompileToAddress: Moves the precompile at this address to another address. It is applied before the code override, and the behavior is client-specific when the target is not a precompile.

state and stateDiff are mutually exclusive — specify only one of them per account.

callsobject[]

Array of call objects to execute sequentially in this block.

typestring

The transaction type as a hex string. Defaults to 0x2 (EIP-1559).

fromstring

The transaction sender (from) address as a string.

tostring

The transaction recipient (to) address as a string. Can be omitted when deploying a contract.

gasstring

The gas limit allocated to this call, as a hex string.

gasPricestring

The price per gas unit, as a hex string. (Legacy transactions)

maxFeePerGasstring

The maximum fee per gas you are willing to pay, as a hex string. (EIP-1559)

maxPriorityFeePerGasstring

The maximum priority fee per gas paid to the validator, as a hex string. (EIP-1559)

maxFeePerBlobGasstring

The maximum fee per blob gas you are willing to pay, as a hex string. Defaults to 0x0. (EIP-4844)

blobVersionedHashesstring[]

Versioned hashes of the blobs. Defaults to an empty array. (EIP-4844)

noncestring

The transaction nonce as a hex string.

valuestring

The value of the transaction.

inputstring

The hashed method signature of the transaction to execute. You can find it in the ABI. It can also be provided in the data field.

accessListobject[]

List of addresses and storage keys the transaction accesses during execution. (EIP-2930)

traceTransfersboolean

When set to true, native token transfers are included in the response logs as ERC-20 Transfer events. Defaults to false.

validationboolean

When set to true, EVM validation rules (balance, nonce, fees, and so on) are applied except for signature checks, making the simulation closer to a real transaction. Defaults to false.

returnFullTransactionsboolean

When set to true, the transactions field in the response returns full transaction objects instead of transaction hashes. Defaults to false.

params[1]string

Use one of block hash, block number, or block tag to specify a block.

  • Block number: hex string (ex. "0x1")
  • Block hash: 64-character hex string (ex. "0x39008d07edf93c03bb9d1cfc80598fcf63f441ec86e9de3733fa6a484980ca48")]
  • Block tag: enum string (ex. "latest", "earliest", "pending")
    • earliest: The oldest available block on the chain.
    • finalized: A recently finalized block that can no longer be changed. Primarily used in proof-of-stake (PoS) blockchains.
    • safe: A recent block considered safe by the network (immune to reorgs).
    • latest: The most recent block on the chain (may be subject to reorgs).
    • pending: The next block to be mined, including pending transactions in the mempool.
Responses
baseFeePerGasstring

Base fee per gas of the simulated block (EIP-1559, hex wei)

blobGasUsedstring

Amount of blob gas used in the block (EIP-4844, hex)

difficultystring

Block difficulty (hex)

excessBlobGasstring

Amount of blob gas used above the target (EIP-4844, hex)

extraDatastring

Arbitrary data included in the block (hex)

gasLimitstring

Maximum total gas allowed in this block (hex)

gasUsedstring

Total gas used by all transactions in this block (hex)

hashstring

Hash of the simulated block

logsBloomstring

Bloom filter for event log search (2048 bits, hex)

minerstring

Block miner address. Can be changed with blockOverrides.feeRecipient.

mixHashstring

Mix hash of the block

noncestring

Block nonce (hex)

numberstring

Simulated block number (hex)

parentBeaconBlockRootstring

Root hash of the parent beacon block (EIP-4788)

parentHashstring

Hash of the parent block

receiptsRootstring

Root hash of the transaction receipts trie

sha3Unclesstring

SHA3 hash of the uncles list

sizestring

Block size in bytes (hex)

stateRootstring

Root hash of the state trie

timestampstring

Block creation time (Unix timestamp, hex). Can be changed with blockOverrides.time.

transactionsoneOf

List of transactions included in the block. Returns an array of full transaction objects when returnFullTransactions is set to true, and an array of transaction hashes otherwise.

array 1string[]
array 2object[]
transactionsRootstring

Root hash of the transactions trie

unclesstring[]

Array of uncle block hashes

indexstring

Withdrawal index (hex)

validatorIndexstring

Validator index (hex)

addressstring

Withdrawal recipient address

amountstring

Withdrawal amount (in Gwei, hex)

withdrawalsRootstring

Root hash of the withdrawals trie (EIP-4895)

statusstring

Execution status of the call. Returns 0x1 on success and 0x0 on failure (including reverts).

returnDatastring

Data returned by the call (hex). Contains the revert data when the call fails.

gasUsedstring

Amount of gas used to execute the call (hex)

maxUsedGasstring

Maximum gas used during execution before refunds are applied (hex)

logsobject[]

Event logs emitted during the call. When traceTransfers is set to true, native token transfers are also included as ERC-20 Transfer events (address 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee).

addressstring

The address of the contract that emitted this log

topicsstring[]

Array of event signature hash and indexed parameters (up to 4 entries)

datastring

Non-indexed event parameter data (hex encoded)

blockNumberstring

Block number containing this log (hex)

transactionHashstring

Hash of the transaction that created this log

transactionIndexstring

Transaction position index within the block (hex)

blockHashstring

Hash of the block containing this log

logIndexstring

Log position index within the block (hex)

removedboolean

True if the log was removed due to a chain reorganization

errorobject

Error object returned only when the call fails.

codeinteger

Error code. Returns 3 when the call reverted, or -32015 on a VM execution error.

messagestring

Error message

datastring

Additional error data such as the revert reason (hex). May not be provided depending on the client.

X-API-KEY
RequestCU35
cURL
curl -X POST "https://polygon-mainnet.nodit.io/" \
  -H "X-API-KEY: {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "eth_simulateV1",
  "params": [
    {
      "blockStateCalls": [
        {
          "blockOverrides": {
            "baseFeePerGas": "0x9"
          },
          "stateOverrides": {
            "0xc000000000000000000000000000000000000000": {
              "balance": "0x4a817c420"
            }
          },
          "calls": [
            {
              "from": "0xc000000000000000000000000000000000000000",
              "to": "0xc000000000000000000000000000000000000001",
              "maxFeePerGas": "0xf",
              "value": "0x1"
            }
          ]
        }
      ],
      "traceTransfers": true,
      "validation": true
    },
    "latest"
  ]
}'
Response
Example · 200
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "baseFeePerGas": "0x9",
      "blobGasUsed": "0x0",
      "calls": [
        {
          "returnData": "0x",
          "logs": [
            {
              "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
              "topics": [
                "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                "0x000000000000000000000000c000000000000000000000000000000000000000",
                "0x000000000000000000000000c000000000000000000000000000000000000001"
              ],
              "data": "0x0000000000000000000000000000000000000000000000000000000000000001",
              "blockNumber": "0x14f2b4b",
              "transactionHash": "0x87c1eb6a0b1a2f4a5b1e7c7fbf16a6f9ee1b3d6d1e19b4a8ca31b2f1a4b6b8a1",
              "transactionIndex": "0x0",
              "blockHash": "0x920189344ddf2bfadb7c8cf4362b8e8c18bfb021a5f6630f84d17460ca05f58c",
              "logIndex": "0x0",
              "removed": false
            }
          ],
          "gasUsed": "0x5208",
          "status": "0x1"
        }
      ],
      "gasLimit": "0x4c4b40",
      "gasUsed": "0x5208",
      "hash": "0x920189344ddf2bfadb7c8cf4362b8e8c18bfb021a5f6630f84d17460ca05f58c",
      "number": "0x14f2b4b",
      "parentHash": "0x1e1b1cc0a1a1f1e6b6f6bbecdc3a1c1b1a0b7c9c8d8e9f0a1b2c3d4e5f607180",
      "timestamp": "0x6821b0a0",
      "transactions": [
        "0x87c1eb6a0b1a2f4a5b1e7c7fbf16a6f9ee1b3d6d1e19b4a8ca31b2f1a4b6b8a1"
      ]
    }
  ]
}

Last updated