Skip to main content
This page is the reference for the CLI commands that move tokens, query balances, and pull funds from the faucet. For wallet lifecycle commands (create, import, export, set-active) see gen wallet.
Recipients are grd@... account locators. Every --to and --account flag on this page expects a 1-part bech32m account locator with the grd@ HRP. Raw 0x... entity hex is rejected. To get the locator for a wallet you control, run gen wallet show <name> --account-address-only. See gen wallet for the full wallet surface.
All gen client commands accept the global --rpc-url <URL> (-s), --header NAME=VALUE, and --json (-j) options. JSON mode emits a single envelope with ok, command, timestamp, and result.

​
Balances

​
gen wallet balance

Query the GEN balance (or a selected token) for the active or named wallet. 
gen wallet balance                               # active wallet, GEN
gen wallet balance alice                         # named wallet, GEN
gen wallet balance alice --token-contract grd@...
Key flags:
  • --token-contract <GVM_CONTRACT>: query a non-default token; defaults to the genesis GEN token.
Text output prints Balance, Symbol, and Name.

​
gen wallet balances

Query every token balance held by the active or named wallet in one call. 
gen wallet balances
gen wallet balances alice
gen wallet --json balances alice
Text output prints one block per token contract. JSON output is a map keyed by token contract string with balance, symbol, and name per entry.

​
gen client balance

Query the GEN balance (or a selected token) for any account on the network, not just one of your local wallets. 
gen client balance --account grd@1qyqqqqqj6jdqp...
gen client balance --wallet alice
gen client balance --account grd@... --token-contract grd@...
Key flags:
  • --account <ACCOUNT>: grd@... locator of any account.
  • --wallet <NAME>: query a named local wallet’s account instead of --account.
  • --token-contract <GVM_CONTRACT>: query a non-default token.
If neither --account nor --wallet is supplied, the active wallet is used. Output mirrors gen wallet balance.

​
Transfers

​
gen wallet transfer

Send tokens from a local wallet to a recipient account. The active wallet is used unless --wallet is supplied; transfers prompt for confirmation unless --yes is passed. 
gen wallet transfer --to grd@... --amount 1000
gen wallet transfer --wallet alice --to grd@... --amount 1000 --yes
gen wallet transfer --wallet alice --to grd@... --amount 1000 --token-contract grd@... --yes
gen wallet transfer --wallet alice --to grd@... --amount 1000 --with-confirmation --no-wait --yes
Key flags:
  • --to <RECIPIENT>: recipient grd@... locator (required).
  • --amount <SUBUNITS>: amount in token subunits, decimal string (required).
  • --wallet <NAME>: source wallet; defaults to the active wallet.
  • --token-contract <GVM_CONTRACT>: non-default token contract; must expose the holder transfer ABI.
  • --with-confirmation: wait for the receiving holder callback instead of fire-and-forget.
  • --no-wait: return after the validator acknowledges the submission.
  • --yes: skip the confirmation prompt; required for non-interactive use and --json.
Text output reports the activation ID and final status after waiting (or just the activation ID with --no-wait). In --json mode the result is the same envelope used across the CLI: 
{
  "ok": true,
  "command": "transfer",
  "timestamp": "2026-03-04T14:18:32.202539Z",
  "result": {
    "activation_id": "0x57dfbf81...aff3",
    "status": "success"
  }
}
A fresh random activation tag is generated for each submission, so repeating an identical transfer does not trip duplicate-activation replay protection.

​
gen client transfer

Lower-level alternative to gen wallet transfer. Same on-chain effect, but --wallet <NAME> is required (there is no implicit active-wallet fallback) and there is no interactive confirmation prompt. 
gen client transfer --wallet alice --to grd@... --amount 1000
gen client transfer --wallet alice --to grd@... --amount 1000 --token-contract grd@...
gen client transfer --wallet alice --to grd@... --amount 1000 --with-confirmation
Key flags:
  • --wallet <NAME>: source wallet (required; the account is debited and the wallet signs).
  • --to <RECIPIENT>: recipient grd@... locator (required).
  • --amount <SUBUNITS>: amount in token subunits (required).
  • --token-contract <GVM_CONTRACT>: non-default token contract.
  • --with-confirmation: wait for the receive callback.
  • --no-wait: return after submission.
Use this form for scripts and CI where an interactive --yes prompt is not appropriate.

​
Faucet

The faucet signs the activation; you supply the recipient. If the recipient account does not exist, the funded path auto-creates it via the FT contract’s receive-failure callback.

​
gen wallet faucet

Request faucet funds for, or simply create, an account. Defaults to the active wallet’s account when no recipient flag is set. 
gen wallet faucet --amount 1000000000           # fund active wallet
gen wallet faucet --wallet alice --amount 1000  # fund named wallet
gen wallet faucet --to grd@... --amount 1000    # fund explicit recipient
gen wallet faucet --create-account-only         # bootstrap active wallet's account, no funds
Key flags:
  • --amount <SUBUNITS>: amount to send from the faucet (must be > 0). Mutually exclusive with --create-account-only.
  • --create-account-only: submit a bare account-creation activation; no funds.
  • --to <RECIPIENT>: explicit recipient grd@... locator.
  • --wallet <NAME>: fund the named wallet’s account. Mutually exclusive with --to.
  • --token-contract <GVM_CONTRACT>: non-default token contract; funded path only.
  • --without-confirmation: use fire-and-forget transfer instead of transfer_with_confirmation (the default).
  • --no-wait: return after submission.
Text output reports the activation ID and final status.

​
gen client faucet

Same implementation and flags as gen wallet faucet. Use whichever subcommand fits the rest of your script. 
gen client faucet --to grd@... --create-account-only
gen client faucet --wallet alice --create-account-only
gen client faucet --to grd@... --amount 1000000
gen client faucet --to grd@... --amount 1000 --no-wait
If you use --no-wait, follow up with gen client get-activation --activation-id <id> to verify the final status.

​
Common patterns

  • Sign offline, submit elsewhere. Build the canonical unsigned bytes once with gen wallet build-activation, sign on an isolated host with gen wallet sign-activation (or gen client sign-activation), then push the signed bytes from anywhere with gen client submit-activation --signed-activation-file ./signed.txt. The same wallet that built the activation must sign it.
  • Dry-run before submitting. Pass the unsigned activation produced by build-activation to gen client simulate-activation to dry-run against current (or a specific) state without broadcasting. Useful for verifying transfer parameters and gas before spending. See Activations.
  • Submit and poll. Add --no-wait to any transfer or faucet command to return as soon as the validator acknowledges the request; the response includes the activation_id. Confirm the final outcome later with gen client get-activation --activation-id <id>.
  • Make repeated identical submissions unique. Transfer and funded-faucet submissions generate a fresh activation tag automatically. For the detached flow, pass --activation-tag <U32> to sign-activation or sign-and-submit-activation to override it manually.

​
See also

  • Wallet management: create, import, export, and select wallets.
  • Activations: build-activation, simulate-activation, sign-activation, submit-activation, and get-activation.
  • Quickstart: end-to-end first transfer in five minutes.