Home Getting Started

Getting Started

Start here.
By Miguel Abascal
• 8 articles

Getting started with Orange Way

Getting started with Orange Way Family budgeting on Bitcoin. Privacy by default, household-friendly by design. This walks you through signing up, unlocking your vault, and seeing your first connected account. What Orange Way is for Orange Way is a household budgeting app that runs on Bitcoin instead of a bank. Two parents (or roommates, or a couple, or anyone sharing money) can: - See a combined household balance without either party exposing their wallets to a third party. - Set monthly goals — savings, bills, restaurant spending, kids' allowance — and watch them tick down. - Bring in an accountant or auditor with read-only access without giving up your keys. - Stay private. Orange Way cannot see your transactions, balances, or counterparties. Same architectural reason as a password manager: ciphertext at rest, decryption in your browser. Sign up 1. Go to orangeway.app and click Sign up. 2. Use the email you'd like associated with your account. Email confirmation lands in your inbox within ~30 seconds. 3. Pick a vault password. This is the root of your account's privacy. We cannot reset it. Write it down somewhere safe, or save the Shamir recovery share (2 of 3) the app generates at vault setup. Without one of these, your data is unrecoverable. That's the entire signup. No phone number, no SSN, no bank login. Unlock your vault Every time you open Orange Way, you'll enter your vault password. The app derives an encryption key from it (Argon2id, takes about one second on a modern phone or laptop) and unlocks everything in the browser. The key never leaves your device. If you've enabled biometric quick-unlock on your phone, the vault password still applies behind the scenes — biometrics just authorize the app to use the key it already derived on first sign-in. Set up your household In Settings → Household, invite a partner by email. They sign up the same way, and you link the two accounts with a one-time household key exchange (it takes about three taps). After that, every transaction either of you records, every connected wallet, and every monthly goal is shared between you — but only between you. Orange Way still sees ciphertext. Add more members for kids (read-only mode is the default for sub-accounts under 18), an accountant (see "Bring in an auditor or accountant"), or a roommate. Connect a wallet Orange Way talks to Bitcoin wallets, exchanges, and payment processors through Orange Rails, the open-source connector platform. Click Add a connection in the dashboard, pick your wallet from the catalog of 100+ supported sources, and either: - Paste an API key (for exchanges and payment processors), or - Paste a watch-only xpub (for on-chain Bitcoin wallets like Sparrow, Specter, Ledger, BlueWallet, etc.) The Connect widget encrypts your credential in your browser before it reaches Orange Way. Even Orange Rails — the connector — only sees the bytes needed to call the upstream wallet. Full breakdown of the privacy model: Privacy and what we cannot see. See your first transactions Once a wallet is connected, click Sync now (or wait — Orange Way syncs in the background every hour). Transactions appear in your dashboard, categorized by your household rules, and folded into your monthly goal progress. The first sync of a long-history xpub can take ~30 seconds while the browser scans BIP 158 filter files. Subsequent syncs are quick because each one only checks new blocks. What's next - Set up your household budget — categories, monthly goals, member roles - Privacy and what we cannot see — the architecture in plain English - Bring in an auditor or accountant — Phase 4.4 Auditor role for read-only third-party access Need help? - Something broke → support.orangeway.app (this site) - Feature request → feedback.orangeway.app (tag: orange-way) - Security issue → security@bitbooks.com

Last updated on May 16, 2026

Set up your household budget

Set up your household budget Categories, monthly goals, and household members. The pieces that turn Orange Way from a transaction list into a budget you can actually run. The mental model Orange Way thinks of your household budget in three nested pieces: 1. Categories — the buckets your money lives in (Groceries, Rent, Kids, Bitcoin savings, Coffee, etc.). You pick them. 2. Monthly goals — how much you want to spend or save in each category this month. Optional. If you don't set a goal, the category just tracks totals. 3. Members — the humans + read-only third parties who can see and (optionally) edit. Always at least one: you. A transaction belongs to a category. A category may belong to a goal. A goal lives in a month. Months roll over automatically. Add categories In Budget → Categories, click Add category. Pick: - Name — "Groceries", "Bitcoin DCA", whatever you say in real life. - Color — purely cosmetic, helps the chart. - Default goal (optional) — if you set this, every new month auto-creates a goal in this category with this amount. - Visibility — by default, household members all see this category. You can mark a category author-only (only the member who created it can see it) for things like personal one-off spending. We added this in the Phase 4.4 release; it's a per-category toggle. Categories can nest (Groceries → Coffee, Groceries → Restaurants). Two levels deep, no more. Set a monthly goal In Budget → Month view, click any category and pick Set goal. Enter: - Amount — denominated in sats, BTC, USD, or your local currency. We convert at the day's median rate when needed. - Direction — "spend at most" (default for expenses) or "save at least" (for savings categories). The dashboard shows you week-by-week progress against the goal, in plain "you have $230 left to spend on groceries this week" English. No financial jargon. Invite a member In Settings → Household, click Invite member. They get an email with a one-time link. When they click it: 1. They sign up (or sign in if they already have an account). 2. The app does a one-time household key exchange — they generate a key, you both confirm a six-digit code in person to make sure no one's in the middle, and the household master key gets wrapped for them. 3. After that they see everything you see, including all past transactions. Roles today: - Owner — full control, can invite/remove members, change household settings. Usually the first person to set up the household. - Member — read + write transactions, set goals, see everything except billing. - Read-only — see everything, change nothing. Default for kids under 18 and for auditors/accountants. Roll over months Every month rolls automatically on the 1st of the next month. Unfinished goals copy forward by default (you can disable per-category). Leftover budget from "spend at most" categories disappears (unless you flip the carry over toggle on the category). Unmet "save at least" goals show as red in the rolling summary. You can also rename a month to mark it ("April 2026 — bought the truck") for searchability later. Categorize transactions When a sync brings in new transactions, Orange Way applies your category rules first (e.g. "anything from Whole Foods → Groceries"). Anything that doesn't match shows up in an Uncategorized bucket on the dashboard. You click each one, pick a category, and the next time a similar transaction comes in, Orange Way remembers. Rules are local (per household). They never get shipped to Orange Way's servers in plaintext — same encryption-in-browser model as the rest of the app. See also - Connect a wallet — get transactions flowing in - Privacy and what we cannot see — why the household key exchange matters - Bring in an auditor or accountant — read-only third-party access

Last updated on May 16, 2026

Connect a Bitcoin wallet

Connect a Bitcoin wallet Orange Way doesn't talk to wallets directly. It uses Orange Rails, the open-source connector platform, to fetch your transactions in a privacy-preserving way. This explains how that works and what each connection method gives up. What gets connected You can connect: - Bitcoin xpub (watch-only) — pasted from Sparrow, Specter, Ledger, BlueWallet, BitBox, Coldcard, anything that exports an xpub/ypub/zpub. Recommended because it's the most private option. - Exchanges — Coinbase, Kraken, Binance, Bybit, OKX, KuCoin, Gemini, Bitstamp, Bitfinex, Crypto.com, NDAX, Bitbuy, and ~85 others through the CCXT bridge. Read-only API keys. - Lightning wallets — Blink, Strike, BTCPay Server (for merchants). What you cannot connect today (on the public roadmap): - Traditional banks (coming via Quiltt or Plaid as a Tier 2 source — discloses to a third party, see Privacy). - Mining pools (Ocean, Braiins, ViaBTC). - Lightning node software (LND, CLN, LDK, Phoenix) — direct. How a connection works, step by step 1. Click Add a connection in your Orange Way dashboard. 2. The Orange Rails Connect widget opens in a popup. It runs at connect.orangerails.com — a separate domain so the credentials never touch Orange Way's main domain in memory. 3. Pick your source (xpub, Coinbase, Blink, etc.). 4. Enter the required credential: - For an xpub: paste the extended public key. We support xpub, ypub, zpub prefixes (BIP 44 / 49 / 84). Multisig descriptors are on the roadmap. - For an exchange: paste the API key + secret + (sometimes) a passphrase, generated in the exchange's dashboard with read-only scopes. - For Blink/Strike: paste the API token (read-only invoice scope). 5. The widget encrypts your credential in the browser using a key derived from your Orange Way vault password. Even the Orange Rails server never sees the plaintext credential. The encrypted bytes get stored. 6. The widget closes. Your new connection appears in the Orange Way dashboard. 7. First sync runs automatically. New transactions roll in within ~30 seconds for most sources; an xpub with a long history can take ~90 seconds the first time. Privacy tiers (T0 → T3) Orange Rails publishes a privacy tier per source so you know upfront what each connection costs you in disclosure. Orange Way surfaces the tier badge before you connect. | Tier | Plain English | Example sources | |---|---|---| | T0 — Just you | No third party sees your activity. The browser scans the chain locally. | xpub (via Stealth Sync) | | T1 — You and the wallet | The wallet/exchange already sees your activity. We don't add new exposure. | Coinbase, Strike, Blink | | T2 — Powered by an aggregator | A third party (Quiltt, Plaid) sees the data because banks don't expose APIs directly. | Traditional bank connections (roadmap) | | T3 — Manual upload | You decide what to share. | CSV / OFX file imports (roadmap) | If you want maximum privacy, stick to T0 (xpub) and T1 (the wallets you already trust). T2 only exists for bank connections because there's no other way today. What if I change my mind Connections are deletable. In Settings → Connections, click the trash icon next to any source. Two things happen: 1. Orange Rails stops syncing it (immediately). 2. The encrypted credential is deleted from Orange Rails' database (immediately). The historical transactions you already pulled in stay in your household budget — they're yours. If you want to also delete the history, click Delete transactions on the connection before you remove it. Troubleshooting - xpub didn't find my transactions — make sure you exported the xpub from the right derivation path. BIP 84 wallets (the common modern default) need a zpub, not an xpub. Sparrow's "Settings → Wallet" view shows you the right one. - Exchange API key is invalid — most exchanges require the IP that calls the API to be allow-listed. Orange Rails' egress IP is documented at api.orangerails.com/info (you set it in the exchange's API key settings). - Sync is slow — first sync of an xpub does a full block scan via BIP 158 filters. Normal. Later syncs only check new blocks. See also - Privacy and what we cannot see — the architectural deep dive - Getting started — sign up + first wallet in 10 minutes - The full Orange Rails source catalog: https://orangerails.com/providers (100+ connections)

Last updated on May 16, 2026

Privacy and what we cannot see

Privacy and what we cannot see Orange Way is built so that we cannot read your data, by the architecture. Not by promise. This walks through exactly what's protected, exactly what's not, and what assumptions you have to accept to use the app. The one-sentence version Your transactions, balances, categories, household members, and goals are all encrypted in your browser before they ever reach our server. We hold ciphertext only. A breach of our database leaks scrambled bytes, not your financial life. What we cannot see - Transaction amounts. Stored as encrypted_payload per record. - Counterparty names. "Whole Foods", "Alice", whatever you typed — encrypted. - Memos and descriptions. Same. - Categories. Your "Coffee" bucket and your "Bitcoin DCA" bucket — encrypted. - Wallet addresses. Even on the Orange Rails side, xpub-derived addresses never leave your browser thanks to Stealth Sync. - Goal amounts. The $400 grocery budget — encrypted. - Household member identities beyond their account email. The link from "this account belongs to this household" is in the database; who you call them and how they relate to you (spouse, kid, accountant) is not. What we can see - Account metadata — email, signup time, last-active timestamp. Needed for billing + login. - Connection types — that you have an xpub connection and a Coinbase connection, for example. We need this to route your syncs. The credentials themselves are encrypted. - Sync timing — when your last sync ran, whether it succeeded. Needed for ops + customer support. - Aggregate counts — total number of transactions, number of categories — but not their contents. - Anything you tell support — if you open a support ticket and paste a screenshot, we see what's in the screenshot. Same as any other support channel. How the encryption works (plain English) 1. When you sign up, you pick a vault password. The app derives an encryption key from it using Argon2id (memory-hard, takes about a second on a modern device). 2. Every time you write something to Orange Way — a transaction, a category, a goal — the app scrambles it with that key in the browser before sending it. 3. The server receives opaque bytes. It stores them. 4. When you sign in, you re-enter the vault password, the app re-derives the key, and unlocks everything in memory. 5. The key never leaves your device. We don't have it. We can't recover it. Household sharing (how partners see the same data) When you invite a partner, the app does a one-time key exchange: 1. They sign up and get their own vault password (different from yours). 2. You both meet a six-digit code on screen to confirm no one is in the middle (a man-in-the-middle attacker would see different codes on each device). 3. The household master key (which actually encrypts the shared data) gets re-wrapped for them, using their key. 4. From that point on, both of you can decrypt the household data with your own vault password. If a partner loses their password, you can re-share with them as long as one of you still has access. If you both lose access, you need the Shamir recovery share (the PDF/QR you saved at vault setup) to recover. What we cannot protect against - A compromised device. If malware reads your keyboard, it sees your vault password. Endpoint security is on you. - A phished password. Same. We can't tell the difference between you and someone holding a gun to your head. - An upstream wallet/exchange breach. Coinbase getting hacked doesn't leak Orange Way's data — but it does leak whatever Coinbase already had on you. We can't help with that. - A subpoena. We will comply with valid legal orders, but we can only hand over what we have: ciphertext, metadata, billing info. We cannot decrypt your data for law enforcement because we don't have your key. Auditor and accountant access You can give an auditor (CPA, family lawyer, etc.) read-only access to a defined slice of your household data. They get their own Orange Way account, the household key gets wrapped for them, and they can see whatever you scope to them — but they can't write, edit, or share with anyone else. Audit log records every read. This is the Phase 4.4 Auditor flow. Detailed setup: Bring in an auditor or accountant. What to do if you lose your vault password 1. Find your Shamir recovery share (the PDF/QR Orange Way generated at vault setup — you should have stored it offline). 2. Sign in with email confirmation, then use the recovery flow with your share + one of the two backup shares (your household partner, or Orange Way's emergency recovery share if you opted in to that at signup). 3. Set a new vault password. The household master key gets re-wrapped under the new password. If you don't have a recovery share and no household partner with access, your data is unrecoverable. Same as a hardware wallet seed — that's the trade-off for true zero-knowledge. Independent verification - Cryptographic audit — planned. Trail of Bits or NCC Group when Orange Way hits 1.0. - SOC 2 — planned post-1.0 for the hosted service. - Source code — Apache 2.0 at github.com/MorningRevolution/orange-way. Audit it yourself or hire someone to. You don't have to trust this page. You can verify everything in the source.

Last updated on May 16, 2026

Bring in an auditor or accountant

Bring in an auditor or accountant Give a CPA, tax preparer, or family lawyer read-only access to a defined slice of your household budget. They never see your vault password. Every read is logged. You can revoke any time. When you'd use this - Your CPA does your taxes. You want them to see your Bitcoin transactions for the year without sharing your vault password. - You're divorcing and the court wants financial transparency for a specified date range. - You're applying for a mortgage. The lender wants statements but not API access to your wallets. - You hire a bookkeeper for the household budget but don't want them touching the categories or goals. In each case the auditor needs read-only access to a defined scope, with an audit trail. That's what this flow is for. How it works 1. In Settings → Auditors, click Invite auditor. 2. Enter their email and pick the scope: - Date range — e.g. "January 1 to December 31, 2026" - Categories — all categories or just specific ones (e.g. only "Tax-deductible expenses") - Members — your transactions only, or the whole household 3. Set an expiry — by default the access auto-revokes 90 days after invite. You can set a longer or shorter window. 4. Click Send invite. They get an email with a one-time link. When they click the link: 1. They create an Orange Way account (or sign in if they already have one). 2. The app does a special key exchange — they generate a key pair, you both confirm a six-digit code, and your household master key gets re-wrapped for them with read-only flags baked into the wrap. 3. They land in a view that looks like Orange Way's normal dashboard, except every "edit" button is disabled and every page shows the scope they were granted. The auditor cannot: - Add transactions - Change categories or goals - Invite other auditors - See data outside the scope you set - Take your data with them (no export endpoint for auditors today; planned for Phase 5) What gets logged Every page the auditor views creates an audit-log row: - Auditor email + IP - Page or article viewed - Timestamp - Scope tag (which range/categories they read) You see the auditor's activity in Settings → Auditors → Audit log. The log is append-only and cannot be deleted by the auditor (or by us). Revoke access In Settings → Auditors, click Revoke next to any auditor. Two things happen: 1. The auditor's session token is invalidated immediately. 2. The wrapped household key is deleted for them. Even if they had a stale browser session, the next request fails. Revoke is irreversible — to re-grant, send a new invite. Common questions Can the auditor share my data with someone else? Not through the app. The data only decrypts in their browser session with their vault password. There's no export endpoint for auditor accounts. If they screenshot, copy, or write down what they saw, that's outside the app — same as any other read-only relationship. Can I give my CPA permanent access? Yes, set the expiry to a very long date (or no expiry). But we recommend setting an expiry by default — most accounting relationships have natural cycles (annual, quarterly). Can I give the auditor write access? No. Auditor role is read-only by design. If you want a bookkeeper who can categorize and edit transactions, use the Member role instead (it's a full household member). What about my partner — do they see the auditor's audit log? Yes. Auditors are household-scoped, so every household member (owner + members) sees the same audit log and can revoke the auditor. See also - Privacy and what we cannot see — why read-only is actually read-only - Set up your household budget — the member roles - The Phase 4.4 architecture deep dive: wiki.abascal.ca/Apps/🍊 Orange Way/Phase 4 Household Design

Last updated on May 16, 2026

Self-host Orange Way

Self-host Orange Way Orange Way is Apache 2.0. The hosted version at orangeway.app runs the same code as the public repo — there's no closed enterprise fork. This is the guide for running it on your own infrastructure. Who self-hosts - Privacy maximalists who want zero ops trust. - Households that want to keep all data inside their own home network. - Developers building on top of Orange Way's API. - Cypherpunks for whom "open source" means "open source AND I run it." Architecture in 30 seconds Orange Way is a Vite SPA + a Supabase backend (Postgres + edge functions). It uses Orange Rails as its connector layer — you can either point at the hosted Orange Rails or run your own. [ your browser ] ↓ [ your-self-host.example.com ] ← static Vite SPA on Cloudflare Pages or any static host ↓ (Supabase JS SDK) [ your Supabase project ] ← Postgres + edge functions ↓ (X-Platform-API-Key) [ Orange Rails ] ← hosted (api.orangerails.com) or self-hosted ↓ [ Coinbase / Blink / Kraken / xpub / etc. ] Quick start (Supabase Cloud path) The fastest path. Free tier covers a household of 4 with plenty of room. 1. Fork the repo gh repo fork MorningRevolution/orange-way --clone=true cd orange-way 2. Create two Supabase projects In the Supabase dashboard, create <yourname>-dev and <yourname>-prod. Note both project refs. 3. Apply migrations supabase link --project-ref <your-dev-ref> supabase db push Repeat for prod. 4. Get an Orange Rails platform API key - Hosted Orange Rails (recommended for first try): sign up at orangerails.com, go to Settings → API tokens, generate a token. Note your platform ID. - Self-hosted Orange Rails: see the Orange Rails self-hosting guide. 5. Configure your fork GitHub Actions repo variables: VITE_SUPABASE_PROJECT_ID_DEV = <your-dev-ref> VITE_SUPABASE_URL_DEV = https://<your-dev-ref>.supabase.co VITE_SUPABASE_PUBLISHABLE_KEY_DEV = <your-dev-anon-key> VITE_SUPABASE_PROJECT_ID_PROD = <your-prod-ref> VITE_SUPABASE_URL_PROD = https://<your-prod-ref>.supabase.co VITE_SUPABASE_PUBLISHABLE_KEY_PROD = <your-prod-anon-key> VITE_OR_SUPABASE_URL = https://api.orangerails.com (or your self-host) VITE_OR_PLATFORM_ID = <your-orange-rails-platform-id> Repo secrets: CLOUDFLARE_API_TOKEN = <your-cf-token-with-pages-edit> CLOUDFLARE_ACCOUNT_ID = <your-cf-account-id> 6. Create two Cloudflare Pages projects In the CF dashboard, create <yourname>-dev and <yourname>-prod. Don't connect them to Git — the GitHub Actions workflow handles deploys. 7. Push git push origin dev # auto-deploys to dev # verify, then git checkout prod && git merge --ff-only dev && git push origin prod Within ~60s your dev site is live. Fully self-hosted (no Supabase Cloud, no Cloudflare) The repo ships with docker-compose.yml to run Supabase locally and a Caddy reference config. The dist build is static; any web host works. git clone https://github.com/MorningRevolution/orange-way cd orange-way docker compose up -d # Postgres + Kong + GoTrue + PostgREST + Realtime supabase db push --db-url postgres://... bun install && bun run build # serve dist/ from your reverse proxy of choice (Caddy/nginx) Reference Caddy block: caddy/Caddyfile.example. Branch model dev is staging; prod is live. No main. Lovable (or your IDE) commits to dev. Promote with git merge --ff-only origin/dev on prod. Full breakdown: Branch flow — dev and prod. Upgrades git remote add upstream git@github.com:MorningRevolution/orange-way.git git fetch upstream git checkout dev && git merge upstream/dev && git push origin dev # verify git checkout prod && git merge --ff-only dev && git push origin prod Backup Same as any Supabase / Postgres deployment. Data at rest is ciphertext — backups are also opaque. Back up your age key off-server, otherwise a database backup is useless. Reference script: scripts/backup-vault.sh (writes encrypted dumps to S3-compatible storage). Help - Self-hosting questions → feedback.orangeway.app (tag: ow-self-host) - Security issues → security@bitbooks.com - General support → support.orangeway.app

Last updated on May 16, 2026

Contributing

Contributing Orange Way is Apache 2.0. PRs welcome. This page covers the repo conventions, branch model, and what to know before opening a PR. Branch model Two branches, two URLs. No main. dev ← Lovable + agents + PRs land here; auto-deploys to dev.orangeway.app prod ← merged from dev when ready; auto-deploys to orangeway.app (live) Full breakdown: Branch flow — dev and prod. Promotion command (run after dev verification): git fetch origin git checkout prod git merge --ff-only origin/dev git push origin prod PR conventions - Open against dev (the GitHub default branch — should auto-select). - Commit format: type(scope): subject. Types we use: feat, fix, chore, docs, ci, copy, refactor, test. - Maintainer squash-merges by default; single-commit PRs are easier to review. - CI must pass (bun run build, type check, the M-suite Playwright tests for any UI change). Setting up locally gh repo clone MorningRevolution/orange-way cd orange-way bun install bun run dev # localhost:8080 For backend work (edge functions, migrations), you'll need a Supabase project. Either: - Use the hosted dev project (ask a maintainer for read access). - Run Supabase locally via supabase start. Copy .env.example to .env and fill in: VITE_SUPABASE_URL=https://<dev-ref>.supabase.co VITE_SUPABASE_PUBLISHABLE_KEY=<anon-key> VITE_SUPABASE_PROJECT_ID=<dev-ref> VITE_OR_SUPABASE_URL=https://api.orangerails.com VITE_OR_PLATFORM_ID=<orangeway-platform-id-on-or-dev> Repo layout src/ routes/ TanStack Router file-based routes components/ UI components context/ React contexts (VaultContext, AuthContext, etc.) hooks/ React hooks lib/ Pure utilities (crypto, vault, HSK, OSK, etc.) pages/ Page-level components integrations/ Supabase client + types supabase/ functions/ Edge functions (signup, household-invite, hsk-mint, etc.) migrations/ Versioned SQL (idempotent guards required) scripts/ Build helpers, test runners, CCXT manifest generators tests/ Playwright + Vitest Code style - TypeScript everywhere. Avoid any. - Plain English in user-facing copy. No "rotate", "encrypt", "decrypt" — say "lock", "open the box", "scrambled bytes" instead. - No em-dashes in user-facing copy. Commas, periods, parentheses. - No compound-word hyphens in user-facing copy ("customer facing", not "customer-facing"). - Tests for any new edge function (Vitest). UI changes that hit a flow get a Playwright test in the M-suite. Privacy is non-negotiable PRs that break zero-knowledge will be rejected. The architectural rule is server stores ciphertext only for transactions, balances, categories, goals, household relationships. Vault password, HSK, OSK never leave the browser. If you're adding a new feature that touches user data, the default question is: can the server see this? If yes, you need a different design. Ask in a PR draft before going deep. What we don't accept yet - PRs that move plaintext data server-side. - PRs that add a hard dependency on a non-free service without a self-host fallback. - PRs that change the public API in breaking ways without a deprecation cycle. - Massive PRs (>500 lines net) without a prior design discussion — open an issue or a draft first. Discussion - Feature requests → feedback.orangeway.app (tag: orange-way) - Support → support.orangeway.app - Security issues → security@bitbooks.com License Apache 2.0. See LICENSE in repo root.

Last updated on May 16, 2026