A secure CLI tool to generate paper wallets for multiple cryptocurrencies: Bitcoin, Ethereum, Solana, and Chainlink.

Built with Commander.js - the most popular Node.js CLI framework.

• 🔐 100% Offline - Generate wallets without internet connection
• 🎯 Multi-Currency - Bitcoin, Ethereum, Solana, Chainlink support
• 🔌 Plugin Architecture - Easy to add new blockchains
• ⚡ Plugin Generator - Scaffold new plugins in 2 minutes with yarn generate:plugin
• 📱 QR Codes - Scannable QR codes for each address
• 🔗 Explorer Links - Direct links to blockchain explorers
• 🧪 Dry-Run Mode - Test without generating real keys
• 📝 BIP39/BIP44 - Industry-standard HD wallet generation
• 🎨 Interactive CLI - Beautiful, user-friendly interface
• 🔒 Type-Safe - Full TypeScript support

For Users:

• 📦 Installation - Get started in 30 seconds
• 🚀 Usage Guide - Generate your first wallet
• ⚠️ Security Guide - Essential safety practices
• 📋 What Gets Generated - Understand the output

For Developers:

• 🔌 Plugin Generator - Add new blockchains (2 min setup!)
• 📖 Plugin Development Guide - Complete API documentation
• 🏗️ Plugin Architecture - Technical design patterns
• 🤝 Contributing Guide - How to contribute

Additional:

• 🔧 Development Setup - Local development
• 📦 Publishing Guide - npm publishing workflow
• 📚 Additional Resources - Standards & documentation

A paper wallet is a physical document containing your cryptocurrency addresses and private keys, stored completely offline. Think of it as printing out your bank account information, but with cryptographic keys instead.

The name refers to the storage method, not the addresses themselves:

Digital Keys → Written/Printed on Paper → "Paper Wallet"

• ✅ 100% offline - Immune to hacking
• ✅ No electronics - Can't fail or corrupt
• ✅ Long-term storage - Works for decades
• ✅ No batteries - Unlike hardware wallets
• ✅ Low cost - Just paper and ink

• ⚠️ Physical damage (fire, water, deterioration)
• ⚠️ Can be lost or stolen (like cash)
• ⚠️ Not convenient for frequent transactions
• ⚠️ Must manually type keys when spending

Important: Cryptocurrency addresses are generated using pure mathematics - they don't need to be "registered" on the blockchain!

Traditional Banking:
Bank assigns you account number → Stored in bank database → Now you can receive money

Cryptocurrency:
You generate address with math → No database entry → Can receive crypto immediately

1. Generate Random Number (256 bits of entropy)
   ↓
2. Create Mnemonic Seed Phrase (24 words)
   ↓
3. Derive Keys Using Elliptic Curve Cryptography
   ↓
4. Generate Public Key from Private Key (one-way math)
   ↓
5. Hash Public Key to Create Address (more one-way math)

All of this happens locally on your computer. No internet. No blockchain interaction.

The blockchain only knows about your address when:

Before first transaction:
- Your address exists: Only in your wallet
- Blockchain record: None (address is "invisible")

After first transaction:
- Transaction broadcast to network
- Blockchain records: "0.001 BTC sent to YOUR_ADDRESS"
- Now your address appears on blockchain with balance

You sign transaction with private key
→ Broadcast to network
→ Blockchain verifies signature matches address
→ Transaction processed

YES! 100% real. Here's why:

1. Mathematically Valid - Generated using the same cryptographic standards as hardware wallets
2. Blockchain-Ready - Will be accepted immediately when first used
3. Industry Standard Libraries - Uses the same code as MetaMask, Ledger, and Trezor
4. Can Hold Real Value - Send real cryptocurrency to them and it will be there

Bitcoin addresses: 2^160 = ~1.4 × 10^48 possible addresses
Ethereum addresses: 2^160 = ~1.4 × 10^48 possible addresses
Solana addresses: 2^256 = ~1.15 × 10^77 possible addresses

For comparison:
- Atoms in human body: ~7 × 10^27
- Stars in observable universe: ~10^24
- Grains of sand on Earth: ~7.5 × 10^18

There are more Bitcoin addresses than atoms in a million human bodies!

Technically yes, but practically... NEVER.

Probability of collision: ~1 in 10^48

You're more likely to:
✓ Win the lottery 6 times in a row
✓ Be struck by lightning 10 times in one day
✓ Find a specific atom in the universe

To get 50% chance of ONE collision:
- Need to generate: 2^80 addresses (1.2 septillion)
- At 1 billion/second: Would take 38 BILLION years
- Age of universe: 13.8 billion years

Historical evidence:
- Bitcoin launched: 2009
- Addresses generated: Billions+
- Collisions found: ZERO

The cryptographic security of address generation is rock solid! This is why wallets can generate addresses offline without checking if they "already exist."

READ BEFORE USING:

1. ⚠️ Run this tool OFFLINE on a secure, air-gapped computer
2. ⚠️ Never share private keys or seed phrases with anyone
3. ⚠️ Store paper wallets in a secure physical location (safe, vault)
4. ⚠️ Make backup copies and store in separate secure locations
5. ⚠️ Verify addresses before sending any funds
6. ⚠️ This tool is for educational/personal use only

npm install -g bitpaper
# or
yarn global add bitpaper

Then run from anywhere:

bitpaper generate

Clone the repository and install dependencies:

git clone <repository-url>
cd bitpaper
yarn install
yarn build

Then use via yarn or link locally:

yarn link
bitpaper generate

Or run directly:

node bin/cli.js generate

bitpaper generate

This will show an interactive selection menu where you can choose which cryptocurrencies to generate (all are selected by default).

Interactive Example:

? Select cryptocurrencies to generate: (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◉ ₿  Bitcoin (BTC)
 ◉ ♦  Ethereum (ETH)
 ◉ ◎  Solana (SOL)
 ◉ 🔗 Chainlink (LINK)

# Generate only Bitcoin and Ethereum
bitpaper generate --currencies bitcoin,ethereum

# Generate only Solana
bitpaper generate --currencies solana

# Mix and match
bitpaper generate --currencies bitcoin,solana,chainlink

Choose which address format(s) to display for currencies that support multiple formats (e.g., Bitcoin):

# Show only Legacy (P2PKH) addresses (starts with "1")
bitpaper generate --currencies bitcoin --format legacy

# Show only P2SH-SegWit addresses (starts with "3")
bitpaper generate --currencies bitcoin --format p2sh-segwit

# Show only Native SegWit addresses (starts with "bc1") - Most efficient
bitpaper generate --currencies bitcoin --format native-segwit

# Show all three formats (default)
bitpaper generate --currencies bitcoin --format all

📋 Format Support by Currency:

💡 The --format option only affects currencies with multiple address formats. Other currencies will show a helpful message if --format is used.

Format Comparison:

💡 All three formats share the same private key - you can receive Bitcoin at any of them and access the funds with the same private key.

bitpaper generate --dry-run

Perfect for:

• ✅ Testing the CLI before real use
• ✅ Seeing the output format
• ✅ Demonstrations and screenshots
• ✅ CI/CD pipeline testing

⚠️ NO real cryptographic keys are generated in dry-run mode!

bitpaper generate --count 5

Generate 5 wallet sets at once.

bitpaper generate --output wallets.txt

Important: After printing/backing up, securely delete the file:

shred -vfz -n 10 wallets.txt  # Linux/Mac

bitpaper generate --no-warnings --no-instructions

bitpaper verify "word1 word2 word3 ... word24"

Checks if a 24-word mnemonic phrase is valid.

bitpaper info

# Generate 3 sets with only Bitcoin and Ethereum, save to file
bitpaper generate --count 3 --currencies bitcoin,ethereum --output wallets.txt

# Bitcoin with only Native SegWit format
bitpaper generate --currencies bitcoin --format native-segwit

# Dry-run with specific currencies
bitpaper generate --dry-run --currencies solana

# Multiple Bitcoin wallets with legacy format only
bitpaper generate --count 5 --currencies bitcoin --format legacy --output legacy-wallets.txt

# Non-interactive with no warnings and specific format
bitpaper generate --currencies bitcoin --format p2sh-segwit --no-warnings --no-instructions

bitpaper --help
bitpaper generate --help

Want to add support for a new blockchain? BitPaper makes it easy!

# Clone the repo
git clone https://github.com/yhauxell/bitpaper.git
cd bitpaper
yarn install

# Generate a new blockchain plugin
yarn generate:plugin

The interactive generator will create all necessary files and register your plugin automatically!

yarn generate:plugin  # Generate new blockchain plugin
yarn build           # Build the project
yarn dev             # Run in development mode

• Plugin Generator Guide - Step-by-step scaffolding guide
• Plugin Development Guide - Complete API documentation
• Contributing Guide - Contribution workflow
• Plugin Architecture - Technical design

• ✅ Easy: Plugin generator handles all boilerplate
• ✅ Fast: Create plugin scaffold in under 2 minutes
• ✅ Type-safe: Full TypeScript support with interfaces
• ✅ Documented: Comprehensive guides and examples
• ✅ Impactful: Help users secure their crypto assets

See something missing? Open an issue or submit a PR!

Each wallet set includes:

• A master seed phrase that can recover ALL wallets
• MOST IMPORTANT - Store this securely!
• Can be used to restore wallets in any compatible wallet software

• Multiple Address Formats: Choose the format that works best for your wallet/exchange:
  • Legacy (P2PKH): Starts with "1" - Maximum compatibility, higher fees
  • P2SH-SegWit: Starts with "3" - SegWit with backward compatibility, medium fees
  • Native SegWit (P2WPKH): Starts with "bc1" - ⭐ Recommended, lowest fees (~40% lower)
• All addresses are derived from the same private key
• Explorer Link: Direct link to Blockchair (check balance/transactions)
• QR Code: Scannable QR code for easy address sharing
• Private Key: For sending Bitcoin or importing to wallets
• WIF (Wallet Import Format): Alternative private key format
• Public Key: For verification
• Derivation Path: m/44'/0'/0'/0/0

• Address: For receiving Ethereum
• Explorer Link: Direct link to Etherscan (check balance/transactions)
• QR Code: Scannable QR code for easy address sharing
• Private Key: For sending ETH or importing to MetaMask
• Public Key: For verification
• Works with all ERC-20 tokens
• Derivation Path: m/44'/60'/0'/0/0

• Address: For receiving LINK tokens
• Explorer Link: Direct link to Etherscan (check balance/transactions)
• QR Code: Scannable QR code for easy address sharing
• Private Key: For sending LINK or importing to wallets
• Note: Uses Ethereum addresses (LINK is an ERC-20 token)
• Derivation Path: m/44'/60'/0'/0/0

• Address: For receiving Solana
• Explorer Link: Direct link to Solscan (check balance/transactions)
• QR Code: Scannable QR code for easy address sharing
• Private Key: For sending SOL or importing to Phantom/Solflare
• Public Key: For verification

1. Use the Address to receive funds
2. Share using QR Code - Scan with wallet apps instead of typing manually
3. Share the address publicly - it's safe
4. Test with a small amount first

Each address includes a scannable QR code that makes receiving funds easier:

Benefits:

• ✅ No typing errors
• ✅ Fast and convenient
• ✅ Works with all major wallet apps
• ✅ Can be scanned from printed paper wallets

How to use:

1. Open your wallet app (MetaMask, Phantom, etc.)
2. Select "Send" or "Transfer"
3. Click "Scan QR Code"
4. Point your camera at the QR code on your paper wallet
5. Confirm the transaction

For printing:

• QR codes print clearly on paper
• Use high-quality printer for best results
• Test scanning before storing away

You'll need the Private Key:

Bitcoin:

• Import the WIF or private key into any Bitcoin wallet
• Recommended: Bitcoin Core, Electrum, or hardware wallets

Ethereum & Chainlink:

• Import private key into MetaMask, MyEtherWallet, or similar
• For LINK: Add the token contract to your wallet

Solana:

• Import private key into Phantom, Solflare, or similar
• Or use the CLI: solana-keygen recover

Instead of individual private keys, you can restore ALL wallets using the 24-word mnemonic:

• Bitcoin: Use BIP44 path m/44'/0'/0'/0/0
• Ethereum: Use BIP44 path m/44'/60'/0'/0/0
• Solana: Use first 32 bytes of seed

1. Disconnect from internet - Run on an offline computer
2. Use a clean system - Preferably a live USB OS like Tails
3. Verify the code - Review the source before running

1. Write down immediately - Have paper and pen ready
2. Double-check - Verify you wrote everything correctly
3. Don't take photos - Never digitally photograph private keys

1. Store securely - Use a fireproof safe or safety deposit box
2. Make multiple copies - Store in different secure locations
3. Test with small amounts - Verify everything works before large transfers
4. Delete digital files - Securely wipe any generated files:

   shred -vfz -n 10 wallets.txt

1. Use archival paper - Won't degrade over time
2. Consider metal - Engrave keys on steel plates for fire/water resistance
3. Protect from elements - Keep dry and away from heat/light
4. Plan inheritance - Consider how heirs will access (secure instructions)

1. ❌ Don't generate wallets on an online computer
2. ❌ Don't store private keys in cloud storage
3. ❌ Don't take screenshots or photos
4. ❌ Don't email private keys to yourself
5. ❌ Don't use the same wallet for multiple purposes
6. ❌ Don't forget to make backup copies
7. ❌ Don't throw away the paper - it's your only access!

Always test with small amounts first:

1. Generate a wallet
2. Send a small test amount to the address
3. Verify you can see the balance
4. Try sending the test amount back
5. Only then use for larger amounts

• BIP39: Mnemonic phrase generation (24 words, 256-bit entropy)
• BIP32: Hierarchical deterministic wallets
• BIP44: Multi-account hierarchy for deterministic wallets
  • Bitcoin: m/44'/0'/0'/0/0
  • Ethereum: m/44'/60'/0'/0/0
• Bitcoin Address Formats:
  • P2PKH: Legacy format (starts with "1")
  • P2SH: Pay-to-Script-Hash, used for SegWit compatibility (starts with "3")
  • P2WPKH: Native SegWit addresses (starts with "bc1", lowest fees)

• Commander.js: CLI framework (~25M weekly downloads)
• Chalk: Terminal styling
• Ora: Loading spinners
• bip39: Mnemonic generation
• bitcoinjs-lib: Bitcoin wallet generation
• ethers: Ethereum wallet generation
• @solana/web3.js: Solana wallet generation

• Uses Node.js crypto.randomBytes() for secure random number generation
• Requires system entropy for cryptographically secure keys

• Bitcoin: Mainnet (change BITCOIN_NETWORK in code for testnet)
• Ethereum: All EVM-compatible networks
• Solana: Mainnet-beta
• Chainlink: Ethereum mainnet (ERC-20)

yarn build

Compiles TypeScript to JavaScript in the dist/ directory.

yarn dev generate --count 1
# or use ts-node directly
yarn ts-node src/index.ts generate

bitpaper/
├── bin/
│   └── cli.js           # Executable entry point
├── src/
│   ├── index.ts         # Main CLI logic (Commander.js)
│   ├── wallet-generator.ts  # Wallet generation functions
│   └── ui.ts            # UI/display functions
├── dist/                # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── LICENSE
├── .npmignore
└── README.md

This project uses GitHub Actions to automatically publish to npm when code is merged to main!

Setup (One-time):

1. Create npm token at npmjs.com
2. Add token as NPM_TOKEN secret in GitHub repository settings
3. See GITHUB_SETUP.md for detailed instructions

To Publish a New Version:

# Bump version
yarn version --patch  # or --minor, --major

# Push to GitHub
git push --follow-tags

# GitHub Actions will automatically publish to npm! 🚀

If you prefer to publish manually:

Prerequisites:

1. Create an npm account: https://www.npmjs.com/signup
2. Login to npm:

   npm login
   # or
   yarn login

Before publishing, make sure:

• ✅ All tests pass (if you have tests)
• ✅ Build succeeds: yarn build
• ✅ Package contents are correct: yarn pack --dry-run
• ✅ Version number is updated in package.json
• ✅ CHANGELOG is updated (if you have one)
• ✅ README is up to date
• ✅ Git repository is clean and pushed

# Build and create a test tarball
yarn pack

# Test installation from the tarball
npm install -g ./yausell-bitpaper-v1.0.0.tgz

# Test the CLI
bitpaper --help

# Uninstall test
npm uninstall -g bitpaper

Follow Semantic Versioning:

# Patch release (1.0.0 -> 1.0.1) - bug fixes
yarn version --patch

# Minor release (1.0.0 -> 1.1.0) - new features
yarn version --minor

# Major release (1.0.0 -> 2.0.0) - breaking changes
yarn version --major

For Public Scoped Package:

npm publish --access public
# or
yarn publish --access public

For Unscoped Package (if you remove @yausell/ from the name):

npm publish
# or
yarn publish

# Check on npm
npm view bitpaper

# Install and test
npm install -g bitpaper
bitpaper --help

When you make changes:

1. Make your code changes
2. Update version: yarn version --patch (or --minor/--major)
3. Build: yarn build
4. Publish: yarn publish --access public

• Use npm tags for pre-releases:

  npm publish --tag beta --access public

• Unpublish within 72 hours if you make a mistake:

  npm unpublish bitpaper@1.0.0

• Deprecate old versions instead of unpublishing:

  npm deprecate bitpaper@1.0.0 "Please upgrade to 1.0.1"

BitPaper uses a plugin-based architecture that makes it easy to add support for new blockchains without modifying core files.

• ✅ Self-contained: Each blockchain in its own plugin directory
• ✅ Type-safe: Full TypeScript support with strict interfaces
• ✅ Auto-discovered: Plugins are automatically registered
• ✅ Extensible: Support for lifecycle hooks and custom features
• ✅ No core changes: Add blockchains without touching existing code

Using the Plugin Generator (Recommended):

yarn generate:plugin

This interactive command will:

• ✅ Prompt for blockchain details (name, symbol, icon, explorer URL, etc.)
• ✅ Generate all necessary files with your configuration
• ✅ Auto-register the plugin in src/plugins/index.ts
• ✅ Provide implementation guidance and next steps

Manual Setup:

1. Copy the plugin template:

   cp -r src/plugins/_template src/plugins/cardano

2. Implement the BlockchainProvider interface:

   • generateWallet(seed) - Create wallet from BIP39 seed
   • getExplorerUrl(address) - Return block explorer URL
   • formatWalletInfo(wallet) - Format wallet display
   • validateAddress(address) - Validate address format

3. Register your plugin in src/plugins/index.ts

4. Build and test:

   yarn build
   bitpaper generate --currencies cardano

Quick Start:

• Plugin Generator Guide - Interactive plugin scaffolding tool
  • Command reference and usage
  • Prompt explanations
  • Troubleshooting tips
  • Template customization

Complete Development Guide:

• Plugin Development Guide - Full implementation guide
  • Complete API documentation
  • Step-by-step tutorial with examples
  • Best practices and security guidelines
  • Testing strategies and workflows
  • Advanced features (lifecycle hooks, testnet support)

Technical Documentation:

• Plugin Architecture - System design documentation
  • Architecture overview and design patterns
  • Core interfaces and components
  • Plugin generator implementation
  • Migration summary and benefits

Contributing:

• Contributing Guide - Contribution workflow
  • Development setup
  • Code style and conventions
  • Pull request process
  • Security guidelines

• Bitcoin (src/plugins/bitcoin/) - Multi-format support (Legacy P2PKH, P2SH-SegWit, Native SegWit)
• Ethereum (src/plugins/ethereum/) - ERC-20 compatible
• Solana (src/plugins/solana/) - Ed25519 keypairs
• Chainlink (src/plugins/chainlink/) - ERC-20 token

We welcome blockchain integrations! Please ensure:

• ✅ Follows plugin template structure
• ✅ Includes proper error handling
• ✅ Uses well-maintained dependencies
• ✅ Tested thoroughly with dry-run and real generation
• ✅ Documentation for unique features

Submit a PR to add your blockchain to BitPaper! 🚀

• Plugin Generator Guide - Automated plugin scaffolding
• Plugin Development Guide - Complete development documentation
• Contributing Guide - How to contribute to the project
• Plugin Architecture - Technical design and patterns
• Publishing Guide - npm publishing workflow

• BIP39 Specification - Mnemonic code standard
• BIP32 Specification - Hierarchical Deterministic Wallets
• BIP44 Specification - Multi-Account Hierarchy
• SLIP-0044 - Registered coin types

• Bitcoin Paper Wallets - Bitcoin wiki
• Ethereum Private Keys - Ethereum docs
• Solana Key Pairs - Solana documentation

• Commander.js - CLI framework
• Plop - Plugin generator tool
• bitcoinjs-lib - Bitcoin library
• ethers.js - Ethereum library

This tool is provided as-is for educational purposes. Always:

• Test thoroughly before using with real funds
• Understand the risks of self-custody
• Consider hardware wallets for large amounts
• Consult with security professionals for high-value storage

MIT License - Use at your own risk.

Remember: With great power comes great responsibility. You are your own bank! 🏦