Wallet management

Use acton wallet to create, import, inspect, fund, export, sign with, and remove wallets used by Acton workflows. For the full command surface and every flag, see the acton wallet reference.

Create a wallet

Create a new wallet when a project needs a fresh mnemonic:

acton wallet new --name deployer --local

Use --local to store the wallet in the current project's wallets.toml. Use --global to store it in global.wallets.toml and reuse it across projects:

acton wallet new --name shared --global

If --name or --version is omitted, Acton prompts for them. Common wallet versions include v5r1, v4r2, and v3r2.

By default, Acton prefers secure native storage for the mnemonic when the system keyring is available. To require secure storage explicitly, pass --secure true. To force plain-text storage, pass --secure false.

Import an existing wallet

Import a wallet when the mnemonic already exists:

acton wallet import --name deployer --local "word1 word2 ... word24"

For interactive import, omit the mnemonic:

acton wallet import

acton wallet import follows the same storage rules as acton wallet new: local or global placement, interactive prompts when flags are omitted, and secure storage when available.

Inspect configured wallets

List all configured wallets:

acton wallet list

Check testnet balances as well:

acton wallet list --balance

Acton merges wallet definitions from global.wallets.toml first and then from local wallets.toml. If both files define the same wallet name, the local entry wins.

Fund a wallet on testnet

New wallets start with zero balance. To request testnet GRAM, use the faucet provided by Acton. It works by performing a small cryptographic computation locally on device and confirming it with the remote endpoint.

Acton faucet is limited to 2 requests of 2 testnet GRAM per hour for a single IP, device, and wallet.

Add --airdrop to request testnet GRAM during creation:

acton wallet new --name deployer --local --airdrop

Use the airdrop subcommand to request testnet GRAM later for an existing wallet:

acton wallet airdrop deployer --net testnet

Skip the post-airdrop balance wait after a successful faucet airdrop request:

acton wallet airdrop deployer --net testnet --no-wait-airdrop

If the wallet name is omitted, Acton auto-selects the wallet only when exactly one wallet is configured. Otherwise, it interactively prompts.

Export a mnemonic

Export a configured wallet mnemonic when it must be moved into another tool:

acton wallet export-mnemonic deployer

This command is interactive-only and asks for confirmation before revealing the mnemonic.

Remove a wallet

Remove a wallet from configuration when it is no longer needed:

acton wallet remove deployer

For non-interactive use, add -y:

acton wallet remove deployer -y

If the wallet uses keyring storage, Acton also removes the mnemonic from the secure store. If the wallet points to an environment variable or external file, Acton removes only the wallet entry.

Use a configured wallet in scripts

Resolve a configured wallet by name from a script:

import "@acton/emulation/scripts"
import "@acton/io"
import "@acton/prompts"

fun main() {
    val deployer = scripts.wallet(promptWallet("Select a wallet:"));
    println("Deployer address: {}", deployer.address);
}

Run the script with a real network to use the configured wallet:

acton script deploy.tolk --net testnet

Without --net, scripts.wallet() creates a local test wallet with the same name. This makes it easy to exercise the script logic before broadcasting.

To use a wallet from an external wallet service such as Tonkeeper, pass --tonconnect together with --net to connect to it through the TON Connect protocol. In this mode, promptWallet() returns tonconnect, and scripts.wallet(...) resolves to the connected wallet address instead of opening local wallet keys:

acton script deploy.tolk --net testnet --tonconnect

Choose local or global storage

Use local wallets for project-specific work and global wallets for identities shared across projects.

• Local wallets live in wallets.toml in the project root.
• Global wallets live in ~/.config/acton/wallets/global.wallets.toml.
• Local entries override global entries with the same name.

When a project already has access to global wallets, Acton places the global.wallets.toml symlink in the project root.

Choose how to store the mnemonic

Acton supports four mnemonic sources. If more than one is present, Acton resolves them in this order: mnemonic-env, mnemonic-file, mnemonic-keyring, mnemonic.

Secure native storage is the preferred option for local development:

[wallets.deployer]
kind = "v5r1"
workchain = 0
keys = { mnemonic-keyring = "my-project:deployer" }

Use an environment variable when the mnemonic must stay outside the config file:

[wallets.deployer]
kind = "v5r1"
keys = { mnemonic-env = "DEPLOYER_MNEMONIC" }

export DEPLOYER_MNEMONIC="word1 word2 ... word24"

Use a file reference when secrets are managed separately:

[wallets.deployer]
kind = "v5r1"
keys = { mnemonic-file = ".secrets/deployer.txt" }

Plain-text mnemonics are supported, but only for development scenarios where that tradeoff is acceptable:

[wallets.deployer]
kind = "v5r1"
keys = { mnemonic = "word1 word2 ... word24" }

Add address safety checks

Expected addresses help catch wallet misconfiguration before real-network operations:

[wallets.deployer]
kind = "v5r1"
workchain = 0
keys = { mnemonic-keyring = "my-project:deployer" }

[wallets.deployer.expected]
address-testnet = "0QD36XRy1ISfSB8zmlSQKBsa5bmeixAWwD6vUUhOXXur8ZLd"

acton wallet new and acton wallet import populate expected.address-testnet automatically. Add address-mainnet manually when the same wallet is meant to be used on mainnet.

Keep wallet data out of version control

wallets.toml and global.wallets.toml can contain sensitive material directly, or indirect references to secrets. Acton adds these files to .gitignore, but secret hygiene still matters:

• Prefer mnemonic-keyring for local development.
• Prefer mnemonic-env or mnemonic-file when plain-text config is not acceptable.
• Avoid reusing the same wallet for unrelated environments.
• Test scripts locally before using --net testnet or --net mainnet.

Sign an external message body

Message bodies composed outside of Acton workflows can be signed via acton wallet sign without writing a script:

acton wallet sign deployer --body <HEX_OR_BASE64_BOC>

When --body is omitted, Acton reads from the standard input if input is piped, or prompts interactively otherwise:

cat body.boc.base64 | acton wallet sign deployer

BoC data in Base64 and hex formats always starts with the same sequence of characters, so Acton auto-detects hex and Base64 input, and prints the signed external-body BoC in hex by default.