Skip to main content
This page is for ATOM holders who use gaiad instead of a wallet: custodians, Ledger users, and anyone scripting transactions. It assumes gaiad v28.3.1 is installed (Installation). You do not need a node of your own. At the end you can build, sign, and broadcast every delegator transaction, alone or as a multisig signer. Nothing here involves validator keys. The keys this page creates are wallet keys (secp256k1, derived from a recovery phrase). A validator’s consensus key and operator key are separate. They are covered under Validator setup.

​
Point gaiad at the Hub

Client defaults for gaiad are stored in ~/.gaia/config/client.toml. Set them once so every command below needs fewer flags:
Any public remote procedure call (RPC) endpoint from the chain registry works for node. Use your own node’s address if you run one. The same settings can be given per command as --chain-id, --node, and --keyring-backend. They can also be set as environment variables with the GAIAD_ prefix, for example GAIAD_KEYRING_BACKEND=os.

​
Keys

Create a key. The command prints the address and a 24 word recovery phrase once. Write the phrase down offline.
Recover an existing phrase, or add a Ledger key (the Cosmos app must be open on the device; see Ledger):
Both derive the first account at m/44'/118'/0'/0/0. Other accounts from the same phrase use --account and --index. See HD wallets. List keys and show the address forms:
The -a flag prints the cosmos1... address, and -p prints the public key JSON. The same key also has a cosmosvaloper1... form (--bech val). That form only matters if this key creates a validator. Keyring backends: os uses the operating system keychain, file an encrypted file under ~/.gaia, test an unencrypted file for devnets. Never keep real funds under test. Details: Keyring.

​
Fees under the fee market

The Hub prices gas with a fee market. The floor is 0.005 uatom per gas, and it rises when blocks are full. A transaction with a hardcoded fee can therefore be rejected on a busy day. Query the current price before sending, and pass it as --gas-prices:
Every transaction on this page uses --gas auto --gas-adjustment 1.5 --gas-prices 0.005uatom. The --gas auto flag simulates the transaction to estimate gas. The --gas-adjustment 1.5 flag adds headroom. The fee is gas times price. A delegation at the floor costs about 0.001 ATOM. Replace 0.005uatom with the queried price when it is higher. The module is described on Fee market.

​
Check balances and delegations

The first lists spendable coins by denom (uatom, 1 ATOM = 1,000,000 uatom). The second lists each delegation with shares and balance. The third lists accrued rewards per validator and the total.

​
Delegate

Choose a validator with the criteria on the Delegator FAQ. Validators are listed by gaiad q staking validators --page-limit 200 and on explorers. Then:
The command prints the transaction, asks for confirmation, and returns a txhash. The delegation appears in gaiad q staking delegations once the transaction is in a block (about six seconds). Delegating again to the same validator adds to the existing delegation.

​
Redelegate

Redelegating moves stake from one validator to another without unbonding. It takes effect at once. The moved stake cannot be redelegated again for 21 days.
Up to seven redelegations from the same pair can be in flight at once (max_entries: 7).

​
Unbond and cancel an unbonding

Unbonding returns ATOM to the spendable balance after 21 days. During that time it earns nothing. It also remains slashable for faults the validator committed while it was bonded.
The query shows each entry with its completion_time and creation_height. An entry can be cancelled before completion, which re-bonds the ATOM to the same validator:

​
Withdraw rewards

Rewards are not paid automatically. Withdraw from all validators at once, or from one:
Rewards land in the spendable balance. Delegate them again to compound. To have rewards paid to another address (a cold address, for example), set a withdraw address once:

​
Vote

Voting needs at least 1 ATOM staked from the voting address. List proposals in their voting period, read one, and vote:
Options are yes, no, abstain, and no_with_veto. A delegator’s vote overrides their validators’ votes for their share of stake. A vote can be split:
What each option means for the outcome is on Governance process.

​
Send ATOM

The first argument is the sender key name or address. The second is the recipient. A --memo is needed only when sending to an exchange that asks for one.

​
Offline signing

Keep the key on a machine without network access. Move only transaction files. The flow has three steps and three machines or directories: build (online), sign (offline), broadcast (online).
  1. Build an unsigned transaction on the online machine. Gas has to be given explicitly since auto needs a node at signing time:
Note the account number and sequence. The offline machine cannot look them up. On the Hub, q auth account returns the account wrapped in .account.value for base accounts.
  1. Sign on the offline machine:
The validate-signatures command prints each signer with [OK].
  1. Broadcast from the online machine:
The output has code: 0 on success and a txhash to look up with gaiad q tx <hash>. A sequence mismatch error means another transaction from the same address went through between build and broadcast. Rebuild with the new sequence.

​
Multisig accounts

A multisig address is derived from several public keys and a threshold. The Hub needs the key material of each member only when they sign. Create it on every signer’s machine from the members’ public keys (gaiad keys show <name> -p on the member’s machine, imported with gaiad keys add <name> --pubkey '<json>'):
The keys show command reports type: multi and the same cosmos1... address on every machine that holds the same three public keys in the same order. The --nosort flag controls ordering if a member list was created unsorted elsewhere. The cosmos1... address must be funded like any other before it can transact. Spending from it:
Each signer signs with --multisig naming the multisig account, producing a signature file:
Combine the threshold number of signatures and broadcast:
The command multisign is an alias for multi-sign. The Hub limits a transaction to seven signatures (tx_sig_limit: 7 in gaiad q auth params). A multisig therefore cannot have more than seven members. Delegations, votes, and reward withdrawals from the multisig use the same build, sign, combine, broadcast steps with the respective tx command.

​
Verify

After any transaction:
A result of code: 0 means it executed. A non-zero code comes with the reason in raw_log (insufficient fee, wrong sequence, validator not found). Then confirm the state change with the matching query: q staking delegations after delegating or redelegating, q staking unbonding-delegations after unbonding, q bank balances after a withdrawal or send, and gaiad q gov vote <id> <address> after voting.

​
Next