https://github.com/aguimaraes/btc-keygen
Minimal offline Bitcoin key generator for cold storage
https://github.com/aguimaraes/btc-keygen
air-gapped bech32 bitcoin cli cold-storage cryptocurrency key-generator offline rust secp256k1 segwit wif
Last synced: about 2 months ago
JSON representation
Minimal offline Bitcoin key generator for cold storage
- Host: GitHub
- URL: https://github.com/aguimaraes/btc-keygen
- Owner: aguimaraes
- License: apache-2.0
- Created: 2026-03-15T04:17:07.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-14T18:50:23.000Z (3 months ago)
- Last Synced: 2026-04-14T20:28:05.537Z (3 months ago)
- Topics: air-gapped, bech32, bitcoin, cli, cold-storage, cryptocurrency, key-generator, offline, rust, secp256k1, segwit, wif
- Language: Rust
- Homepage: https://aguimaraes.github.io/btc-keygen
- Size: 147 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# btc-keygen
Minimal offline Bitcoin key generator for cold storage.
## What it does
Generates a Bitcoin private key and its corresponding native SegWit (Bech32) address in a single execution. Prints both to stdout, keeps no state, and exits. Designed to run on an air-gapped machine for cold storage key ceremonies.
```
$ btc-keygen generate
address: bc1q...
wif: K...
```
Every run creates a new keypair. The tool does not store secrets. If you lose the output, there is no way to recover the key.
## Features
- Cryptographically secure randomness from the OS
- secp256k1 validation using Bitcoin Core's libsecp256k1
- Compressed public keys, native SegWit (Bech32) addresses
- WIF private key export
- Optional hex and public key output
- JSON output for scripting
- Memory zeroization of secret material on exit
- Zero network code — fully offline
- Automated tests including known-answer vectors from the Bitcoin wiki
- Cross-platform: Linux, macOS, Windows, BSDs
## Library usage
Add to your project:
```
cargo add btc-keygen
```
```rust
let key = btc_keygen::generate()?;
let wif = btc_keygen::encode_wif(&key);
let pubkey = btc_keygen::derive_pubkey(&key);
let address = btc_keygen::derive_address(&pubkey);
```
| Function | Input | Output |
| ------------------------------- | --------------------- | ---------------------------------------------- |
| `generate()` | — | `Result` |
| `PrivateKey::from_bytes(bytes)` | `[u8; 32]` | `Result` (validated scalar) |
| `PrivateKey::from_hex(hex)` | `&str` (64 hex chars) | `Result` (validated scalar) |
| `encode_wif(&key)` | `&PrivateKey` | `String` (starts with `K` or `L`) |
| `derive_pubkey(&key)` | `&PrivateKey` | `[u8; 33]` (compressed public key) |
| `derive_address(&pubkey)` | `&[u8; 33]` | `String` (Bech32 address, `bc1q...`) |
`PrivateKey` zeroizes its bytes when dropped. Full API docs at [docs.rs/btc-keygen](https://docs.rs/btc-keygen).
## Install (CLI)
Download a pre-built binary from the
[latest release](https://github.com/aguimaraes/btc-keygen/releases/latest),
verify the SHA256 checksum, and run it.
Or build from source:
```
git clone https://github.com/aguimaraes/btc-keygen.git
cd btc-keygen
cargo build --release
./target/release/btc-keygen generate
```
Requires [Rust](https://www.rust-lang.org/tools/install) and a C compiler.
## Usage
```
btc-keygen generate # address + WIF
btc-keygen generate --hex # also show raw private key hex
btc-keygen generate --pubkey # also show compressed public key
btc-keygen generate --json # JSON output
btc-keygen generate --hex --pubkey --json # everything
# Provide your own 64-character hex private key instead of OS entropy:
btc-keygen generate --from-hex
```
## Security
This tool is designed for air-gapped cold storage key generation. See the
[website](https://aguimaraes.github.io/btc-keygen) for a plain-language
explanation, or the [docs/](docs/) directory for the full threat model,
security assumptions, and dependency analysis.
## License
Licensed under either of
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
at your option.