# vgen
[](https://crates.io/crates/vgen)
[](https://crates.io/crates/vgen)
[](LICENSE)
[](https://deepwiki.com/oritwoen/vgen)
Bitcoin vanity address generator with regex pattern matching and GPU acceleration.
> [!WARNING]
> This project is experimental. Do not use generated keys for storing real funds without thorough verification. Always prefer hardware wallets or well-established software for production use.
## Features
- Generate cryptocurrency addresses matching custom regex patterns
- Multiple address formats: P2PKH (1...), P2WPKH (bc1q...), P2TR (bc1p...), P2SH-P2WPKH (3...), Ethereum (0x...)
- GPU acceleration via wgpu (Vulkan/Metal/DX12/OpenGL backends)
- Parallel CPU scanning with rayon
- Interactive TUI with real-time statistics
- Range scanning for Bitcoin Puzzle challenges
- Data providers for puzzle/bounty integration (boha)
- Output: text, JSON, JSON Lines, CSV, minimal
## Installation
### From crates.io
```bash
cargo install vgen
```
### Arch Linux (AUR)
```bash
paru -S vgen
```
### From source
```bash
cargo install --path .
```
## Usage
### Generate vanity address
```bash
# Find address starting with "1Cat"
vgen generate -p "^1Cat"
# Case insensitive matching
vgen generate -p "^1cat" -i
# Bech32 address ending with "dead"
vgen generate -p "dead$" -f p2wpkh
# Taproot address
vgen generate -p "^bc1p.*cat" -f p2tr
# P2SH-P2WPKH (nested SegWit)
vgen generate -p "^3Cat" -f p2sh-p2wpkh
# Ethereum address
vgen generate -p "^0xdead" -f ethereum
# CPU only (GPU is enabled by default)
vgen generate -p "^1Cat" --no-gpu
# Pick a specific GPU backend
vgen generate -p "^1Cat" --backend vulkan
# Find multiple matches
vgen generate -p "^1Cat" -c 5
# Quiet mode
vgen generate -p "^1Cat" -q
```
### Estimate difficulty
```bash
vgen estimate -p "^1CatDog"
```
### Scan key range (Bitcoin Puzzles)
```bash
# Scan puzzle #66 range
vgen range --puzzle 66 -p "."
# Custom range
vgen range -r "20000000000000000:3FFFFFFFFFFFFFFFF"
```
### Data providers
Use external data sources for pattern generation:
```bash
# Vanity with puzzle address prefix (6 characters)
vgen generate -p "boha:b1000:66" -l 6
# → Resolves to pattern: ^13zb1h
# Puzzle solving (exact address match + auto key range)
vgen range -p "boha:b1000:66"
# → Range: 2^65..2^66-1
# → Pattern: ^13zb1hQbWVsc2S7ZTZnP2G4undNNpdh5so$
# With prefix matching in range mode
vgen range -p "boha:b1000:66" -l 8
```
Supported providers:
- `boha:collection:id` - [boha](https://github.com/oritwoen/boha) puzzle library (b1000, gsmg, bitaps, etc.)
### Verify private key
```bash
# From WIF
vgen verify -k "5HueCGU8rMjxEXxiPuD5BDku4MkFqeZyd4dZ1jvhTVqvbTLvyTJ"
# From hex
vgen verify -k "0c28fca386c7a227600b2fe50b7cae11ec86d3bf1fbe471be89827e19d72aa1d"
# Verify against expected address
vgen verify -k "5HueCGU8rMjxEXxiPuD5BDku4MkFqeZyd4dZ1jvhTVqvbTLvyTJ" -a "1GAehh7TsJAHuUAeKZcXf5CnwuGuGgyX2S"
```
### List GPUs
```bash
vgen list-gpus
```
## Output formats
```bash
# Default text output
vgen generate -p "^1Cat" -o text
# JSON output (pretty-printed)
vgen generate -p "^1Cat" -o json
# JSON Lines (one JSON object per line, for data pipelines)
vgen generate -p "^1Cat" -o jsonl
# CSV (with header, for data catalogs/Iceberg)
vgen generate -p "^1Cat" -o csv
# Minimal (just WIF)
vgen generate -p "^1Cat" -o minimal
# Write to file
vgen generate -p "^1Cat" -o jsonl --file results.jsonl
vgen generate -p "^1Cat" -o csv --file results.csv
```
## TUI
The interactive TUI is enabled by default in terminal sessions. Disable with `--no-tui`.
Features:
- Real-time hashrate display
- Performance sparkline chart
- Luck indicator
- Found matches list
## Performance
GPU acceleration is enabled by default and falls back to CPU if no compatible GPU is found. Use `--backend` to force a specific backend (vulkan, metal, dx12, gl) or `--no-gpu` for CPU only.
- CPU: ~50,000-200,000 keys/sec (depends on CPU)
- GPU: ~500,000-2,000,000 keys/sec (depends on GPU)
## Pattern syntax
Patterns use Rust regex syntax:
| `^1Cat` | Starts with "1Cat" |
| `dead$` | Ends with "dead" |
| `^1[Cc]at` | Starts with "1Cat" or "1cat" |
| `^1.*dead$` | Starts with "1", ends with "dead" |
## Comparison
| **vgen** | Rust | wgpu (Vulkan/Metal/DX12) | regex | TUI, range scanning, memory safe |
| [VanitySearch](https://github.com/JeanLucPons/VanitySearch) | C++ | CUDA | prefix | Fastest (~7 Gkeys/s), NVIDIA only |
| [vanitygen-plusplus](https://github.com/10gic/vanitygen-plusplus) | C++ | OpenCL | prefix/regex | 100+ cryptocurrencies |
| [btc-vanity](https://github.com/Emivvvvv/btc-vanity) | Rust | - | prefix/regex | BTC/ETH/SOL, CPU only |
| [nakatoshi](https://github.com/ndelvalle/nakatoshi) | Rust | - | prefix | Simple, prefix only |
| [supervanitygen](https://github.com/klynastor/supervanitygen) | C | - | prefix | ASM optimizations (AVX2/SHA-NI) |
| [vanitygen](https://github.com/samr7/vanitygen) | C | - | prefix/regex | Classic, unmaintained |
**Why vgen?**
- Cross-platform GPU via wgpu (not locked to NVIDIA CUDA)
- Memory safe Rust implementation
- Full regex pattern support
- Interactive TUI with real-time statistics
- Bitcoin Puzzle range scanning built-in
## Agent Skills
This project includes [agent skills](https://skills.sh/) that teach AI coding agents how to use vgen.
### Static skills
Curated by the project author:
```bash
npx skills add oritwoen/vgen
```
| `vgen` | CLI and library API for Bitcoin vanity address generation with GPU acceleration |
### Dynamic skills
Auto-generated from live docs, issues, and releases using [skilld](https://github.com/harlan-zw/skilld):
```bash
npx skilld add oritwoen/vgen
```
## Roadmap
- [ ] More cryptocurrencies (Litecoin, Dogecoin, Solana, etc.)
- [ ] GPU performance improvements (CUDA backend, shader optimizations)
- [ ] More data providers (mempool, blockchair, etc.)
## Security
Generated private keys are cryptographically secure random numbers. Always verify the generated key produces the expected address before use.
## License
MIT
