stxer docs

Appearance

Quickstart ​

This walks through one simulation session against mainnet, first with the raw API and then with the SDK. No account or key is needed.

With curl ​

1. Start a session. A session is a private fork of the chain. Leave the body empty to fork at the current tip, or pin a block with block_height and block_hash:

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

2. Submit steps. Steps run in order against the fork. Here: evaluate Clarity, then read a balance and a nonce:

sh
curl -s -X POST https://api.stxer.xyz/devtools/v2/simulations/ed81e6c266077d3cf56d640f9a543468 \
  -H 'content-type: application/json' \
  -d '{"steps":[
        {"Eval":["SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER","","SP000000000000000000002Q6VF78.pox","(list block-height burn-block-height)"]},
        {"Reads":[{"StxBalance":"SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER"},{"Nonce":"SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER"}]}
      ]}'
json
{
  "steps": [
    { "Eval": { "Ok": "0b00000002010000000000000000000000000002f72101000000000000000000000000000da546" } },
    { "Reads": [ { "Ok": "89952768" }, { "Ok": "10" } ] }
  ]
}

Clarity values come back hex-serialized; balances and nonces come back as decimal strings.

3. Read it back. GET /devtools/v2/simulations/{id} returns the fork point and every step with its result. The same session is viewable at https://stxer.xyz/simulations/mainnet/{id}.

To run a real transaction, submit it as {"Transaction":"<hex>"}. It does not need a valid signature; see Simulations.

With the SDK ​

sh
npm install stxer
ts
import { SimulationBuilder } from 'stxer'
import { boolCV } from '@stacks/transactions'

const id = await SimulationBuilder.new({ network: 'mainnet' })
  .useBlockHeight(1044660)                       // optional; omit to fork at the tip
  .withSender('SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER')
  .addSTXTransfer({ recipient: 'SP000000000000000000002Q6VF78', amount: 1000 })
  .addContractDeploy({ contract_name: 'test', source_code: '(define-data-var enabled bool false) (define-public (set-enabled (v bool)) (ok (var-set enabled v)))' })
  .addContractCall({
    contract_id: 'SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER.test',
    function_name: 'set-enabled',
    function_args: [boolCV(true)],
  })
  .addVarRead('SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER.test', 'enabled')
  .run()

console.log(`https://stxer.xyz/simulations/mainnet/${id}`)

run() returns the simulation id. For typed per-step results (tests, assertions), use the session functions described in the SDK reference.

Next ​