Client queries

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...

--account <ACCOUNT>: GvmAccount in bech32m format (HRP grd@) (required).

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

--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...

--contract <CONTRACT>: Deployed contract identifier from deploy command output (bech32m format with ‘grd@’ prefix) (required).

`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

--contract <CONTRACT>: Deployed contract identifier from deploy command output (bech32m format with ‘grd@’ prefix) (required).
--output-file <PATH>: Write the pretty-printed ABI response JSON to a file. With —json, the ABI also remains in the JSON stdout output. Without —json, stdout shows only a confirmation line instead of the full ABI dump.

`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...

--contract-code-id <CONTRACT_CODE_ID>: Contract code ID from push command output (bech32m format with ‘grd@’ prefix) (required).
--output-file <PATH>: Write the pretty-printed ABI response JSON to a file. With —json, the ABI also remains in the JSON stdout output. Without —json, stdout shows only a confirmation line instead of the full ABI dump.

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>

--gvm-component-id <COMPONENT_ID>: GVM component ID (short: grd@<entity+index>,grd@<contract>; full: grd@<entity+index>,grd@<contract>,grd@<contract_code_id>,grd@<component_type_index>) (required).

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@..."}'

--component-id <COMPONENT_ID>: Target component ID (short: grd@<entity+index>,grd@<contract>; full: grd@<entity+index>,grd@<contract>,grd@<contract_code_id>,grd@<component_type_index>) (required).
--method <METHOD>: Contract method name to invoke (required).
--params <JSON_OBJECT>: Method parameters as JSON object with parameter names as keys.

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>

--gvm-component-id <COMPONENT_ID>: GVM component ID (short: grd@<entity+index>,grd@<contract>; full: grd@<entity+index>,grd@<contract>,grd@<contract_code_id>,grd@<component_type_index>) (required).
--storage-key <STORAGE_KEY>: Storage key as a 32-byte hex value with 0x prefix (required).

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>

--trace-id <TRACE_ID>: Trace ID (128 hex characters with 0x prefix) (required).

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.

RPC

SDK

Contracts

AI

CLI

Troubleshooting

Client queries

Accounts

`gen client get-account`

Balances (read-only)

Blocks

`gen client get-current-block-index`

`gen client get-block`

Contracts

`gen client get-contract`

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

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

Components

`gen client get-component`

`gen client view`

`gen client get-storage-at`

Traces

`gen client get-trace`

Output formatting for scripts

See also

​Accounts

​gen client get-account

​Balances (read-only)

​Blocks

​gen client get-current-block-index

​gen client get-block

​Contracts

​gen client get-contract

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

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

​Components

​gen client get-component

​gen client view

​gen client get-storage-at

​Traces

​gen client get-trace

​Output formatting for scripts

​See also

Accounts

`gen client get-account`

Balances (read-only)

Blocks

`gen client get-current-block-index`

`gen client get-block`

Contracts

`gen client get-contract`

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

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

Components

`gen client get-component`

`gen client view`

`gen client get-storage-at`

Traces

`gen client get-trace`

Output formatting for scripts

See also