Keypairs with solana-keygen
Generate Ed25519 keypairs, recover wallets from seed phrases, and grind vanity addresses with solana-keygen.
Recipe
Quick-reference recipe card - copy-paste ready.
# New keypair (interactive passphrase optional)
solana-keygen new --outfile ~/.config/solana/id.json
# Recover from 12/24-word seed phrase
solana-keygen recover -o recovered.json
# Vanity prefix (slow - increase --num-threads)
solana-keygen grind --starts-with abc:1 --ignore-caseWhen to reach for this:
- First-time CLI setup before
solana config set --keypair. - Recovering a wallet on a new machine from a seed phrase.
- Creating separate deployer, upgrade-authority, or treasury keys.
- Grinding a vanity prefix for branding (expect long runtimes).
Working Example
mkdir -p ~/.config/solana
solana-keygen new --outfile ~/.config/solana/id.json --no-bip39-passphrase
solana config set --keypair ~/.config/solana/id.json
solana address
# Backup seed phrase when prompted - store offline, never in git
chmod 600 ~/.config/solana/id.jsonWhat this demonstrates:
- Creates a standard Ed25519 keypair file the CLI reads for signing.
--no-bip39-passphraseskips an extra encryption layer (dev only).chmod 600restricts read access to your user account.solana addressconfirms the public key matches expectations.
Deep Dive
How It Works
- Solana uses Ed25519; the keypair file is a 64-byte secret key JSON array.
solana-keygen newcan emit a BIP39 seed phrase for recovery.- Public keys are base58-encoded 32-byte addresses shown by
solana address. - Vanity grinding searches random keys until a prefix pattern matches.
Keypair File Layout
| Field | Format | Notes |
|---|---|---|
| Secret key | JSON byte array (64 bytes) | Contains seed + public key bytes |
| Passphrase | Optional BIP39 | Encrypts the on-disk file when set |
| Seed phrase | 12 or 24 words | Independent backup path to the same key |
bash Notes
# Verify pubkey without exposing the secret file contents
solana-keygen pubkey ~/.config/solana/id.json
# Prompt for passphrase-protected key during recover
solana-keygen recover prompt:// -o recovered.jsonGotchas
- Committing keypair files - JSON key files in git leak funds instantly. Fix: add
*.jsonkey paths to.gitignoreand use hardware or CI secrets for production. - Skipping seed phrase backup - disk failure means unrecoverable keys. Fix: write the phrase offline before funding the wallet.
- Reusing one keypair everywhere - deploy authority and daily dev share the same risk surface. Fix: separate keypairs per role and cluster.
- Vanity grind on laptops - long prefixes take hours or days. Fix: cap prefix length, use
--num-threads, or accept a shorter match. - Wrong outfile overwrite -
solana-keygen newoverwrites existing paths without a prompt in scripts. Fix: checktest -fbefore generating in automation.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Hardware wallet (Ledger) | Mainnet treasury and upgrade authority | Quick localnet iteration |
solana-keygen recover | Restoring from seed phrase | Generating brand-new keys |
| Browser wallet (Phantom) | End-user signing in dApps | Headless CI deploy pipelines |
mucho key helpers | Foundation scaffold workflows | You only need a single dev key |
FAQs
What format is the keypair file?
A JSON array of 64 unsigned bytes representing the Ed25519 secret key. The CLI and Anchor read this format natively.
Is the seed phrase the same as the JSON file?
They encode the same key material when created together. You can recover the JSON from the phrase with solana-keygen recover, but you cannot derive the phrase from the JSON alone if you skipped recording it.
Should I use a passphrase on the keypair file?
Yes for any key that holds mainnet funds. For throwaway devnet keys, --no-bip39-passphrase is common but never commit those files.
How do I print only the public key?
solana-keygen pubkey path/to/keypair.jsonCan two machines share one keypair safely?
Only through a secrets manager or encrypted channel - never Slack or email. Prefer separate keys per machine for dev and a single hardware-backed key for production roles.
What does vanity grinding cost?
CPU time grows exponentially with prefix length. A 3-character prefix is quick; 6+ characters may need dedicated hardware or overnight runs.
How do I recover with a passphrase-protected seed?
Run solana-keygen recover prompt:// and enter the phrase when prompted. Use ASK or prompt:// forms documented in solana-keygen recover --help.
Does solana-keygen work on Windows?
Yes via WSL or native builds from the Agave installer. Paths differ - use %USERPROFILE%\.config\solana\ equivalents.
What permissions should the key file have?
chmod 600 on Unix so only your user can read the secret bytes.
How is this different from a program keypair?
Program deploy keypairs sign deployment transactions; program IDs come from the program keypair's public key. Store program keys with the same care as treasury keys.
Related
- Solana CLI Basics - default keypair configuration
- Airdrops & Balances - fund a new pubkey
- Deploying Programs - program deploy keypairs
- Solana CLI Best Practices - key hygiene rules
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.