Key Management

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

Commands

Command	Description
`xyz keys generate`	Create a new keypair
`xyz keys list`	List all stored keys
`xyz keys import`	Import from mnemonic
`xyz keys export`	Export a keypair

Generate a New Key

Create a new keypair with a 24-word mnemonic:

xyz keys generate <name>

Example

xyz keys generate mykey

Output

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

Flag	Description
`--keyring-backend`	Override keyring backend
`--home`	Override 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

Output

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

Component	Value	Meaning
Purpose	44’	BIP44
Coin Type	118’	XYZ Chain
Account	0’	First account
Change	0	External chain
Index	0	First 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:

Platform	Storage	Security
macOS	Keychain	High
Windows	Credential Manager	High
Linux	Secret Service	High

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

Backup Strategy

Write mnemonic on paper immediately
Store in multiple secure locations
Consider metal backup (fire/water resistant)
Never store digitally (no photos, no cloud)

Multiple Keys

Use separate keys for different purposes:

hot-wallet - Daily transactions (small balance)
cold-wallet - Long-term storage (large balance)
dev-wallet - Development/testing only

Hardware Wallets

For significant holdings, use a Ledger device:

# Ledger support via xyzd
xyzd keys add mykey --ledger

Key Rotation

Periodically move funds to new keys:

Generate new key
Transfer funds
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

Key not found

Ensure the key exists:

xyz keys list

Check keyring backend matches:

xyz config get keyring-backend

Wrong 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

macOS Keychain permission

On first use, macOS asks for permission. Click “Always Allow” to avoid repeated prompts.

Linux Secret Service

Ensure a secret service is running:

# GNOME Keyring
gnome-keyring-daemon --start

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

Getting Started

Chain

Products

Developer Tools

Token Operations

Smart Contracts

Local Development

Chain API

Launchpad API

Key Management

Key Management

Commands

Generate a New Key

Example

Options

List Keys

Example Output

Import a Key

Interactive Mode

With Flag

Validation

Export a Key

Example

Key Derivation

Address Format

Keyring Security

OS Backend (Default)

File Backend

Test Backend

Best Practices

Using Keys with Commands

Troubleshooting

​Key Management

​Commands

​Generate a New Key

​Example

​Options

​List Keys

​Example Output

​Import a Key

​Interactive Mode

​With Flag

​Validation

​Export a Key

​Example

​Key Derivation

​Address Format

​Keyring Security

​OS Backend (Default)

​File Backend

​Test Backend

​Best Practices

​Using Keys with Commands

​Troubleshooting

Key Management

Commands

Generate a New Key

Example

Options

List Keys

Example Output

Import a Key

Interactive Mode

With Flag

Validation

Export a Key

Example

Key Derivation

Address Format

Keyring Security

OS Backend (Default)

File Backend

Test Backend

Best Practices

Using Keys with Commands

Troubleshooting