Sending transfers

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:

[NAME] (positional): Wallet to act on; defaults to the active wallet.
--wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
--token-contract <GVM_CONTRACT>: Query a specific token contract instead of the default 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:

--wallet <NAME>: Use a specific wallet instead of the active wallet.
--account <ACCOUNT>: Query the token balance for a specific GvmAccount (bech32m, HRP grd@) instead of a wallet.
--token-contract <GVM_CONTRACT>: Query a specific token contract instead of the default GEN 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:

--wallet <NAME>: Use a specific wallet instead of the active wallet.
--to <RECIPIENT>: Recipient GvmAccount in bech32m format (HRP grd@) (required).
--amount <SUBUNITS>: Token amount in subunits (u128 decimal string) (required).
--token-contract <GVM_CONTRACT>: Deployed token contract in bech32m format. Must resolve to the genesis fungible-token code ID (the genesis GEN contract); other code IDs are rejected.
--with-confirmation: Ask the remote holder to confirm transfer delivery before returning.
--no-wait: Return immediately after sending without waiting for the activation to complete.
--yes (-y): Skip the interactive transfer confirmation prompt.

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": "wallet-transfer",
  "timestamp": "2026-03-04T14:18:32.202539Z",
  "result": {
    "activation_id": "0x57dfbf81...aff3",
    "token_contract": "grd@...",
    "sender_account": "grd@...",
    "recipient_account": "grd@...",
    "amount": "1000",
    "status": "success"
  }
}

status and outcome_result are present only once the activation resolves (omitted with --no-wait). 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 with the same on-chain effect and the same wallet resolution: --wallet is optional and falls back to the active wallet. Like gen wallet transfer, it prompts for confirmation, so pass --yes for non-interactive use; in --json or other non-interactive contexts it errors without --yes rather than prompting.

gen client transfer --to grd@... --amount 1000 --yes                        # active wallet
gen client transfer --wallet alice --to grd@... --amount 1000 --yes
gen client transfer --wallet alice --to grd@... --amount 1000 --token-contract grd@... --yes
gen client transfer --wallet alice --to grd@... --amount 1000 --with-confirmation --yes

Key flags:

--wallet <NAME>: Use a specific wallet instead of the active wallet.
--to <RECIPIENT>: Recipient GvmAccount in bech32m format (HRP grd@) (required).
--amount <SUBUNITS>: Token amount in subunits (u128 decimal string) (required).
--token-contract <GVM_CONTRACT>: Deployed token contract in bech32m format. Must resolve to the genesis fungible-token code ID (the genesis GEN contract); other code IDs are rejected.
--with-confirmation: Ask the remote holder to confirm transfer delivery before returning.
--no-wait: Return immediately after sending without waiting for the activation to complete.
--yes (-y): Skip the interactive transfer confirmation prompt.

For scripts and CI, pass --yes so the command never blocks on (or errors at) the confirmation prompt.

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 Fungible Token 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

Pick the recipient with at most one of --wallet or --to; with neither, the active wallet’s account is used. Exactly one of --amount or --create-account-only is required, and the two are mutually exclusive. --create-account-only is the unfunded path: combining it with --amount, --token-contract, or --without-confirmation is rejected as an invalid argument combination, not silently ignored (--token-contract and --without-confirmation both require --amount). Key flags:

--wallet <NAME>: Use a specific wallet instead of the active wallet.
--to <RECIPIENT>: Recipient GvmAccount in bech32m format (HRP grd@).
--amount <SUBUNITS>: Amount in subunits to transfer from the faucet (must be > 0).
--create-account-only: Create the account without funding it.
--token-contract <GVM_CONTRACT>: Token contract for the funded path. Defaults to the genesis FT (GEN).
--without-confirmation: Use fire-and-forget transfer instead of transfer_with_confirmation (funded path only).
--no-wait: Return immediately after sending without waiting for the activation and its continuations to complete.

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.

RPC

SDK

Contracts

AI

CLI

Troubleshooting

Sending transfers

Balances

`gen wallet balance`

`gen wallet balances`

`gen client balance`

Transfers

`gen wallet transfer`

`gen client transfer`

Faucet

`gen wallet faucet`

`gen client faucet`

Common patterns

See also

​Balances

​gen wallet balance

​gen wallet balances

​gen client balance

​Transfers

​gen wallet transfer

​gen client transfer

​Faucet

​gen wallet faucet

​gen client faucet

​Common patterns

​See also

Balances

`gen wallet balance`

`gen wallet balances`

`gen client balance`

Transfers

`gen wallet transfer`

`gen client transfer`

Faucet

`gen wallet faucet`

`gen client faucet`

Common patterns

See also