Creating a secure and functional Bitcoin wallet is a foundational step for managing digital assets effectively. The createwallet command in Bitcoin Core offers a powerful, flexible way to generate new wallets directly through the command line. Whether you're a developer, advanced user, or just exploring Bitcoin's underlying tools, understanding how to use createwallet empowers you with full control over wallet configuration.
This guide walks you through every parameter of the createwallet command, explains their implications, and shows practical examples to help you set up wallets tailored to your security and privacy needs.
Understanding the createwallet Command Syntax
The basic structure of the command is:
createwallet "wallet_name" ( disable_private_keys blank "passphrase" avoid_reuse descriptors load_on_startup )This command creates and loads a new wallet into the running Bitcoin Core node. Let’s break down each argument to understand its role and impact.
Argument #1: Wallet Name (Required)
Type: String
The wallet_name is the only required parameter. It defines the identifier for your new wallet. If you provide a file path (e.g., /home/user/wallets/mywallet), Bitcoin Core will create the wallet at that specific location.
⚠️ Wallet names must be unique within your node. Attempting to create a wallet with an existing name will result in an error unless it's already loaded.
👉 Learn how to securely manage multiple Bitcoin wallets using advanced tools.
Argument #2: Disable Private Keys (Optional)
Type: Boolean | Default: false
Setting disable_private_keys=true creates a watch-only wallet. Such wallets can monitor balances and validate transactions but cannot sign or spend funds since they don’t store private keys.
This is ideal for:
- Auditing services
- Cold storage monitoring
- Multi-signature setups where signing occurs offline
Use this mode when security through separation of duties is critical.
Argument #3: Blank Wallet (Optional)
Type: Boolean | Default: false
A blank=true wallet starts with no keys and no HD (Hierarchical Deterministic) seed. This means:
- No addresses are generated automatically
- You must manually import keys or set a seed later using
sethdseed
This option is useful for:
- Regulatory compliance scenarios
- Institutions that manage seeds externally
- Advanced setups requiring precise key control
👉 Discover secure ways to store and manage Bitcoin with institutional-grade solutions.
Argument #4: Passphrase (Optional)
Type: String
Encrypting your wallet with a passphrase ensures that all private keys are stored encrypted on disk. Without the passphrase, the wallet cannot be loaded or used — even if someone gains access to your machine.
🔐 Best Practice: Use a strong, unique passphrase. Avoid reusing passwords from other platforms.
Once encrypted:
- The wallet must be unlocked (
walletpassphrase) before sending transactions - Encryption applies only to private data; public addresses and transaction history remain visible
Argument #5: Avoid Reuse (Optional)
Type: Boolean | Default: false
Enabling avoid_reuse=true activates built-in protections against address reuse — a common privacy leak in Bitcoin.
With this enabled:
- Bitcoin Core tracks whether coins have been previously spent ("dirty" vs "clean")
- Change outputs are handled more carefully
- Spending recommendations aim to minimize linkability between transactions
This setting enhances user privacy and aligns with modern best practices in personal financial hygiene on the blockchain.
Argument #6: Descriptors (Optional)
Type: Boolean | Default: false
Setting descriptors=true creates a descriptor-based wallet, which uses script descriptors to manage address derivation internally.
Benefits include:
- Better interoperability with other descriptor-aware wallets
- Clearer backup procedures
- Support for complex scripts like multisig and Taproot
- Easier migration and auditing
Descriptor wallets represent the future of wallet architecture in Bitcoin Core and are recommended for new deployments.
Argument #7: Load on Startup (Optional)
Type: Boolean | Default: null
The load_on_startup parameter determines whether the wallet should be automatically reloaded when Bitcoin Core restarts.
true: Adds the wallet to persistent startup configurationfalse: Removes the wallet from auto-load listnull: Leaves current settings unchanged
This is especially useful in server environments where consistent wallet availability is required without manual intervention.
Understanding the Response Output
When successful, the createwallet command returns a JSON object:
{
"name": "testwallet",
"warning": "Wallet contains no HD seed. Use sethdseed to initialize."
}Key fields:
"name": Confirms the wallet name or full path"warning": Alerts you to potential issues (e.g., blank wallet, missing seed)
Always check for warnings — they may indicate configuration gaps that affect usability or security.
Practical Examples
Example 1: Create a Basic Encrypted Wallet
bitcoin-cli createwallet "my_secure_wallet" false false "my_strong_passphrase"This creates:
- A named wallet:
my_secure_wallet - With private keys enabled
- Not blank (HD seed generated)
- Encrypted with your passphrase
- Standard privacy settings
Example 2: Create a Watch-Only Descriptor Wallet
bitcoin-cli createwallet "watch_only" true false "" false true nullUseful for monitoring incoming payments without risking exposure of spending keys.
Example 3: Create a Blank Wallet for Cold Storage
bitcoin-cli createwallet "cold_storage" false true "" false true trueIdeal for air-gapped systems. You’ll later import keys or set a seed securely.
Example 4: Using cURL via JSON-RPC
curl --user myusername --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "createwallet", "params": ["testwallet"]}' -H 'content-type: text/plain;' http://127.0.0.1:8332/This method allows integration with scripts, web apps, or remote management tools.
Frequently Asked Questions (FAQ)
Q: Can I change wallet settings after creation?
A: Some settings like encryption require wallet creation time. However, features like avoid_reuse can be toggled later using setwalletflag.
Q: What happens if I lose my passphrase?
A: There is no recovery. Without the passphrase, encrypted wallets cannot be accessed. Always back up passphrases securely — ideally offline.
Q: Is it safe to store wallets on cloud drives?
A: Only if encrypted and not actively loaded. Never expose unencrypted wallet files (like wallet.dat) to networked storage.
Q: What’s the difference between a blank wallet and one without private keys?
A: A blank wallet has no keys or seed but can later accept them. A no-private-keys wallet is watch-only — it observes but never controls funds.
Q: Should I use descriptor wallets by default in 2025?
A: Yes. Descriptor wallets offer better transparency, backup clarity, and future-proofing for new script types like Taproot.
Q: How many wallets can I load at once?
A: Bitcoin Core supports multiple wallets simultaneously, limited mainly by system resources. Use listwallets to view active ones.
👉 Explore next-generation crypto storage and trading platforms built for security and performance.
By mastering the createwallet command, you gain granular control over your Bitcoin experience — from privacy tuning to enterprise-grade key management. Whether setting up a personal wallet or managing institutional infrastructure, these tools form the backbone of responsible cryptocurrency use.