A self-hosted, non-custodial Bitcoin payment processor for Fractal Bitcoin (FB) — an independent open-source fork of BTCPay Server.
-ee7a1c){kind=icon}
SoloSatPay is an independent fork of BTCPay Server, adapted for Fractal Bitcoin. It is not affiliated with or endorsed by the BTCPay Server project. BTCPay Server, NBXplorer and NBitcoin are MIT-licensed; SoloSatPay keeps their copyright notices (see
NOTICE). Built by The Lonely Bit.
Fractal Bitcoin is a near drop-in fork of Bitcoin Core (30-second blocks,
near-zero fees, OP_CAT). SoloSatPay teaches the battle-tested BTCPay stack to speak Fractal, so any
merchant can accept FB with zero processor fees, no custody, and no KYC — and a much faster, cheaper
checkout than Bitcoin L1.
This repo is a distribution + customization layer: it pins the upstream projects, applies the small
set of changes that add Fractal Bitcoin (FB) support and SoloSatPay branding, and runs the whole stack
with Docker.
fractald (Bitcoin Core fork) ──RPC+P2P──> NBXplorer (FB chain) ──> BTCPayServer (FB + SoloSatPay) ──> PostgreSQL
Fractal reuses Bitcoin's address encoding byte-for-byte, so adding it is a clone of the Bitcoin
definition at each layer (see docs/FRACTAL.md and docs/ARCHITECTURE.md). The net-new code is small
and lives in src/ (plus patches/ for the few modified upstream files).
Requires Docker + git. (x86_64 Linux; the pinned fractald release binary needs glibc ≥ 2.34.)
./scripts/build.sh # clones pinned upstreams, applies patches, downloads fractald
docker compose up -d # fractald + postgres + nbxplorer + btcpay
# wait ~3-5 min for first build, then:
open http://127.0.0.1:23000 # SoloSatPay UI (regtest)The first registered user becomes admin. For mainnet/testnet, change BTCPAY_NETWORK/NBXPLORER_network
in docker-compose.yml and point the node at a synced fractald (mainnet ~2 TB; testnet ~300 GB).
| Layer | File | Change |
|---|---|---|
| NBitcoin | src/nbitcoin/FractalBitcoin.cs |
FB network (main/test/regtest): magic, ports, genesis, addressing |
| NBXplorer | src/nbxplorer/NBXplorerNetworkProvider.FractalBitcoin.cs |
registers FB (MinRPCVersion 300) |
| BTCPayServer | src/btcpayserver/AltcoinsPlugin.FractalBitcoin.cs |
FB payment network, on-chain only |
| Rates | src/btcpayserver/CoinGeckoRateProvider.cs |
re-adds CoinGecko so FB can be priced in fiat (FB_BTC = coingecko(FB_BTC), BTC_X via the store's exchange) |
| Branding | src/btcpayserver/branding/ |
SoloSatPay logo, dark-first amber theme, X/Telegram links, fork attribution, BTCPay backers removed |
The exact upstream commits and modified files are in patches/ (applied by scripts/build.sh).
- Fiat pricing: FB is priced via CoinGecko (id
fractal-bitcoin). The free endpoint works; for higher limits setSSP_COINGECKO_APIKEY(uses CoinGecko Pro). BTC↔fiat comes from the store's chosen exchange (e.g. Kraken). Invoices can be created directly inFB(no rate lookup) or any fiat. - Social links point to
x.com/fractal_tlbandt.me/fractalbits(edit_Footer.cshtmlto change). - Auth: use API keys for automation — BTCPay rate-limits HTTP Basic auth.
Fractal mainnet/testnet addresses are byte-identical to Bitcoin addresses — indistinguishable by
string. SoloSatPay disambiguates strictly by the FB crypto code. Never rely on address format to tell
the chains apart; sending BTC to an FB-intended address (or vice-versa) moves funds on the other chain.
SoloSatPay is free and open-source — no fees, no custody. If it's useful to you, donations keep it maintained and independent:
bc1qah3mera2nqy9cyyj5j5j46y5r5v334f48yjmgz
This one address works for both BTC (Bitcoin) and FB (Fractal Bitcoin) — the address encoding is identical across the two chains, so send on whichever you prefer (funds land on the chain you broadcast to). Follow and reach us on X and Telegram.
MIT (see LICENSE). Includes MIT-licensed work from BTCPay Server, NBXplorer and NBitcoin — see NOTICE.