OrangeRails
The open-source rails for Bitcoin financial data.
Open-source, self-hostable, Bitcoin-native.
Architecture ·
Contributing ·
Security
Why this exists
"Here we are faced with the problems of loss of privacy, creeping computerization, massive databases, more centralization, and [David] Chaum offers a completely different direction to go in, one which puts power into the hands of individuals rather than governments and corporations. The computer can be used as a tool to liberate and protect people, rather than to control them."
Hal Finney, cypherpunks mailing list, November 1992
Thirty-four years later, every financial data aggregator in existence still operates the way Finney warned against.
Plaid, Finicity, Teller, TrueLayer, Yodlee, MX, Mesh Connect, Vezgo: every one of them stores user credentials in a form their servers can decrypt. That makes each of them a high-value target. A single breach can expose tens of millions of users' financial histories in plaintext.
In 2022, LastPass was breached. Attackers exfiltrated encrypted vaults and spent the next three years brute-forcing weak master passwords. In March 2025, federal prosecutors linked a $150 million cryptocurrency heist directly to that breach.
Plaid itself has never publicly disclosed a breach. As one Hacker News commenter put it in 2021:
"Plaid is only one security breach away from being utterly destroyed." (HN, August 2021)
Orange Rails exists so that the next generation of Bitcoin apps does not have to repeat that mistake. The server holds ciphertext. The keys live with the user.
What Orange Rails is
Orange Rails is the open-source rails for Bitcoin financial data. Apps integrate once, customers connect their wallets, exchanges, Lightning nodes, and banks, and the data flows back to the app. Provider credentials are encrypted on the user's device and stored as ciphertext under a key we do not keep. On the client sealed path the server never sees transaction content. On the managed sync path the calling application supplies the key with the request, the server decrypts in memory for that request, and it keeps no key afterwards.
What ships in this repository:
- API gateway. A Cloudflare Worker that exposes a stable, versioned HTTP surface at
api.orangerails.com and proxies to the backend.
- Edge functions. Supabase Edge runtime that handles connect flows, sync orchestration, webhook receivers, and per-platform isolation.
- SDKs. Typed clients for integrators, published from
packages/.
- Stealth Sync widget. The drop-in connect widget that runs the in-browser key derivation and encrypts credentials before they leave the device.
For the full reference, including the session-based zero-knowledge boundary, the hybrid post-quantum key wrapping, and the BIP 158 compact block filter design for on-chain wallets, read docs/OrangeRails-Architecture.md.
Who uses this today
Two production apps consume Orange Rails today. Both are sibling projects under the same ownership, which is how the API gets exercised end to end before it is asked to support unaffiliated integrators.
- BitBooks. Bookkeeping on a Bitcoin standard. The first consuming app, and the reason the bank, Lightning, and exchange adapter set looks the way it does. bitbooks.com
- Orange Way. A personal-finance manager and a personal-bookkeeping app in the same family. Drives the consumer side of the connect flow and the mobile-friendly widget surface.
Adding your app is the v0.1 path. The contract is the same one BitBooks and Orange Way use. If you want to be the third integrator, open an issue and say hello.
Quick start (for integrators)
git clone https://github.com/Orange-The-World/orangerails
cd orangerails
npm install
bash scripts/install-git-hooks.sh
npm run dev
You will need a Supabase project, a Cloudflare account for the Worker, and a Bitcoin or banking provider key for whichever adapter you want to exercise first (Blink and Quiltt are the easiest starting points). Copy .env.example to .env.local and fill in what is marked required.
Before you ship anything against a real customer, read SECURITY.md and docs/OrangeRails-Architecture.md. The integration contract assumes you understand which side of the encryption boundary your code is running on.
Self-host in under 30 minutes
The same code that runs the hosted Orange Rails runs on your own infrastructure. The supported self-host stack is:
- Cloudflare Pages for the frontend and the widget.
- Supabase (hosted or self-hosted) for the database, auth, and edge functions.
- One Cloudflare Worker for the public API surface at your chosen domain.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
