Simulations

A simulation runs Stacks transactions and Clarity code against a copy of real chain state, without broadcasting anything. Nothing you do in a simulation reaches the chain.

stxer offers two kinds:

	Session	Instant
Endpoint	POST /devtools/v2/simulations, then steps	POST /devtools/v2/simulations:instant
Steps	many, submitted in one or more calls	one transaction, plus optional reads
Execution trace	yes, unless skip_tracing	no
Stored, share link	yes	no
Typical use	scripted scenarios, tests, debugging	wallet or app preview before sending

Current vs historical state

A session forks the chain at one block, its parent block:

• Omit block_height to fork at the current tip.
• Pass block_height and block_hash to fork at any past Stacks block. The simulation then sees state exactly as it was after that block, so you can replay or vary a historical transaction.

The fork point is fixed for the life of the session and is returned in the session's metadata (block_height, block_hash, burn_block_height, epoch, …). Instant simulations accept the same two fields.

Steps

Each step sees the state left by the steps before it.

Step	What it does
Transaction	Runs a serialized transaction (hex). Produces a receipt with result, events, execution_cost, vm_error and post_condition_aborted; charges the fee, uses the nonce, enforces post conditions. The signature is not checked: the origin in the spending condition is trusted.
Eval	[sender, sponsor, contract_id, code]. Evaluates Clarity with write access in the contract's context. No fee, nonce, events or receipt. Useful for setting up state.
SetContractCode	[contract_id, source, clarity_version]. Replaces a contract's code in the fork. Keep the ABI compatible.
Reads	A batch of DataVar, MapEntry, EvalReadonly, StxBalance, FtBalance, FtSupply, Nonce reads at that point in the session.
TenureExtend	{ "cause": "Extended" } resets the block's execution cost; the SIP-034 causes (ExtendedRuntime, ExtendedReadCount, …) reset one dimension.
AdvanceBlocks	Adds bitcoin and Stacks blocks on top of the fork. See Advancing blocks.

A Transaction step that returns Ok only means it executed. Check, in order: post_condition_aborted, vm_error, then whether result is an (err …) (hex prefix 08).

What is stored

For a session, stxer keeps the fork point, each step you submitted with its result, and — unless the session was created with skip_tracing: true — the execution trace of each Transaction step. Results are retrievable by id:

• GET /devtools/v2/simulations/{id} — metadata and every step with its result.
• GET /devtools/v2/simulations/{id}/tip — the session's current tip.
• GET /devtools/v2/simulations/{id}/inspect/{txid} — the trace of one transaction step.

Instant simulations are not stored.

Session ids are random. Treat them as unguessable but not secret: anyone with the id can read the session. Do not put secrets in simulated code or transactions. When the simulator's format changes, older sessions answer 410 with a body starting simulation_outdated:; start a new session.

Share links

Every stored session can be opened in the inspector:

https://stxer.xyz/simulations/{network}/{simulation_id}
https://stxer.xyz/simulations/{network}/{simulation_id}/txid/{txid}

{network} is mainnet or testnet. The first shows all steps; the second opens the debugger on one transaction step.

On-chain transactions have their own pages, with tabs for summary, contracts, events, state changes, debugger, gas and a simulator:

https://stxer.xyz/tx/{network}/{txid}
https://stxer.xyz/tx/{network}/{txid}/debugger

See also

• Simulation sessions API and Instant simulation API
• SDK: SimulationBuilder, createSimulationSession, instantSimulation