Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ton-blockchain/acton/llms.txt

Use this file to discover all available pages before exploring further.

acton localnet runs a full TON-compatible development node on your machine, giving you a zero-cost sandbox where transactions confirm instantly, wallets can be funded on demand, and the entire network state can be snapshotted and restored. The local node exposes a TonCenter-compatible API at http://127.0.0.1:<port> and includes a built-in single-page explorer UI at the root path. When fork mode is enabled, Acton pulls remote account state from testnet or mainnet on demand, so you can develop against real deployed contracts without waiting for a remote network.

​
Synopsis

acton localnet <SUBCOMMAND> [OPTIONS]

​
Subcommands

SubcommandDescription
startStart the local TON network node
airdropSend TON from the local faucet to an address
statusInspect the status of a running localnet

​
acton localnet start

Start the local TON network. The node runs in the foreground on 127.0.0.1:<port> until you stop it with Ctrl+C or kill the process. Synopsis 
acton localnet start [OPTIONS]
Options
FlagTypeDefaultDescription
--portnumber5411Port for the localnet API server
--fork-netstring—Remote network to fork account state from: testnet or mainnet
--fork-block-numbernumber—Historical block seqno to fork from (pins to a specific state)
--accountsstrings—Comma-separated wallet names to auto-fund and deploy on startup
--db-pathpath—SQLite database path for persistent node state across restarts
--load-statepath—Load node state from a JSON snapshot before starting
--dump-statepath—Write a JSON snapshot on graceful shutdown
--rate-limitnumber—Max /api/* requests per second (simulates provider rate limits)
--load-state and --db-path are mutually exclusive — you cannot use both in the same run.

​
acton localnet airdrop

Send TON from the local faucet to any address. The localnet must already be running. Synopsis 
acton localnet airdrop <ADDRESS> [OPTIONS]
Options
FlagTypeDefaultDescription
ADDRESSstringrequiredRecipient address (friendly or raw format)
-a, --amountnumber100Amount of TON to send
-p, --portnumber5411Localnet server port

​
acton localnet status

Inspect whether a localnet is running on the given port and print basic node information. Synopsis 
acton localnet status [OPTIONS]
Options
FlagTypeDefaultDescription
-p, --portnumber5411Localnet server port to check
--jsonflag—Print machine-readable JSON (includes running field for automation)

​
Acton.toml configuration

Store localnet defaults in Acton.toml to avoid repeating flags on every start. CLI flags override config values for the current invocation.
Acton.toml
[localnet]
port = 5411
fork-net = "testnet"
fork-block-number = 55000000
accounts = ["deployer", "user"]
rate-limit = 25

​
API endpoints

The localnet server exposes:
EndpointDescription
GET /Built-in single-page explorer UI
GET /api/v2/*TonCenter v2 compatible API
GET /api/v3/*TonCenter v3 compatible API
POST /api/v2/sendBocSend external-in messages
POST /api/v3/messageSend external-in messages
GET /acton_nodeInfoUptime, latest block seqno, active state source
POST /acton_dumpStateWrite a JSON snapshot without stopping the server
POST /acton_loadStateReplace current state from a JSON snapshot
POST /acton_setShardAccountReplace an account’s ShardAccount with a base64 BoC
POST /acton_sendInternalMessageInject a raw internal message BoC
TonCenter-compatible message endpoints (/api/v2/sendBoc, /api/v3/message) accept external-in messages only. Use /acton_sendInternalMessage when you need to inject a raw internal message directly.
Control endpoints (acton_*) are unauthenticated and intended for local development only. Do not expose the localnet server on a public network interface.

​
Fork mode

Fork mode lets you develop against real deployed contract state without querying a live public RPC for every transaction. When a fork is enabled, Acton pulls unknown account state from the remote network on first access and caches it locally for the session. 
# Fork testnet at the current block
acton localnet start --fork-net testnet

# Fork testnet at a specific historical block (pins to that state)
acton localnet start --fork-net testnet --fork-block-number 55000000
When forking from a built-in network, set TONCENTER_TESTNET_API_KEY or TONCENTER_MAINNET_API_KEY in your environment or .env file to avoid rate-limit errors during fork resolution.

​
Persistence

acton localnet start --db-path build/localnet.db
State is stored in a SQLite database and survives process restarts. Use this for long-running development sessions where you want deployed contracts to persist.

​
Auto-funded startup accounts

The --accounts flag (or [localnet].accounts in Acton.toml) automatically deploys and funds the named wallets from wallets.toml when the node starts. This eliminates the manual airdrop step for common development wallets: 
acton localnet start --accounts deployer,user
Acton.toml
[localnet]
accounts = ["deployer", "user"]

​
Examples

acton localnet start

​
Exit status

  • 0 — the selected subcommand completed successfully; for status, this includes the port not running (check the running field in --json output for automation)
  • 1 — startup failed because of port binding, state loading, fork initialization, faucet handling, or a control query failure

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us