# BTCPay Server

Self-hosted Bitcoin payment processor with invoices, POS apps and the Greenfield REST API.

BTCPay Server lets a business accept on-chain Bitcoin and Lightning payments without an intermediary: stores, invoices, payment requests, pull payments and payouts, a point-of-sale app and crowdfunding pages. The Greenfield API covers nearly the whole product and is the basis for running it headless. Docker deployment is configured through BTCPAY_* and BTCPAYGEN_* variables.

Alternative to: BitPay, Coinbase Commerce

- Capabilities: adaptable, operable
- Vertical: invoicing-finance
- Shape: business-app
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/btcpayserver/btcpayserver (MIT), 7741 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/btcpayserver--btcpayserver.html
- JSON: apps/btcpayserver--btcpayserver.json

## Use it when

- I want to accept Bitcoin at my shop or website without a processor taking a cut or holding my keys
- I want my agent to raise invoices and check settlement over an API I control

## Gotchas

- Bitcoin and Lightning only; no fiat card rails
- A full node sync takes days and hundreds of GB unless you add the pruning fragment
- Running Lightning means managing channel liquidity

## Editions

- Free: Free, open source
  - source: https://github.com/btcpayserver/btcpayserver
  - container: https://docs.btcpayserver.org/Docker/
  - hosted: https://docs.btcpayserver.org/ThirdPartyHosting/

## Adaptable: make it yours

Effort: config-only (16 things to edit)

The Docker deployment is a generator: set BTCPAY_HOST, network, which coins and Lightning implementation to run, reverse proxy and Let's Encrypt email in the .env, add fragments for pruning or plugins, then run btcpay-setup.sh. Store branding, checkout appearance and rates are in-app settings; plugins extend behavior without forking.

- Env vars: BTCPAY_HOST, BTCPAY_ADDITIONAL_HOSTS, NBITCOIN_NETWORK, BTCPAYGEN_CRYPTO1, BTCPAYGEN_LIGHTNING, LIGHTNING_ALIAS, BTCPAYGEN_REVERSEPROXY, REVERSEPROXY_HTTP_PORT, REVERSEPROXY_HTTPS_PORT, LETSENCRYPT_EMAIL, BTCPAY_LETSENCRYPT_HOSTS, BTCPAYGEN_ADDITIONAL_FRAGMENTS, BTCPAYGEN_EXCLUDE_FRAGMENTS, BTCPAY_ENABLE_SSH
- Config files: .env (BTCPAY_ENV_FILE), btcpay.env
- Prompt files: none
- Accounts you'll need: none

## Operable: what an agent can drive

Operability: official. Interface: api at https://docs.btcpayserver.org/API/Greenfield/v1/ (published by the builder, local).

### Reach (partial coverage)

- Create and manage stores: reachable. swagger.template.stores.json, stores-users, stores-rates
- Issue invoices and watch payment status: reachable. swagger.template.invoices.json, webhooks
- Payment requests: reachable. swagger.template.payment-requests.json
- Pull payments and payouts (refunds, salaries): reachable. swagger.template.pull-payments.json, payout-processors
- Point of sale, crowdfunding and donation apps: reachable. swagger.template.apps.json
- Lightning node operations: reachable. swagger.template.lightning.internal.json, lightning.store, stores-lightning-addresses
- On-chain wallet and payment methods: reachable. swagger.template.stores-wallet.on-chain.json, stores-payment-methods
- Users, API keys and notifications: reachable. swagger.template.users.json, api-keys, authorization, notifications
- Sign transactions with a hardware wallet: not reachable. BTCPay Vault runs in the browser next to the hardware wallet; not an API operation
- Install and configure plugins: undetermined. no plugins group among the swagger templates; server admin UI or BTCPAYGEN_ADDITIONAL_FRAGMENTS

## Code stack

- Languages: C#
- Frameworks: ASP.NET Core (.NET 10)
- Package manager: nuget
- Database: PostgreSQL
- Hosting target: Docker (btcpayserver-docker), third-party hosts, manual .NET deploy

## Skills

contributor: Repo carries contributor-facing development skills (migrations, changelog, PR descriptions, Playwright patterns) for working on the server. [contributor tooling, not adopter-facing]
- Paths: .agents/skills/*/SKILL.md

## Evidence and confidence

- formFactor: ASP.NET web app with client-facing checkout and admin (README) (confidence 0.95)
- executionModel: no model at runtime (confidence 0.95)
- operability: Greenfield API documented at docs.btcpayserver.org by the Builder; swagger templates in BTCPayServer/wwwroot/swagger/v1 (confidence 0.95)
- effort: docs.btcpayserver.org/Docker lists BTCPAY_* and BTCPAYGEN_* variables and the .env file (confidence 0.85)
- editions: README: free and open source, MIT; third-party hosting list (confidence 0.95)
- active: GitHub pushedAt 2026-09-02
- reach:  (confidence 0.85)

## Open questions

- Plugin management over Greenfield

## Sources

- https://github.com/btcpayserver/btcpayserver (sourcing:invoicing-finance:github)
- https://docs.btcpayserver.org/Docker/ (analysis:invoicing-finance)
- https://github.com/btcpayserver/btcpayserver/tree/master/BTCPayServer/wwwroot/swagger/v1 (analysis:invoicing-finance)