Simulator control API
Acton-only control routes for local state, wallets, address names, compiler ABI metadata, simulated network conditions, and raw local message injection. These routes are intended for local development tooling and should not be exposed publicly. When simulator is started with --require-auth, these routes require the simulator API token. Rate limiting applies only to /api routes, and response delay applies only to TON Center-compatible API routes; control routes remain available when --rate-limit or --response-delay-ms is enabled.
Acton-only control routes for local state, wallets, address names, compiler ABI metadata, simulated network conditions, and raw local message injection.
These routes are intended for local development tooling and should not be exposed publicly. When simulator is started with --require-auth, these routes require the simulator API token. Rate limiting applies only to /api routes, and response delay applies only to TON Center-compatible API routes; control routes remain available when --rate-limit or --response-delay-ms is enabled.
Fund an account
Queues a local faucet transfer to credit an address. The transfer is included on the next automatic or manually mined block.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_fundAccount" \ -H "Content-Type: application/json" \ -d '{ "address": "0:2222222222222222222222222222222222222222222222222222222222222222", "amount": 1000000000 }'{
"ok": true,
"@extra": "string",
"result": {
"ok": true,
"result": {
"tx_hash": "string",
"block_seqno": 0
}
}
}Mint jettons to an account
Finds the jetton master in simulator state, verifies that it is mintable and has an admin, converts the display amount using the decimals from jetton metadata, preflights the legacy 0x15 and current 0x642b7d07 mint layouts, and queues the uniquely accepted message for the next block.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_fundJetton" \ -H "Content-Type: application/json" \ -d '{ "address": "0:2222222222222222222222222222222222222222222222222222222222222222", "jetton_master": "0:3333333333333333333333333333333333333333333333333333333333333333", "amount": "12.5" }'{
"ok": true,
"@extra": "string",
"result": {
"@type": "ok",
"hash": "string",
"hash_norm": "string"
}
}Get address names
Returns local names for the requested addresses. Missing names are returned as null.
Simulator API token printed by acton simulator start --require-auth.
In: header
Query Parameters
1 <= itemsResponse Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_getAddressName?address=string"{
"ok": true,
"@extra": "string",
"result": {
"property1": "string",
"property2": "string"
}
}Set an address name
Sets or updates the local name for an address.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setAddressName" \ -H "Content-Type: application/json" \ -d '{ "address": "0:2222222222222222222222222222222222222222222222222222222222222222", "name": "deployer" }'{
"ok": true,
"@extra": "string",
"result": null
}Get compiler ABI metadata
Returns extended contract ABI metadata for the requested code hashes. Missing ABI entries are returned as null.
Simulator API token printed by acton simulator start --require-auth.
In: header
Query Parameters
1 <= itemsResponse Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_getCompilerAbi?code_hash=string"{
"ok": true,
"@extra": "string",
"result": {
"property1": {
"compiler_abi": null,
"display_name": "string",
"code_hashes": [
"string"
],
"links": [
{
"kind": "string",
"title": "string",
"url": "http://example.com",
"scope": "string"
}
]
},
"property2": {
"compiler_abi": null,
"display_name": "string",
"code_hashes": [
"string"
],
"links": [
{
"kind": "string",
"title": "string",
"url": "http://example.com",
"scope": "string"
}
]
}
}
}List registered compiler ABI metadata
Returns compiler ABI metadata registered directly in the simulator node.
Simulator API token printed by acton simulator start --require-auth.
In: header
Response Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_listCompilerAbis"{
"ok": true,
"@extra": "string",
"result": [
{
"codeHash": "string",
"abi": {
"compiler_abi": null,
"display_name": "string",
"code_hashes": [
"string"
],
"links": [
{
"kind": "string",
"title": "string",
"url": "http://example.com",
"scope": "string"
}
]
},
"savedAt": 0
}
]
}Delete registered compiler ABI metadata
Deletes a locally registered compiler ABI entry by code hash or one of its code hash aliases.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Hash in hex or base64 format.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_deleteCompilerAbi" \ -H "Content-Type: application/json" \ -d '{ "code_hash": "f4SmFiL+Y0Yxu0Uw1zIfTDQ/JT6Qje03EmHlaQQWDK8=" }'{
"ok": true,
"@extra": "string",
"result": null
}Get verified contract source
Proxies TON verifier source lookup by address or code hash and returns the verified source bundle when the contract is confirmed.
Simulator API token printed by acton simulator start --require-auth.
In: header
Query Parameters
TON address in raw or user-friendly format.
Hash in hex or base64 format.
Response Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_getVerifiedSource"{
"ok": true,
"@extra": "string",
"result": {
"code_hash": "string",
"verified": true,
"bundle": {
"source_bundle_hash": "string",
"verified_at": 0,
"storage_revision": "string",
"entrypoint": "string",
"compiler": {
"language": "string",
"version": "string",
"params": null
},
"files": [
{
"path": "string",
"content_hash": "string",
"include_in_command": true,
"is_stdlib": true,
"has_include_directives": true,
"content": "string"
}
]
}
}
}Get registered contract source
Returns the source bundle registered directly in the simulator node for an address or code hash.
Simulator API token printed by acton simulator start --require-auth.
In: header
Query Parameters
TON address in raw or user-friendly format.
Hash in hex or base64 format.
Response Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_getRegisteredVerifiedSource"{
"ok": true,
"@extra": "string",
"result": {
"code_hash": "string",
"verified": true,
"bundle": {
"source_bundle_hash": "string",
"verified_at": 0,
"storage_revision": "string",
"entrypoint": "string",
"compiler": {
"language": "string",
"version": "string",
"params": null
},
"files": [
{
"path": "string",
"content_hash": "string",
"include_in_command": true,
"is_stdlib": true,
"has_include_directives": true,
"content": "string"
}
]
}
}
}List registered contract sources
Returns source bundles registered directly in the simulator node, one per code hash.
Simulator API token printed by acton simulator start --require-auth.
In: header
Response Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_listVerifiedSources"{
"ok": true,
"@extra": "string",
"result": [
{
"codeHash": "string",
"source": {
"code_hash": "string",
"verified": true,
"bundle": {
"source_bundle_hash": "string",
"verified_at": 0,
"storage_revision": "string",
"entrypoint": "string",
"compiler": {
"language": "string",
"version": "string",
"params": null
},
"files": [
{
"path": "string",
"content_hash": "string",
"include_in_command": true,
"is_stdlib": true,
"has_include_directives": true,
"content": "string"
}
]
}
},
"savedAt": 0
}
]
}Delete registered contract source
Deletes a locally registered source bundle by code hash.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Hash in hex or base64 format.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_deleteVerifiedSource" \ -H "Content-Type: application/json" \ -d '{ "code_hash": "f4SmFiL+Y0Yxu0Uw1zIfTDQ/JT6Qje03EmHlaQQWDK8=" }'{
"ok": true,
"@extra": "string",
"result": null
}Register compiler ABI metadata
Registers one or more extended compiler ABI payloads for later explorer and API lookups by code hash.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_registerCompilerAbis" \ -H "Content-Type: application/json" \ -d '{ "entries": [ { "abi": { "compiler_abi": { "contract_name": "Wallet", "get_methods": [], "incoming_messages": [] }, "display_name": "Wallet", "code_hashes": [ "f4SmFiL+Y0Yxu0Uw1zIfTDQ/JT6Qje03EmHlaQQWDK8=" ], "links": [] } } ] }'{
"ok": true,
"@extra": "string",
"result": null
}Register contract sources
Registers one or more source artifacts for later explorer source-code and retrace lookups by code hash.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_registerVerifiedSources" \ -H "Content-Type: application/json" \ -d '{ "entries": [ { "code_hash": "f4SmFiL+Y0Yxu0Uw1zIfTDQ/JT6Qje03EmHlaQQWDK8=", "source": { "code_hash": "f4SmFiL+Y0Yxu0Uw1zIfTDQ/JT6Qje03EmHlaQQWDK8=", "verified": true, "bundle": null } } ] }'{
"ok": true,
"@extra": "string",
"result": null
}Create snapshot
Saves the current state as a persistent JSON snapshot without stopping the node. The returned ID identifies the saved file.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_createSnapshot" \ -H "Content-Type: application/json" \ -d '{ "name": "before-upgrade" }'{
"ok": true,
"@extra": "string",
"result": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"created_at": 0,
"block_seqno": 0,
"size_bytes": 0
}
}List snapshots
Lists saved JSON snapshots, including snapshots from earlier node runs.
Simulator API token printed by acton simulator start --require-auth.
In: header
Response Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_listSnapshots"{
"ok": true,
"@extra": "string",
"result": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"created_at": 0,
"block_seqno": 0,
"size_bytes": 0
}
]
}Restore snapshot
Restores state in the node mutation queue without restarting the process or deleting any saved snapshots.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_restoreSnapshot" \ -H "Content-Type: application/json" \ -d '{ "id": "f25d4568-af6a-4f5f-a857-ebcf90648a9f" }'{
"ok": true,
"@extra": "string",
"result": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"created_at": 0,
"block_seqno": 0,
"size_bytes": 0
}
}Delete snapshot
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_deleteSnapshot" \ -H "Content-Type: application/json" \ -d '{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }'{
"ok": true,
"@extra": "string",
"result": null
}Download snapshot
Downloads the selected saved JSON file without capturing new state.
Simulator API token printed by acton simulator start --require-auth.
In: header
Query Parameters
1 <= lengthResponse Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_exportSnapshot?id=string"{
"format_version": 1,
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"created_at": 0,
"fork_network": "string",
"state": {}
}Import snapshot
Validates and saves a JSON snapshot under a new ID without changing the running state. An optional name overrides the name in the file.
Simulator API token printed by acton simulator start --require-auth.
In: header
Query Parameters
1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_importSnapshot" \ -H "Content-Type: application/json" \ -d '{ "format_version": 1, "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "created_at": 0, "state": {} }'{
"ok": true,
"@extra": "string",
"result": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"created_at": 0,
"block_seqno": 0,
"size_bytes": 0
}
}Replace blockchain config
Validates and replaces the full blockchain config dictionary from a base64-encoded BOC, then commits the change in a config-only block.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Base64-encoded TON BOC.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setConfig" \ -H "Content-Type: application/json" \ -d '{ "config": "te6ccgEC..." }'{
"ok": true,
"@extra": "string",
"result": {
"config_hash": "string",
"block_seqno": 0
}
}Update a blockchain config parameter
Checks the parameter's expected representation hash and commits its replacement in a new block, even with automatic mining disabled. A null expectedHash adds a missing parameter. Other parameters and historical configs are preserved. Parameter 0 cannot be changed.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setConfigParam" \ -H "Content-Type: application/json" \ -d '{ "index": 0, "boc": "string" }'{
"ok": true,
"@extra": "string",
"result": {
"config_hash": "string",
"block_seqno": 0
}
}Set a ShardAccount
Replaces the selected account state with a base64-encoded ShardAccount BOC.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setShardAccount" \ -H "Content-Type: application/json" \ -d '{ "address": "0:2222222222222222222222222222222222222222222222222222222222222222", "shard_account": "te6ccgEBAQEA..." }'{
"ok": true,
"@extra": "string",
"result": null
}Change account state
Changes the selected local account state to nonexist, uninit, or frozen. When state is frozen with source=current, set mine=false to queue the synthetic freeze transaction for the next mined block instead of committing a block immediately.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_changeAccountState" \ -H "Content-Type: application/json" \ -d '{ "address": "0:2222222222222222222222222222222222222222222222222222222222222222", "mine": false, "state": { "type": "frozen", "source": "current" } }'{
"ok": true,
"@extra": "string",
"result": null
}Send a raw internal message
Injects a base64-encoded internal message BOC into the local internal queue. TON Center-compatible message endpoints accept external-in messages only.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Base64-encoded TON BOC.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_sendInternalMessage" \ -H "Content-Type: application/json" \ -d '{ "boc": "te6ccgEBAQEA..." }'{
"ok": true,
"@extra": "string",
"result": {
"@type": "ok",
"hash": "string",
"hash_norm": "string"
}
}List startup accounts
Returns public account descriptors selected when the simulator server started.
Simulator API token printed by acton simulator start --require-auth.
In: header
Response Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_getStartupAccounts"{
"ok": true,
"@extra": "string",
"result": [
{
"name": "string",
"version": "string",
"network": "string",
"address": "string"
}
]
}Set empty-block mining mode
Controls whether automatic and manual mining skip blocks with no pending messages. Set skip_empty_blocks to false to produce empty blocks. This does not enable or disable automatic mining.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Skip mining when no messages are pending. The startup default is true.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setMiningMode" \ -H "Content-Type: application/json" \ -d '{ "skip_empty_blocks": true }'{
"ok": true,
"@extra": "string",
"result": {
"skip_empty_blocks": true
}
}Mine simulator blocks
Manually mines queued and/or empty simulator blocks. When the request body is omitted or blocks is not provided, one block is mined.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_mine" \ -H "Content-Type: application/json" \ -d '{ "blocks": 3 }'{
"ok": true,
"@extra": "string",
"result": {
"blocks_mined": 1,
"last_block_seqno": 0,
"blocks": [
{
"workchain": 0,
"shard": 0,
"seqno": 0,
"root_hash": "string",
"file_hash": "string"
}
]
}
}Increase virtual time
Adds seconds to the simulator virtual clock. Future blocks use this adjusted time until it is changed again.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_increaseTime" \ -H "Content-Type: application/json" \ -d '{ "seconds": 3600 }'{
"ok": true,
"@extra": "string",
"result": {
"current_unix_time": 0,
"time_offset_seconds": 0,
"next_block_timestamp": 0
}
}Set virtual time
Sets the simulator virtual clock to a Unix timestamp. The timestamp must not be lower than the latest mined block time.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setTime" \ -H "Content-Type: application/json" \ -d '{ "timestamp": 1710000000 }'{
"ok": true,
"@extra": "string",
"result": {
"current_unix_time": 0,
"time_offset_seconds": 0,
"next_block_timestamp": 0
}
}Set next block timestamp
Sets a one-shot Unix timestamp for the next mined block. The timestamp is consumed by the next automatic or manually mined block and must not be lower than the latest mined block time.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setNextBlockTimestamp" \ -H "Content-Type: application/json" \ -d '{ "timestamp": 1710000600 }'{
"ok": true,
"@extra": "string",
"result": {
"current_unix_time": 0,
"time_offset_seconds": 0,
"next_block_timestamp": 0
}
}Set simulated network conditions
Updates simulated network conditions while the simulator server is running and returns the updated values. Set response_delay_ms to 0 to disable response delay. Current values are also available from /acton_nodeInfo.
Simulator API token printed by acton simulator start --require-auth.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "http://127.0.0.1:5411/acton_setNetworkConditions" \ -H "Content-Type: application/json" \ -d '{ "response_delay_ms": 0 }'{
"ok": true,
"@extra": "string",
"result": {
"response_delay_ms": 0
}
}Get node status
Returns uptime, latest block seqno, local or remote state-source information, and current simulated network conditions.
Simulator API token printed by acton simulator start --require-auth.
In: header
Response Body
application/json
curl -X GET "http://127.0.0.1:5411/acton_nodeInfo"{
"ok": true,
"@extra": "string",
"result": {
"uptime_seconds": 0,
"last_block_seqno": 0,
"state_source": "local",
"fork_network": "string",
"fork_block_number": 0,
"current_unix_time": 0,
"time_offset_seconds": 0,
"next_block_timestamp": 0,
"network_conditions": {
"response_delay_ms": 0
}
}
}Last updated on