Cowrie Research

btpay-primary-sources-2026-05-03

3 min read

BTPay primary sources — 2026-05-03

Project status in this pass

  • No canonical standalone BTPay whitepaper or litepaper surfaced.
  • The clearest current source of truth is the official site, the repository README, and the first-party API / configuration / deployment docs.
  • The project is best understood as a self-hosted merchant-payments control plane with a deliberately lightweight architecture, not as a hosted payment gateway.

Primary-source snapshots

1) Official site / top-level positioning

  • URL: https://btpay.org/
  • Key excerpt:
    • The site describes BTPay as a “Self-hosted Bitcoin payment processor” with “No third parties. No monthly fees. Full control of your keys.”
    • It links directly to quick start, API reference, configuration, and deployment docs, which suggests the first-party surface is operator-focused rather than marketing-heavy.
    • It also calls BTPay a “lightweight, privacy-focused alternative to BTCPay Server.”

2) Repository README / product surface

  • URL: https://raw.githubusercontent.com/btpay-org/btpay/master/README.md
  • Key excerpt:
    • The README says BTPay supports onchain Bitcoin via xpubs, output descriptors, and static address lists; BTCPay Server and LNbits integrations; stablecoins; wire transfer; invoices; payment links; storefronts; donation pages; team access; and REST API/webhooks.
    • It emphasizes privacy features like no telemetry, Tor-friendly SOCKS5 support, and reproducible builds.
    • It also states that the project is “Alpha Software,” which matters when interpreting maturity and deployment risk.

3) API reference / merchant integration surface

  • URL: https://raw.githubusercontent.com/btpay-org/btpay/master/docs/API.md
  • Key excerpt:
    • The API docs expose invoice creation/finalization/status, payment links, exchange-rate endpoints, and webhook registration.
    • Webhooks use HMAC-SHA256 signatures and a documented retry schedule.
    • The API is rate-limited to 100 requests per minute per API key, reinforcing that BTPay is meant to be integrated into real merchant workflows.

4) Configuration reference / privacy and chain support

  • URL: https://raw.githubusercontent.com/btpay-org/btpay/master/docs/CONFIGURATION.md
  • Key excerpt:
    • The docs show configurable SOCKS5/Tor routing, custom mempool endpoints, Electrum servers, rate limits, autosave/backup intervals, and update controls.
    • Stablecoin monitoring is documented across Ethereum, Arbitrum, Base, Polygon, Optimism, Avalanche, Tron, and Solana.
    • Supported tokens include USDC, USDT, DAI, and PYUSD.

5) Deployment docs / operating model

  • URL: https://raw.githubusercontent.com/btpay-org/btpay/master/docs/DEPLOYMENT.md
  • Key excerpt:
    • The deployment guide targets Linux/FreeBSD with Gunicorn, Nginx, and systemd.
    • It explicitly says production should use a single Gunicorn worker because the app uses an in-memory data store with JSON persistence.
    • The docs also describe self-update, rollback, backup, optional Tor hidden-service exposure, and service hardening flags like ProtectSystem=strict and NoNewPrivileges=yes.

Working conclusion

BTPay is best cataloged as a sovereign merchant-payments control plane. The deciding evidence in this pass was the combination of self-hosted custody boundaries, invoice/storefront/payment-link workflows, API + webhook integrations, privacy-preserving verification options, and an intentionally lightweight single-worker architecture. It is closer to a compact operator-run payments appliance than to a hosted gateway or a simple donation-page script.

Graph View