Skip to main content
gen client exposes the read-side of the network: every JSON-RPC query method has a matching subcommand. This page covers the pure read commands. For balance and transfer commands that move tokens, see Sending transfers. For activation build/sign/submit and tracing, see Working with activations. All gen client commands accept the global --rpc-url <URL> (-s), --header <NAME=VALUE>, and --json (-j) flags. JSON mode emits a single envelope: 
{
  "ok": true,
  "command": "<name>",
  "timestamp": "2026-05-27T13:19:36.051512Z",
  "result": { /* command-specific */ }
}
On failure, ok is false, a code field is set (for example TransportError), and error carries the message. Use --json for any scripted consumption; text mode is for humans.

​
Accounts

​
gen client get-account

Fetch the components installed on an account and its owner. 
gen client get-account --account grd@1snr7fek9...
Required flags:
  • --account <ACCOUNT>: bech32m GvmAccount (grd@ HRP).
The result lists each component (header, contract, index, version) attached to the account. An account that has never been used returns an error: only accounts that have been bootstrapped (typically by a faucet call) exist on chain. See Entities and accounts for the model.

​
Balances (read-only)

gen client balance and gen client balances are documented with the rest of the balance and transfer surface in Sending transfers. They are listed here for completeness:
  • gen client balance queries a single token contract for a wallet or account.
  • gen client balances returns every routed balance for a wallet or account.
Both accept --wallet <NAME> (a local wallet) or --account <ACCOUNT> (any on-chain account). If neither is supplied, the active wallet is used.

​
Blocks

​
gen client get-current-block-index

Return the latest finalized block index known to the RPC unit. Useful for picking a valid_until_block when building activations. 
gen client get-current-block-index

{
  "ok": true,
  "command": "get-current-block-index",
  "result": { "block_index": "8576536" }
}
The block index is serialized as a decimal string to preserve u64 precision in JSON.

​
gen client get-block

Return the aggregated closed block at a given index. 
gen client get-block --block-index 8576500
Required flags:
  • --block-index <INDEX>: block index as a decimal integer.
The result includes the block’s order events: per-activation start/end markers with the activation ID, target entity, and Lamport timestamp. Use this to reconstruct execution order within a block.

​
Contracts

​
gen client get-contract

Return contract metadata and all component ABIs for a deployed contract. 
gen client get-contract --contract grd@1...
Required flags:
  • --contract <CONTRACT>: deployed contract identifier (bech32m, grd@ HRP). This is the identifier printed by gen client deploy.

​
gen client get-abi-by-contract-id

Return only the ABIs (no metadata) for a deployed contract. Useful when you just need to look up function signatures. 
gen client get-abi-by-contract-id --contract grd@1...
gen client get-abi-by-contract-id --contract grd@1... --output-file ./contract-abis.json
Required flags:
  • --contract <CONTRACT>: deployed contract identifier.
Optional flags:
  • --output-file <PATH>: write the pretty-printed ABI JSON to a file. Without --json, stdout shows only a confirmation line instead of dumping the full ABI; with --json, the ABI is in both stdout and the file.

​
gen client get-abi-by-contract-code-id

Same shape as get-abi-by-contract-id, but takes a contract code ID, not a deployed contract ID. This is the identifier returned by gen client push before you deploy. 
gen client get-abi-by-contract-code-id --contract-code-id grd@1...
Required flags:
  • --contract-code-id <CONTRACT_CODE_ID>: code ID from push output.
Accepts the same --output-file flag as get-abi-by-contract-id.

​
Components

​
gen client get-component

Return the ABI and owner for a single component instance on a specific entity. 
gen client get-component --gvm-component-id grd@<entity+index>,grd@<contract>
Required flags:
  • --gvm-component-id <COMPONENT_ID>: the component ID. Short form is two comma-separated bech32m parts (grd@<entity+index>,grd@<contract>); full form is four parts (grd@<entity+index>,grd@<contract>,grd@<contract_code_id>,grd@<component_type_index>).
The short form is what you will pass everywhere else (for view, build-activation, get-storage-at). The full form pins a specific contract code and component type; use it when you need to disambiguate versions.

​
gen client view

Execute a read-only call against a component. No state changes; no signature required. 
gen client view \
  --component-id grd@<entity+index>,grd@<contract> \
  --method balance_of \
  --params '{"holder": "grd@..."}'
Required flags:
  • --component-id <COMPONENT_ID>: target component ID (short or full form, as for get-component).
  • --method <METHOD>: contract method name.
Optional flags:
  • --params <JSON_OBJECT>: method parameters as a JSON object keyed by parameter name.
view is the read counterpart to build-activation + submit-activation: the parameter encoding is identical, but no activation is built and no signature is required.

​
gen client get-storage-at

Return the raw storage value for a component at a specific 32-byte key. 
gen client get-storage-at \
  --gvm-component-id grd@<entity+index>,grd@<contract> \
  --storage-key 0x<64 hex chars>
Required flags:
  • --gvm-component-id <COMPONENT_ID>: target component ID.
  • --storage-key <KEY>: 32-byte storage key as 0x-prefixed hex (64 characters).
The result is base64-encoded raw bytes, or null if the key is unset. This is a low-level escape hatch: prefer view against a contract method when one exists.

​
Traces

​
gen client get-trace

Return every activation ID that participated in a trace. A trace groups the original activation with every continuation it produced across entities. See Traces for the concept. 
gen client get-trace --trace-id 0x<128 hex chars>
Required flags:
  • --trace-id <0x...>: trace ID (128 hex characters, 0x-prefixed).
For the activation detail itself (status, gas used, events), follow up with gen client get-activation --activation-id <id> on each ID. See Working with activations for the full pattern.

​
Output formatting for scripts

Use --json and pipe through jq for any non-interactive use. The envelope shape is stable across commands, so the same script pattern works everywhere: 
RPC_URL=$(gen config show | grep rpc_url | awk '{print $2}')
BLOCK=$(gen client --json get-current-block-index | jq -r .result.block_index)
echo "current finalized block: $BLOCK"
For non-JSON output the format is human-targeted and may change between releases. Do not parse it from scripts.

​
See also