Canary Wallet is a Bitcoin monitoring and early warning system built in Rust using BDK (Bitcoin Development Kit) with a Next.js frontend. It provides real-time transaction intelligence, advanced pattern recognition (RBF, CPFP, consolidation), and instant multilingual notifications for Bitcoin wallet activity - designed specifically for monitoring cold storage and Bitcoin holdings you don't actively use.
A canary in the cold mine - When your bitcoins are in cold storage, you seldom check on them. Canary Wallet acts as an early warning system that alerts you the moment your coins move, giving you immediate notification of any activity on your wallets.
Start with a clean watch-only wallet list and add your first wallet when you are ready.
Start from an empty wallet list and add the first watch-only wallet.
Select your wallet type from popular software wallets (Sparrow, BlueWallet, Electrum) or hardware wallets (ColdCard, Ledger, Trezor). Single-sig and multisig watch-only wallets are both supported. Canary Wallet only needs read-only access to monitor transactions - your private keys stay safe in your wallet.
Add a read-only descriptor for a wallet named Test.
Follow wallet-specific instructions to export your output descriptor or XPUB. Each supported wallet has tailored guidance to make setup easy.
Follow the Sparrow-specific guide to export a descriptor safely.
View your balance in BTC and fiat and see your complete transaction history with send/receive indicators.
Monitor balances, pending activity, and transaction details from one dashboard.
Give each contact its own delivery methods, transaction rules, balance alerts, and message-content privacy level.
Review notification behavior at a glance and open the editor only when changes are needed.
Customize your language preference (9 languages supported) and fiat currency display. Exchange rates update automatically via CoinGecko.
Configure appearance, regional preferences, transaction explorer, and ntfy notifications.
- Single-sig and multisig wallets
- Output descriptors, XPUBs, and individual addresses
- No seed phrases or private keys
- Sending and receiving bitcoin notifications
- Transaction confirmation alerts
- RBF (Replace-By-Fee) detection - fee bumping notifications
- CPFP (Child-Pays-For-Parent) detection - transaction acceleration notifications
- Configurable threshold alerts (above/below/equals)
- Support for both BTC and fiat currency thresholds
- Smart crossing detection to prevent notification spam
- Auto-disable after firing with manual reactivation
Real-time notifications in 9 languages via ntfy push (default public server ntfy.sh, or a local server such as the Umbrel ntfy app), encrypted Nostr DMs, self-hosted JSON webhooks, and optional Telegram bot messages.
canarybitcoin.com additionally supports SMS (via Twilio) and Email (via Resend) notifications.
Supported Languages: English, Norwegian, Spanish, Portuguese, German, French, Japanese, Danish, Swedish
Umbrel / Docker note: On Umbrel, Canary Wallet auto-detects the local ntfy app through the Docker-internal URL provided by the Umbrel package. You should not need to enter
http://ntfy_app_1manually. Use "Send Test Notification" in Settings to verify your configuration.
With CANARY_MODE=self-hosted, custom ntfy URLs can use Docker-internal names (such as http://ntfy on a shared Docker network), LAN addresses (such as http://192.168.1.20:8080), and Tailscale addresses or MagicDNS names (such as http://100.64.0.10:8080). This works on Umbrel, StartOS, myNode, and standalone Docker without an extra flag. Existing saved private URLs work after upgrading. The Canary backend must be able to resolve the hostname and reach the server; browser access alone is insufficient. Loopback addresses refer to the backend's own network namespace. Link-local metadata and other special-purpose addresses remain blocked for custom servers. Custom self-hosted ntfy connections bypass HTTP proxy environment settings to connect directly to validated addresses. Detected integrations and operator defaults retain their existing connection behavior.
StartOS note: StartOS packages can provision a scoped local ntfy publisher and pass it to Canary Wallet with
CANARY_NTFY_SERVER_URL,CANARY_NTFY_TOKEN, andCANARY_NTFY_TOPIC. These values are used as defaults; settings saved in Canary Wallet remain authoritative.Nostr .onion relays: NIP-17 delivery to
.onioninbox relays needs system Tor (or equivalent SOCKS5). SetCANARY_NOSTR_SOCKS_PROXYto the SOCKS port, typically127.0.0.1:9050. Public clearnet relays keep using a direct connection.
| Self-Hosted | canarybitcoin.com | |
|---|---|---|
| Users | Single user, no auth required | Multi-user with email/password authentication |
| Notifications | ntfy + Nostr DM + JSON webhook + Telegram | ntfy + SMS + Email |
| Billing | Free | Subscription plans (Personal & Team) |
| Wallet sync | Fixed interval | Tier-based (faster sync on higher plans) |
- Rust toolchain (version pinned in
rust-toolchain.toml) - Node.js 18+
- Docker and Docker Compose (for local Bitcoin regtest)
# Backend - choose your mode
cd backend
cp .env.example.self-hosted .env # or .env.example.cloud
# Frontend
cd frontend
cp .env.example.self-hosted .env.local # or .env.example.cloud# Start local Bitcoin regtest environment
cd scripts && docker-compose up -d
# Start backend (requires Stripe CLI for cloud mode)
cd backend && cargo run
# Start frontend
cd frontend && pnpm devThe frontend displays the git version and commit hash in the footer. To generate this build info locally:
# Generate build info (creates src/lib/build-info.json)
cd frontend && node scripts/generate-build-info.js
# Then start the dev server
pnpm devThe footer will display in format: v0.13.0 • 5e66fe3 (tag and commit) or just the commit hash if no tag exists.
Note: The build info is automatically generated during production builds via the webpack configuration. For local development, you need to run the script manually.
The Rust toolchain is pinned in rust-toolchain.toml, together with clippy and rustfmt; rustup installs it on first use. From the repository root, run the backend checks:
.agent-loop/checks.sh backendThis is equivalent to:
cd backend
cargo fmt --check
cargo clippy --all-targets --features system-tests -- -D warnings
cargo testCI also builds the documentation with warnings denied:
cd backend && RUSTDOCFLAGS="-D warnings" cargo doc --no-depsSee backend/ARCHITECTURE.md for an overview of the backend.
System tests start Bitcoin Core and Fulcrum in Docker on regtest, send real transactions and check the events Canary records. They need Docker and the docker-compose command. They are only built with the system-tests cargo feature, so cargo test skips them.
cd backend
./run-system-tests.sh # runs the standard scenarios one file at a time
./run-system-tests.sh --nocapture # same, with full test outputhigh_index_scanning is excluded from the runner because it currently hangs (#633). See backend/system_tests/README.md for the full list of scenarios and how to run a single file or test.
See backend/ARCHITECTURE.md for the backend architecture: process layout, sync and notification flow, storage, error handling and testing.
agent-reference.md and backend/agent-reference.md collect API endpoints, environment variables, database notes and development commands.
See JSON webhook notifications for the self-hosted webhook contract and deployment guidance.
See Telegram Bot notifications for bot token setup and destination rules.
See LICENSE.md for license information.