Docs
Command reference

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 TON Center
  • call contract get-methods with ABI-parsed or raw TVM stack arguments
  • check whether an account is active, frozen, or uninitialized
  • inspect balance, last transaction metadata, and state hashes
  • render a TON Center v3 trace as a decoded transaction tree
  • match deployed code against a local Acton project by code_hash
  • decode account storage and get-method results through local, bundled, or verifier ABI metadata when a match is found

For one-off inspection, rpc info and rpc call also accept --abi. The path can point to compiler ABI JSON emitted by acton build or acton compile, or to a .tolk interface file such as contract.types.tolk. An explicit ABI has priority over code-hash matching.

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. If no local match exists, Acton falls back to the bundled ABI catalog and then the TON verifier API. Successful verifier ABI responses are cached in build/cache/verifier-abi for 24 hours. If the verifier is unavailable, an expired cache entry is still used when available. Set ACTON_VERIFY_BACKEND to override the verifier backend, for example when running the verifier locally.

Subcommands

acton rpc info

Show information about a single account.

Synopsis

acton rpc info [options] address

Options

<address>

Contract address in friendly or raw format.

--abi<path>

Use compiler ABI JSON or a Tolk ABI source instead of automatic ABI matching. Tolk sources are compiled with entrypoints disabled, so standalone *.types.tolk interface files are accepted.

--net<network>

Network to query.

Default:

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
  • ABI match information when a project contract, bundled catalog entry, or verifier response has the same code_hash
  • decoded storage in a YAML-like view when compiler ABI metadata is available

If no ABI match is found, Acton still prints the raw remote account information and reports that decoded storage is unavailable.

acton rpc call

Call a contract get-method through TON Center.

Synopsis

acton rpc call [options] address method [args...]

Options

<address>

Contract address in friendly or raw format.

<method>

Get-method name or numeric TVM method id.

<args>

Arguments to pass to the get-method.

Repeatable:

May be passed multiple times.

--abi<path>

Use compiler ABI JSON or a Tolk ABI source instead of automatic ABI matching. The explicit ABI controls method lookup, argument parsing, result decoding, field comments, and custom exit-code descriptions.

--net<network>

Network to query.

Default:

testnet.

Supported values include mainnet, testnet, localnet, and custom:<name>.

--json

Print machine-readable JSON output.

--with-comments

Include field comments from ABI metadata in the result. In JSON mode, a described field is returned as an object with value and comment keys. In the default human-readable mode, the comment is printed on the line before the field value.

Conflicts with:

--raw

--raw

Print the raw TON Center stack without ABI decoding.

Conflicts with:

--with-comments

ABI Arguments

When --abi is provided, Acton loads that file before making the RPC request and uses it without comparing the remote code hash. Otherwise, Acton searches local, bundled, and verifier ABI metadata for the remote contract. Get-method arguments are parsed against the selected ABI.

Accepted explicit ABI formats are:

  • compiler ABI JSON, including files emitted under build/abi
  • .tolk source or interface files, including *.types.tolk; these are compiled with no contract entrypoint requirement

The method argument can be either an ABI get-method name or a numeric TVM method id. When the numeric id is present in the ABI, Acton still uses ABI metadata for arguments and result decoding. When the numeric id is not present in the ABI, Acton sends the call as a raw get-method request.

  • integers use Tolk integer literal syntax such as 42, -1, 0xff, and 0b1010
  • bool accepts true and false
  • nullable supported types accept null
  • cell, slice, and bitsN accept plain BoC hex without C{} or CS{} prefixes
  • any_address accepts an internal address or the addr_none literal
  • arrays accept [item1, item2]

Unsupported ABI argument types currently include structs, shaped tuples, maps, dictionaries, builders, continuations, and other complex values.

Without ABI metadata, acton rpc call builds a raw stack from CLI arguments. Raw arguments support Tolk integer literals, true, false, null, internal addresses, addr_none, plain BoC hex as cell, and explicit cell:, slice:, builder:, and string: prefixes.

Output

When ABI metadata is available and the result stack width matches the get-method return type, Acton prints the decoded Tolk value. Otherwise it prints the raw TON Center stack in a compact field-per-line format.

Raw output uses decimal integers, URL-friendly addresses, addr_none for two-bit none addresses, and one fieldN: type = value line per stack item.

acton rpc block

Print the latest masterchain block info returned by TON Center.

Synopsis

acton rpc block [options]

Options

--net<network>

Network to query.

Default:

testnet.

Supported values include mainnet, testnet, localnet, and custom:<name>.

Output

acton rpc block prints the full TON Center 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

--net<network>

Network to query.

Default:

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 TON Center v3 trace by root transaction hash and render it in a stable text format.

Synopsis

acton rpc trace [options] hash

Options

<hash>

Root transaction hash to query through TON Center v3 /traces.

--net<network>

Network to query.

Default:

testnet.

Supported values include mainnet, testnet, localnet, and custom:<name>.

--summary

Print only the trace summary.

Conflicts with:

--tree, --verbose

--tree

Print the trace summary and transaction tree. This is the default mode.

Conflicts with:

--summary, --verbose

--verbose

Print the summary, tree, and stable per-transaction fields.

Conflicts with:

--summary, --tree

--show-bodies

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, bundled catalog entry, or verifier response, Acton prints the matched contract name. Add --show-bodies to print decoded inbound message bodies.

Display Options

--color<when>

Control when to use colored output.

Possible values:

auto, always, never

Default:

auto

Project Options

--manifest-path<path>
Pass-through:

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.

Conflicts with:

--project-root

--project-root<path>
Pass-through:

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.

Conflicts with:

--manifest-path

Network Resolution

  • mainnet and testnet use the built-in TON Center endpoints
  • localnet uses the configured localnet or its default URL
  • custom:<name> resolves through [networks.<name>] in Acton.toml

For custom:<name>, Acton needs access to the selected project or manifest so it can read the custom network configuration.

TON Center 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, get-method argument parsing, and get-method result decoding are best-effort and depend on local project context, the bundled ABI catalog, or the verifier API.

Acton attempts to:

  1. use --abi directly when it is provided to rpc info or rpc call
  2. otherwise fetch the remote account code cell
  3. compute its code_hash
  4. compare that hash with locally configured contracts
  5. fall back to the bundled ABI catalog when there is no local ABI
  6. query the verifier API when no local or bundled ABI matches
  7. cache successful verifier responses for 24 hours and use stale entries during verifier outages
  8. decode storage and get-method results with the selected compiler ABI

This means decoding is robust for contracts you control in the current Acton project, available for known third-party deployments in the bundled catalog, and extendable to verified deployments through the verifier API.

For acton rpc call, missing ABI metadata does not prevent a get-method call. Acton sends raw stack arguments instead and prints the raw result stack.

Exit Status

  • 0: The selected RPC query completed successfully.
  • 1: The address was invalid, the network could not be resolved, the remote request failed, an explicit ABI could not be read, parsed, or compiled, raw or ABI argument parsing failed, a named get-method was not found in ABI metadata, or the get-method returned a non-zero exit code.

Examples

  1. Inspect a testnet account quickly:

    acton rpc info EQC...

  2. Inspect a mainnet account with an API key from the environment:

    TONCENTER_MAINNET_API_KEY=your-key acton rpc info EQC... --net mainnet

  3. Inspect a localnet deployment and decode storage with the current project:

    acton rpc info EQC... --net localnet

  4. Decode account storage with an explicit Tolk interface:

    acton rpc info EQC... --abi contracts/Counter.types.tolk --net mainnet

  5. Call a get-method with an explicit compiler ABI JSON file:

    acton rpc call EQC... get_wallet_data --abi build/abi/counter.json --net mainnet

  6. Call a get-method with automatically matched ABI metadata:

    acton rpc call EQC... get_wallet_data --net mainnet

  7. Call a get-method by numeric TVM method id:

    acton rpc call EQC... 85143 --net mainnet

  8. Call a get-method without ABI metadata by passing raw stack arguments:

    acton rpc call EQC... 85143 0xff true cell:B5EE9C... --net mainnet

  9. Pass addr_none to an any_address get-method argument:

    acton rpc call EQC... accepts_any_address addr_none --net localnet

  10. Use a custom network defined in another manifest:

acton --manifest-path ../incident/Acton.toml rpc info EQC... --net custom:staging
  1. Print the latest mainnet masterchain block JSON:
acton rpc block --net mainnet
  1. Print the latest mainnet masterchain block number:
acton rpc block-number --net mainnet
  1. Print a transaction trace from localnet:
acton rpc trace <tx-hash> --net localnet

See Also

Last updated on

acton wallet

Reference manual for the acton wallet command

acton verify

Reference manual for the acton verify command

On this page

Synopsis
Description
Subcommands
acton rpc info
Synopsis
Options
Output
acton rpc call
Synopsis
Options
ABI Arguments
Output
acton rpc block
Synopsis
Options
Output
acton rpc block-number
Synopsis
Options
Output
acton rpc trace
Synopsis
Options
Output
Display Options
Project Options
Network Resolution
TON Center API Keys
ABI Matching
Exit Status
Examples
See Also