Skip to main content

​
Key Management

The xyz keys commands manage cryptographic keypairs for signing transactions on XYZ Chain.

​
Commands

CommandDescription
xyz keys generateCreate a new keypair
xyz keys listList all stored keys
xyz keys importImport from mnemonic
xyz keys exportExport a keypair

​
Generate a New Key

Create a new keypair with a 24-word mnemonic: 
xyz keys generate <name>

​
Example

xyz keys generate mykey

Generated new keypair: mykey

Address: xyz1qwertyuiopasdfghjklzxcvbnm12345678

Mnemonic (save this securely):
abandon abandon abandon abandon abandon abandon abandon abandon
abandon abandon abandon abandon abandon abandon abandon abandon
abandon abandon abandon abandon abandon abandon abandon about

WARNING: Write down your mnemonic phrase and store it securely.
This is the only way to recover your account.
Save your mnemonic phrase immediately! It is only displayed once and cannot be recovered.

​
Options

FlagDescription
--keyring-backendOverride keyring backend
--homeOverride home directory

​
List Keys

View all stored keypairs: 
xyz keys list

​
Example Output

NAME      ADDRESS
mykey     xyz1qwertyuiopasdfghjklzxcvbnm12345678
alice     xyz1aliceaddress12345678901234567890
bob       xyz1bobaddress123456789012345678901234

​
Import a Key

Import an existing key from a mnemonic phrase: 
xyz keys import <name>

​
Interactive Mode

xyz keys import mykey
# Enter your 12 or 24 word mnemonic:

​
With Flag

xyz keys import mykey --mnemonic "word1 word2 word3 ... word12"

​
Validation

The CLI validates:
  • Mnemonic must be 12 or 24 words
  • Words must be valid BIP39 words
  • Checksum must be valid
xyz keys import test --mnemonic "invalid mnemonic phrase"
# Error: invalid mnemonic: word count must be 12 or 24

​
Export a Key

Export a keypair as armored ASCII: 
xyz keys export <name>

​
Example

xyz keys export mykey

Enter passphrase to encrypt the exported key:
Confirm passphrase:

-----BEGIN XYZ PRIVATE KEY-----
kdf: bcrypt
salt: ABC123DEF456...
type: secp256k1

base64EncodedEncryptedPrivateKey...
-----END XYZ PRIVATE KEY-----
The exported key is encrypted with the passphrase you provide. Import it on another machine with: 
# On the target machine
xyz keys import mykey --armor
# Paste the armored key

​
Key Derivation

XYZ Chain uses the following HD path: 
m/44'/118'/0'/0/0
ComponentValueMeaning
Purpose44’BIP44
Coin Type118’XYZ Chain
Account0’First account
Change0External chain
Index0First address
This ensures compatibility with:
  • Keplr wallet
  • Ledger
  • Other compatible wallets

​
Address Format

Generated addresses use the xyz prefix with Bech32 encoding: 
xyz1qwertyuiopasdfghjklzxcvbnm12345678
└─┬─┘└────────────────┬─────────────────┘
prefix        20-byte hash (base32)

​
Keyring Security

​
OS Backend (Default)

xyz config set keyring-backend os
Uses platform-specific secure storage:
PlatformStorageSecurity
macOSKeychainHigh
WindowsCredential ManagerHigh
LinuxSecret ServiceHigh

​
File Backend

xyz config set keyring-backend file
  • Encrypted with passphrase
  • Portable across machines
  • Requires passphrase for each operation

​
Test Backend

xyz config set keyring-backend test
Development only! Keys stored unencrypted at ~/.xyz/keyring-test/

​
Best Practices

  1. Write mnemonic on paper immediately
  2. Store in multiple secure locations
  3. Consider metal backup (fire/water resistant)
  4. Never store digitally (no photos, no cloud)
Use separate keys for different purposes:
  • hot-wallet - Daily transactions (small balance)
  • cold-wallet - Long-term storage (large balance)
  • dev-wallet - Development/testing only
For significant holdings, use a Ledger device:
# Ledger support via xyzd
xyzd keys add mykey --ledger
Periodically move funds to new keys:
  1. Generate new key
  2. Transfer funds
  3. Archive old key (don’t delete - may have pending rewards)

​
Using Keys with Commands

Most commands accept key references via --from or --key: 
# Query balance by key name
xyz balance --key mykey

# Send transaction with key
xyz token transfer xyz1contract... xyz1recipient... 1000 --from mykey

# Deploy contract with key
xyz program deploy contract.wasm --from mykey

​
Troubleshooting

Ensure the key exists:
xyz keys list
Check keyring backend matches:
xyz config get keyring-backend
Keys are stored per-backend. If you created a key with test backend but are using os:
xyz config set keyring-backend test
xyz keys list
On first use, macOS asks for permission. Click “Always Allow” to avoid repeated prompts.
Ensure a secret service is running:
# GNOME Keyring
gnome-keyring-daemon --start

# Or use file backend instead
xyz config set keyring-backend file