https://github.com/gamepunk/vanitygen-cli
Bitcoin vanity address generator — find your perfect address.
https://github.com/gamepunk/vanitygen-cli
bitcoin cargo linux macos rust vanity windows
Last synced: about 22 hours ago
JSON representation
Bitcoin vanity address generator — find your perfect address.
- Host: GitHub
- URL: https://github.com/gamepunk/vanitygen-cli
- Owner: gamepunk
- License: mit
- Created: 2026-06-25T02:18:08.000Z (14 days ago)
- Default Branch: main
- Last Pushed: 2026-06-25T03:52:41.000Z (14 days ago)
- Last Synced: 2026-06-25T05:05:54.590Z (14 days ago)
- Topics: bitcoin, cargo, linux, macos, rust, vanity, windows
- Language: Rust
- Homepage: https://crates.io/crates/vanitygen
- Size: 195 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# vanitygen
[](https://github.com/gamepunk/vanitygen/actions/workflows/ci.yml)
[](https://crates.io/crates/vanitygen)
[](LICENSE)
[中文版](README.zh-CN.md)
**Bitcoin vanity address generator — find your perfect address.**
Generate custom Bitcoin addresses with a chosen prefix
(e.g. `1Bit`, `1Pizza`, `bc1qninja`). Supports all 4 address formats.
All cryptographic primitives are delegated to the audited
[`rust-bitcoin`](https://github.com/rust-bitcoin/rust-bitcoin) crate
(backed by `libsecp256k1` — the same C library Bitcoin Core uses).
---
## Install
### Prerequisites
- **Rust 1.70+** — install via [rustup](https://rustup.rs) (all platforms)
- Nothing else — no OpenSSL, no system libraries
### Build
```bash
cargo build --release
./target/release/vanitygen 1Bit
```
Or install globally:
```bash
# From crates.io (recommended):
cargo install vanitygen
# Or build from source:
cargo install --git https://github.com/gamepunk/vanitygen.git
# Then run:
vanitygen 1Bit
```
### Platform notes
| Platform | Build | Bark notifications |
|----------|-------|-------------------|
| macOS | ✅ native | ✅ uses system `curl` |
| Linux | ✅ native | ✅ uses `curl` |
| Windows | ✅ native | ❌ not supported (no `curl`) |
Bark is optional and purely cosmetic — the tool works fully on all platforms
without it.
---
## Commands
### `vanitygen` / `vanitygen search` — Search for a vanity address
**Default command.** Find an address matching a pattern (prefix, suffix,
anywhere, or regex).
```
vanitygen 1Bit
vanitygen search 1Bit
```
**Options:**
| Flag | Default | Description |
|------|---------|-------------|
| `-t, --address-type TYPE` | `legacy` | Address type |
| `-i, --case-insensitive` | off | Match any letter case (faster) |
| `-m, --mnemonic` | off | Use BIP39+BIP32 derivation (outputs seed phrase) |
| `-u, --uncompressed` | off | Uncompressed public key (Legacy only) |
| `-T, --threads N` | all cores | Worker threads |
| `-q, --quiet` | off | Suppress progress output |
| `--bark KEY` | — | Bark API key for iOS push notification |
| `-p, --match-prefix` | (default) | Match pattern as prefix |
| `-s, --suffix` | off | Match pattern as suffix |
| `-a, --anywhere` | off | Match pattern anywhere in the address |
| `-r, --regex` | off | Interpret pattern as a regular expression |
| `--words N` | `24` | BIP39 word count: 12/15/18/21/24 (with `--mnemonic`) |
| `-n, --count N` | `1` | Number of addresses to find |
| `--input-file FILE` | — | Read patterns from file (one per line) |
| `-o, --output-file FILE` | — | Append results to file |
**Examples:**
Search Legacy, normal mode (fast, outputs WIF):
```
$ vanitygen 1Pizza -T 8
>> Self-test passed
>> Searching
prefix: 1Pizza
type: Legacy (P2PKH)
threads: 8
>> Found vanity address
Address: 1Pizza5RqXnupPvn9KbK8cLTBPcVB8zFhE
WIF: L2VH7b3xpLkv1jN8bPNdw73tK8fH... ← import this into your wallet
attempts: 10,317
elapsed: 11.2s
>> Same-key addresses
Legacy (P2PKH): 1Pizza5RqXnupPvn9KbK8cLTBPcVB8zFhE
Nested SegWit (P2SH): 3Ji9hUqTq15rQd...
Native SegWit (P2WPKH): bc1qpy7y0...
Taproot (P2TR): bc1pxv50f...
```
Search case-insensitive (faster, address letter-case will be random):
```
vanitygen 1bit -i -T 8
```
Search with uncompressed public key (Legacy only):
```
vanitygen 1Pizza -u -T 8
```
Search with mnemonic (slower, outputs BIP39 seed phrase, 24 words by default):
```
$ vanitygen 1Pizza -m
>> Searching
prefix: 1Pizza
type: Legacy (P2PKH)
threads: 8
source: BIP39+BIP32
>> Found vanity address
Address: 1Pizza5RqXnupPvn9KbK8cLTBPcVB8zFhE
WIF: L2VH7b3xpLkv1jN8bPNdw73tK8fH...
>> BIP39 Mnemonic
abandon ability able about above absent...
derivation path: m/44'/0'/0'/0/0
>> Wallet addresses (index 0)
Legacy (P2PKH): 1Pizza5RqXnupPvn9KbK8cLTBPcVB8zFhE (path: m/44'/0'/0'/0/0)
Nested SegWit (P2SH): 3Ji9hUqTq15rQd... (path: m/49'/0'/0'/0/0)
Native SegWit (P2WPKH): bc1qpy7y0... (path: m/84'/0'/0'/0/0)
Taproot (P2TR): bc1pxv50f... (path: m/86'/0'/0'/0/0)
```
Search other address types:
```
vanitygen bc1qbit -t segwit
vanitygen 3Pizza -t p2sh
vanitygen bc1pbit -t taproot
```
**Match modes:**
By default the pattern is matched as a **prefix** (the address starts with it).
Use one of these flags to change the match behaviour:
```bash
# Suffix mode — address ends with "pizza"
vanitygen pizza -s -t segwit
# Suffix + case-insensitive
vanitygen pizza -s -i -t segwit
# Anywhere mode — address contains "ninja"
vanitygen ninja -a -t segwit
# Regex mode — any regex pattern supported by the regex crate
vanitygen '^1[A-Z]{3}.*[0-9]{2}$' -r -t legacy
# Regex + suffix-style via regex anchor
vanitygen 'pizza$' -r -t segwit
```
**Mnemonic word count:**
```bash
# 12-word mnemonic (faster generation, still secure)
vanitygen 1Pizza -m --words 12
# Default: 24 words (256-bit security)
vanitygen 1Pizza -m
```
**Batch mode (input / output files):**
Create a file with one pattern per line (blank lines and `#` comments are
skipped). Each line can optionally include inline flags after the pattern:
```bash
vanitygen --input-file patterns.txt -o results.txt
```
The input file format:
```
# My patterns
1Bitcoin # uses CLI defaults (prefix, legacy)
ninja -a -t segwit # anywhere mode, segwit address
pizza -s -i # suffix mode, case-insensitive
^1A.*T$ -r # regex mode
```
Results are appended to the output file in a structured format:
```
---
pattern: 1Bitcoin
mode: Prefix
address: 1BitcoinXXXXXXXXXXXXXX
wif: Lxxxxxxxxxxxxxxxxxxxxxxx
attempts: 12345
elapsed: 10.23s
```
---
### `vanitygen verify` — Validate a WIF private key
Parse a WIF and show all four derived addresses.
```
$ vanitygen verify Kz6K83ge1AeeDi7fvE7kxGkyYws47sucXUZZwMXVTFG9q7u4ey12
>> WIF Verification
network: Mainnet
compressed: true
>> Derived addresses
Legacy (P2PKH): 1Ninja2TuXomkKakWbMzb9VBG8aj5krLbF
Nested SegWit (P2SH): 37nx7BGgtq28QbRfMAdHYg2zsjmGBiVtuQ
Native SegWit (P2WPKH): bc1qaeqa7easxmtfzr2jrpaqex9t6nudj0887p8cdq
Taproot (P2TR): bc1pm3xcsp9ys2y6f2elt0yqzycrdkssdv4xhznjudqn2r07k2ympvusdnazap
```
---
### `vanitygen address` — Derive all address types from a key
Shows all four address formats from a single private key.
```
$ vanitygen address Kz6K83ge1AeeDi7fvE7kxGkyYws47sucXUZZwMXVTFG9q7u4ey12
>> Addresses from private key
network: Mainnet
compressed: true
>> Derived addresses
Legacy (P2PKH): 1Ninja2TuXomkKakWbMzb9VBG8aj5krLbF
Nested SegWit (P2SH): 37nx7BGgtq28QbRfMAdHYg2zsjmGBiVtuQ
Native SegWit (P2WPKH): bc1qaeqa7easxmtfzr2jrpaqex9t6nudj0887p8cdq
Taproot (P2TR): bc1pm3xcsp9ys2y6f2elt0yqzycrdkssdv4xhznjudqn2r07k2ympvusdnazap
```
---
### `vanitygen mnemonic` — Generate a random BIP39 wallet
Creates a 24-word BIP39 mnemonic (256-bit) and derives addresses
for all 4 standard BIP32 paths at index 0.
```
$ vanitygen mnemonic
>> BIP39 Mnemonic (24 words, 256-bit)
abandon ability able about above absent abstract ...
>> Legacy (P2PKH)
path: m/44'/0'/0'/0/0
WIF: L25wxdxzuhRbAZ5ScDf...
P2PKH: 1Htr2MgUzhxRLuzAb3HB6HxgEoBe2Cswmq
P2SH: 3MAJvD3BF4EvvponEDZQckPKc5TaY9oCSz
P2WPKH: bc1qh9gzvddydxcx7w2wh28sypt7xj0xlgcy9pngc6
P2TR: bc1p84pg4cl2zxda5k6lydugnh2umdsc8e5035303ss3f0pqvxmcdmqsc6r43y
```
⚠ Write down these 24 words. Keep them offline. Anyone with this phrase
can steal your funds.
---
### `vanitygen benchmark` — Measure performance
Derives all 4 address types from random keys to measure throughput.
```
$ vanitygen benchmark
>> Benchmark
threads: 8
iterations: 400000 (50000 per thread)
>> Results
elapsed: 3.315s
keys derived: 400000
speed: 0.12 Mkeys/s
threads: 8
per thread: 15.08 kkeys/s
```
---
## Address Types
| Type | CLI name | Prefix | Encoding | BIP standard |
|------|----------|--------|----------|-------------|
| Legacy (P2PKH) | `legacy` | `1…` | Base58Check | BIP44 |
| Nested SegWit (P2SH) | `p2sh` | `3…` | Base58Check | BIP49 |
| Native SegWit (P2WPKH) | `segwit` | `bc1q…` | Bech32 | BIP84 |
| Taproot (P2TR) | `taproot` | `bc1p…` | Bech32m | BIP86 |
---
## Performance
Timings for **normal mode** on an M-series Mac (8 threads, ~1 Mkeys/s).
| Effective chars | Avg tries | Normal mode | `--mnemonic` mode |
|:---:|---:|---:|---:|
| 2 | 3.3×10³ | < 0.1s | ~1s |
| 3 | 1.9×10⁵ | 0.2s | ~50s |
| 4 | 1.1×10⁷ | 11s | ~50 min |
| 5 | 6.5×10⁸ | 11 min | impractical |
| 6+ | 3.8×10¹⁰ | ~10 h | impractical |
Use `--mnemonic` for short prefixes (2–3 chars). For longer prefixes use
normal mode and import the WIF directly.
---
## Notes
**Base58Check encoding:** The second character of a P2SH address (`3…`) is
always uppercase (A–R) or a digit (1–9) — never lowercase. For Legacy
addresses (`1…`) it's lowercase only ~2% of the time. The tool warns
you if you try an impossible prefix.
### Push notification (Bark)
Receive an iOS push notification when a match is found.
**Setup:** Get your free API key from the [Bark app](https://bark.day.app/).
```bash
# Via CLI flag:
vanitygen 1Pizza --bark YOUR_KEY_HERE
# Or via config file (recommended):
# ~/.config/vanitygen/config.toml
# bark_key = "YOUR_KEY_HERE"
```
CLI flag overrides config file.
Uses system `curl` — zero deps. Not available on Windows (no `curl`).
---
## Configuration file
`vanitygen` loads settings from `~/.config/vanitygen/config.toml` (XDG standard).
```toml
# ~/.config/vanitygen/config.toml
# Default thread count (overridable by -T / --threads)
threads = 8
# Bark API key for iOS push notification
bark_key = "YOUR_KEY_HERE"
# Default address type (legacy, p2sh, segwit, taproot)
# address_type = "legacy"
```
CLI flags always override config file values.
---
## Dependencies
```
vanitygen v0.4.0
├── bip39 — BIP39 mnemonic generation
├── bitcoin — Bitcoin address / key types
├── bs58 — Base58Check encoding (hot path)
├── clap — CLI argument parsing
├── rand — Cryptographic random numbers
├── ripemd — RIPEMD-160 hashing (hot path)
└── sha2 — SHA-256 hashing (hot path)
```
---
## Disclaimer
**⚠ Use at your own risk.**
This tool generates Bitcoin private keys entirely on your local machine.
Private keys and mnemonic phrases are displayed in plain text on your
terminal. Anyone with access to your screen, terminal history, or
clipboard can steal your funds.
- **Always move funds to a new address immediately** after the vanity
address is funded.
- **Clear your terminal history** after generating a key
(`history -c` on Unix, or restart your terminal).
- **Never** share your WIF, mnemonic phrase, or private key with anyone.
- **Run on an offline (air-gapped) machine** for maximum security.
- The authors assume **no liability** for any loss of funds or damages
arising from the use of this software.
By using this software you accept these terms.
---
## License
MIT