acton rpc
Reference manual for the acton rpc command
Synopsis
acton rpc [options] command
Description
Query blockchain account state through a configured network endpoint.
acton rpc is intended for fast inspection workflows when you want to:
- fetch the latest masterchain block number for a network
- inspect the latest masterchain block object returned by TonCenter
- check whether an account is active, frozen, or uninitialized
- inspect balance, last transaction metadata, and state hashes
- render a TonCenter v3 trace as a decoded transaction tree
- match deployed code against a local Acton project by
code_hash - decode account storage through local ABI metadata when a match is found
The command works without a project manifest for raw remote inspection.
When Acton can resolve a local project and finds a contract with the same
compiled code_hash, it also prints the matched contract name and decodes the
account storage using the local compiler ABI.
Subcommands
acton rpc info
Show information about a single account.
Synopsis
acton rpc info [options] address
Options
Contract address in friendly or raw format.
Network to query.
testnet.
Supported values include mainnet, testnet, localnet, and
custom:<name>.
Output
acton rpc info prints:
- remote account metadata such as status, balance, last transaction LT and hashes
- code and data hashes when the account has deployed state
- local contract match information when a project contract has the same
code_hash - decoded storage in a YAML-like view when compiler ABI metadata is available
If no local ABI match is found, Acton still prints the raw remote account information and reports that decoded storage is unavailable.
acton rpc block
Print the latest masterchain block info returned by TonCenter.
Synopsis
acton rpc block [options]
Options
Network to query.
testnet.
Supported values include mainnet, testnet, localnet, and
custom:<name>.
Output
acton rpc block prints the full TonCenter getMasterchainInfo JSON response
for the selected network.
acton rpc block-number
Print the latest masterchain block number for a network.
Synopsis
acton rpc block-number [options]
Options
Network to query.
testnet.
Supported values include mainnet, testnet, localnet, and
custom:<name>.
Output
acton rpc block-number prints only the latest masterchain block seqno as a
decimal number.
acton rpc trace
Fetch a TonCenter v3 trace by root transaction hash and render it in a stable text format.
Synopsis
acton rpc trace [options] hash
Options
Root transaction hash to query through TonCenter v3 /traces.
Network to query.
testnet.
Supported values include mainnet, testnet, localnet, and
custom:<name>.
Print only the trace summary.
Print the trace summary and transaction tree. This is the default mode.
Print the summary, tree, and stable per-transaction fields.
Print decoded message bodies in the transaction tree.
Output
acton rpc trace prints a short summary first:
- query hash
- trace id
- root transaction hash
- whether the trace is complete
- total transaction and message counts
Tree and verbose modes then reuse the same transaction tree formatter as Acton
tests. When current account code matches a local contract in the project,
Acton prints local contract names through the local ABI. Add --show-bodies
to print decoded inbound message bodies.
Display Options
Control when to use colored output.
auto, always, never
Project Options
Accepted as a global Acton option for CLI consistency.
This command does not require an existing project manifest for its primary
workflow. It remains mutually exclusive with --project-root.
Accepted as a global Acton option for CLI consistency.
This command does not require an existing project root for its primary
workflow. It remains mutually exclusive with --manifest-path.
Network Resolution
mainnetandtestnetuse the built-in TonCenter endpointslocalnetuses the configured localnet or its default URLcustom:<name>resolves through[networks.<name>]inActon.toml
For custom:<name>, Acton needs access to the selected project or manifest so
it can read the custom network configuration.
TonCenter API Keys
Built-in mainnet/testnet requests read TONCENTER_MAINNET_API_KEY or
TONCENTER_TESTNET_API_KEY, depending on the selected network.
For custom:<name>, Acton reads <NORMALIZED_NAME>_API_KEY. Custom network
names are uppercased and non-alphanumeric characters are replaced with _, so
custom:mock becomes MOCK_API_KEY.
Acton loads .env automatically, so the simplest setup during project work is
usually to keep these keys there and use shell environment variables only for
one-off overrides or CI.
ABI Matching
Storage decoding is best-effort and depends on local project context.
Acton attempts to:
- fetch the remote account code cell
- compute its
code_hash - compare that hash with locally configured contracts
- decode storage with the matched contract's compiler ABI
This means decoding is robust for contracts you control in the current Acton project, but not guaranteed for arbitrary third-party deployments.
Exit Status
0: The selected RPC query completed successfully.1: The address was invalid, the network could not be resolved, the remote request failed, or local ABI decoding encountered an unrecoverable error.
Examples
-
Inspect a testnet account quickly:
acton rpc info EQC... -
Inspect a mainnet account with an API key from the environment:
TONCENTER_MAINNET_API_KEY=your-key acton rpc info EQC... --net mainnet -
Inspect a localnet deployment and decode storage with the current project:
acton rpc info EQC... --net localnet -
Use a custom network defined in another manifest:
acton --manifest-path ../incident/Acton.toml rpc info EQC... --net custom:staging -
Print the latest mainnet masterchain block JSON:
acton rpc block --net mainnet -
Print the latest mainnet masterchain block number:
acton rpc block-number --net mainnet -
Print a transaction trace from localnet:
acton rpc trace <tx-hash> --net localnet
See Also
acton help disasmacton help retraceacton help script- Command reference
Last updated on