Simulation sessions

A session is a fork of the chain at one block. You submit steps to it, read its state, and fetch its results and traces by id. Background: Simulations.

Create a session

POST /devtools/v2/simulations

Body field	Type	Meaning
block_height	integer or decimal string	Stacks block to fork at. Omit for the current tip.
block_hash	64 hex chars	Hash of that block; pass it with block_height.
skip_tracing	boolean	true skips traces: faster and cheaper, but no debugger view.

curl -s -X POST https://api.stxer.xyz/devtools/v2/simulations \
  -H 'content-type: application/json' \
  -d '{"block_height":1044660,"block_hash":"31c1c350a532eb2a2e183c2bcdeb7496330ad8c0fa22173058168bab6031340b"}'

{ "id": "ed81e6c266077d3cf56d640f9a543468" }

Submit steps

POST /devtools/v2/simulations/{id}

Body: { "steps": [ … ] }. Steps run in order; the response has one result per step, in the same order.

Step	Shape
Transaction	"<transaction hex>" (unsigned is fine; the origin is trusted)
Eval	[sender, sponsor or "", contract_id, code]
SetContractCode	[contract_id, source_code, clarity_version]
Reads	array of { "DataVar": [contract_id, name] }, { "MapEntry": [contract_id, map, key_hex] }, { "EvalReadonly": [sender, sponsor, contract_id, code] }, { "StxBalance": principal }, { "FtBalance": [contract_id, token, principal] }, { "FtSupply": [contract_id, token] }, { "Nonce": principal }
TenureExtend	{ "cause": "Extended" } or a SIP-034 cause such as "ExtendedRuntime"
AdvanceBlocks	{ "bitcoin_blocks": n, "stacks_blocks_per_bitcoin": m, … } — see Advancing blocks

curl -s -X POST https://api.stxer.xyz/devtools/v2/simulations/ed81e6c266077d3cf56d640f9a543468 \
  -H 'content-type: application/json' \
  -d '{"steps":[
    {"Transaction":"0000000001040053…01a4"},
    {"Eval":["SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER","","SP000000000000000000002Q6VF78.pox","(list block-height burn-block-height)"]},
    {"Reads":[{"StxBalance":"SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER"},{"Nonce":"SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER"}]},
    {"AdvanceBlocks":{"bitcoin_blocks":2,"stacks_blocks_per_bitcoin":1}}
  ]}'

Response (abbreviated):

{
  "steps": [
    { "Transaction": { "Ok": {
        "result": "0801000000000000000000000000000007db",
        "post_condition_aborted": true,
        "vm_error": "Post-condition check failure on fungible asset SP3W69VDG9VTZNG7NTW1QNCC1W45SNY98W1JSZBJH.flat-earth-stxcity::FlatEarth owned by SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01: 884190453436 SentGe 0",
        "events": [],
        "execution_cost": { "runtime": 216976, "read_count": 19, "read_length": 86380, "write_count": 0, "write_length": 0 },
        "stx_burned": 0, "tx_index": 0, "costs": 9 } } },
    { "Eval": { "Ok": "0b00000002010000000000000000000000000002f72101000000000000000000000000000da546" } },
    { "Reads": [ { "Ok": "89952768" }, { "Ok": "10" } ] },
    { "AdvanceBlocks": { "Ok": [ { "stacks_height": 1044661, "burn_height": 894279, "…": "…" }, { "stacks_height": 1044662, "…": "…" } ] } }
  ]
}

Each result is { "Ok": … } or { "Err": "<message>" }. A Transaction result of Ok means the transaction executed; check post_condition_aborted, vm_error and whether result is an (err …) (prefix 08), as in the example above, where a post condition aborted the swap. events is an array of JSON-encoded strings.

Submit to one session sequentially: a concurrent submit gets 409 simulation_busy:.

Get results

GET /devtools/v2/simulations/{id}

Returns the fork point and every step submitted so far, each with its input and Result. Transaction steps also carry TxId and ExecutionCost.

{
  "metadata": {
    "block_height": 1044660,
    "block_hash": "31c1c350a532eb2a2e183c2bcdeb7496330ad8c0fa22173058168bab6031340b",
    "burn_block_height": 894278,
    "burn_block_hash": "000000000000000000023044a3e8d2c7f69ade82f605dcabfddf268c7df7a3ab",
    "index_block_hash": "e6ab7332de530d4ce87c8950f020bd3b2a4971d6d9971267ab0d8cd2a0b975dc",
    "consensus_hash": "4a9b8cefd79eada3ad0056c6233699c6d881614e",
    "sortition_id": "c688a15f…",
    "epoch": "3.1",
    "skip_tracing": false
  },
  "steps": [
    { "Transaction": "0000000001040053…01a4",
      "TxId": "a1b639036dc4d55dfb3a7326d4917c0020e6340b0156f9bd1670a0a5122b3c9e",
      "ExecutionCost": { "runtime": 216976, "read_count": 19, "…": "…" },
      "Result": { "Transaction": { "Ok": { "…": "…" } } } },
    { "Eval": ["SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER", "", "SP000000000000000000002Q6VF78.pox", "(list block-height burn-block-height)"],
      "Result": { "Eval": { "Ok": "0b000000020100…da546" } } }
  ]
}

Session tip

GET /devtools/v2/simulations/{id}/tip

The block the session is at now. synthetic is false until an AdvanceBlocks step has run; then it is the last added block and includes vrf_seed and tenure_change.

{
  "synthetic": true,
  "stacks_height": 1044662,
  "burn_height": 894280,
  "coinbase_height": 194339,
  "block_time": 1745817275,
  "burn_block_time": 1745817275,
  "index_block_hash": "b653606d4c87905e99c4447f95ee9835617b46771f2f88567502645edf89351d",
  "consensus_hash": "c944ffab817f4d97cf8934c3e2dac2df3b25c51e",
  "burn_header_hash": "b7d5b815495a59979f3d06dc52d30d3454303a7c305ac1079b9c46d32887147b",
  "sortition_id": "f9d53fef…",
  "epoch": "3.1",
  "vrf_seed": "5d26851a…",
  "tenure_change": true
}

Batch reads

POST /devtools/v2/simulations/{id}/reads

Reads the session's current state without adding a step. All fields are optional arrays; each answer array matches its request array.

Field	Each entry
vars	[contract_id, variable_name]
maps	[contract_id, map_name, key_hex]
readonly	[contract_id, function_name, ...arg_hex]
readonly_with_sender	[sender, sponsor or "", contract_id, function_name, ...arg_hex]
stx	principal
nonces	principal
ft_balance	["<contract_id>::<token_name>", principal]
ft_supply	"<contract_id>::<token_name>"

curl -s -X POST https://api.stxer.xyz/devtools/v2/simulations/ed81e6c266077d3cf56d640f9a543468/reads \
  -H 'content-type: application/json' \
  -d '{"stx":["SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER"],
       "nonces":["SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER"],
       "readonly":[["SP000000000000000000002Q6VF78.pox-4","get-pox-info"]]}'

{
  "readonly": [ { "Ok": "070c000000061c66697273742d6275726e636861696e2d626c6f636b2d686569676874…" } ],
  "stx": [ { "Ok": "89952768" } ],
  "nonces": [ { "Ok": "10" } ]
}

Traces

GET /devtools/v2/simulations/{id}/inspect/{txid} — see Traces.