Your Bitcoin shouldn’t die with you.
Most people with Bitcoin have no plan for what happens when they die. Not because they don't care. It's because the tools are too complicated, too expensive, or require trusting a company that might not exist in 20 years.
GhostKey is a free, open-source way to make sure your Bitcoin reaches the people you love. You keep your keys. You stay in control. If you ever stop checking in, a countdown begins, and when it ends your heir can claim what you left them. No lawyer. No middleman. No permission needed from anyone.
- Paste your wallet's extended public key (xpub) into the setup wizard
- Enter your heir's email and a name for the vault
- Choose how long to wait before they can claim (e.g. 3 months)
- Open the site once a month and tap I'm still here
That's the whole job. One tap a month.
If you stop tapping, a countdown starts. When it ends, your heir gets one email with a link. They open it in any browser, paste their Bitcoin address, and receive a transaction they sign with their own wallet. No account. No app. No one holds their funds at any point.
GhostKey works with Bitcoin you actually control.
If your sats are on Blink, Yellow Card, Binance, or any exchange, those sats belong to the exchange, not to you. GhostKey cannot reach them. If you want them to be inheritable, move them to a wallet where you hold the keys first (Cake Wallet, Blue Wallet, Sparrow, or a hardware wallet). We'll show you how.
Most inheritance tools assume you can run a full node, read a script policy, and manage a multisig setup. Most people can't, and shouldn't have to.
GhostKey packages one specific, well-tested Bitcoin inheritance pattern into something you can set up in five minutes from your phone. The rules are written into Bitcoin itself. Even if GhostKey shut down tomorrow, the on-chain script would still work. Anyone holding the pre-built transaction can broadcast it once the timelock expires.
Your Bitcoin sits in a special address with two keys:
- Your key: you can spend it any time
- Your heir's key: they can spend it only after your countdown has expired
Tapping "I'm still here" resets the countdown. Stop tapping long enough, and the countdown reaches zero, at which point only your heir's key works.
No one at GhostKey can touch the funds. The rules are enforced by Bitcoin, not by this website.
Live on mainnet, early real users. The hosted app at
www.ghostkeyapp.com runs on Bitcoin
mainnet (default_network: bitcoin), with a small group of early users
holding real funds in vaults. The core cryptography is tested end-to-end
on regtest and signet, and the full owner + heir flows have been exercised
on signet and mainnet.
It has not yet had an external security review, so it is still early
software: keep amounts modest, keep your own backup of the recovery kit,
and read the threat model before trusting it with anything you cannot
afford to lose. Self-hosters default to testnet and opt into mainnet
explicitly (GHOSTKEY_DEFAULT_NETWORK=bitcoin).
The written threat model lives at docs/threat-model.md:
who can attack the system, what the design defends against, which risks
were accepted eyes-open, and the open questions for an external review.
What works today:
- Full vault setup from xpub (legacy / CLI flow) and in-browser password setup (no seed phrase shown to the user; owner xprv sealed with Argon2id-derived KEK)
- Cross-device sign-in: email + password unlocks any vault on any browser
- Multi-heir vaults (N parallel single-heir vaults grouped client-side; the dashboard fans out one tap to all of them)
- Guardian vaults for underage heirs: the claim policy is
heir AND (g1 OR g2) AND older(N), so it needs the child-heir plus one of two guardians and the timelock; no single guardian can act alone. An optional unlock-year (after(H)CLTV) holds the funds until a chosen block height. The owner can spend at any time. Verified end-to-end on signet. - Owner check-in via tap-button, one-tap email link, or Lightning (requires the optional Breez SDK Liquid sidecar; see DESIGN.md "Lightning check-ins")
- Configurable check-in cadence (weekly / 2-weekly / monthly / quarterly) and grace period (3 days / 1 week / 2 weeks / 1 month)
- Scheduler with pre-deadline reminders, daily alarm escalation, panic-stop freeze, and per-cycle one-tap tokens
- Encrypted heir / owner / trusted-contact storage. Owner-key blobs require the owner's password; the simple Door A heir-key blob is server-assisted as described below.
- Email notifications (SMTP via
lettre+ STARTTLS); SMS + WhatsApp via Twilio (optional, off by default) - Owners can change how an heir is reached after setup (contact + channel), so a vault set up on an undeliverable channel can be fixed without re-doing setup. The address must match the channel, and easy-setup (F2) heirs stay locked to their email since their key is derived from it.
- One-time claim link and two heir-claim flows:
- Password-vault flow (default): heir pastes a receive address, server signs in-memory with the just-unwrapped heir xprv, broadcasts in one call.
- Manual PSBT flow (legacy): server hands the heir an unsigned PSBT, accepts the signed string back.
- "Heir has no Bitcoin wallet" support (Door A): the browser generates the heir's key and seals it under their one-time claim token, so the heir needs no wallet or prior setup. To deliver the future link, the server stores that token encrypted under its production master key. Consequently DB + master key can reconstruct the heir key now, while CSV prevents spending until maturity. Door B is the recommended strict non-custodial option when the heir already has a wallet: only their xpub reaches GhostKey. The older server-derivation path (
derive_heir_seedover(master_key, heir_email, vault_id)) remains only for legacy claims. - In-app AI guide chat (
/assist/chat) proxied to Claude; refuses to forward seed-shaped strings - Email-verified cross-device recovery: lookup responses are uniform, recovery links expire after 15 minutes and are single-use, and sealed owner blobs are no longer publicly retrievable
- Per-IP rate limiting on unauthenticated endpoints (
/assist/chat, vault creation, recovery request/exchange, and/claim/:token/*), with per-deployGHOSTKEY_RL_*overrides (see DEPLOY.md)
What's still being built:
- Hardware wallet PSBT export (
--export-psbt/--sign-psbton the CLI) - Setup from a plain Bitcoin address (without needing an xpub)
- Translations: Pidgin first (planned), then Yoruba, Igbo, Hausa
- External mainnet security review
Built with Rust (ghostkey-core, ghostkey-cli, ghostkey-server) and React (ghostkey-web).
# Prerequisites: Rust 1.85+, Node 20+
cargo build --workspace
cd ghostkey-web && npm install && npm run build && cd ..
# Server (one terminal)
GHOSTKEY_MASTER_KEY=$(openssl rand -base64 32) cargo run -p ghostkey-server
# → http://127.0.0.1:8787
# Web app (another terminal)
cd ghostkey-web && npm run dev
# → http://127.0.0.1:5173For live demonstrations and screen recordings, the server can be started in demo mode so the entire setup → missed-check-in → alarm → claim flow finishes in well under a minute:
GHOSTKEY_DEMO_MODE=1 \
GHOSTKEY_MASTER_KEY=$(openssl rand -base64 32) \
cargo run -p ghostkey-serverIn demo mode:
- The setup wizard exposes seconds-scale cadence (10 s / 30 s / 2 min) and grace-period (5 s / 15 s / 1 min) presets.
- The scheduler tick drops to 1 s so transitions are observable in real time.
- The web UI shows a sticky amber "Demo mode" banner on every page.
- Mainnet vault creation is refused. signet / testnet / regtest only.
Do not set GHOSTKEY_DEMO_MODE on a production server. A real
owner who picked a 10-second cadence would lose access to recovery
the moment they put their phone down.
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
# End-to-end on real regtest bitcoind (~5s; also runs in CI on every PR)
cargo test -p ghostkey-core --test regtest_e2e -- --ignored
cd ghostkey-web && npm run typecheck && npm run buildcrates/
ghostkey-core/ Bitcoin logic. I/O-free. Descriptors, PSBTs, BIP68 timelocks.
ghostkey-cli/ Owner and heir CLI. Talks to Esplora or local bitcoind.
ghostkey-server/ Axum server. Vault registry, scheduler, notifier, claim broker.
ghostkey-web/ React + Vite dashboard.
The on-chain script, threat model, and design decisions are in ARCHITECTURE.md.
PRs welcome, especially on anything in the "still being built" list above, plus bug fixes, accessibility improvements, and translations. See CONTRIBUTING.md.
Security issues: SECURITY.md. Please report privately first.
License: Apache-2.0 or MIT, at your option. See LICENSE.md.