Bare Bitcoin Plugin for BTCPay Server

Integrate your Bare Bitcoin account with BTCPay Server. This plugin allows you to receive Lightning payments directly to your Bare Bitcoin account and view your current balance.

Features

• Receive Lightning payments — Accept bitcoin payments over Lightning Network directly to your Bare Bitcoin account
• Balance display — View your current Bare Bitcoin balance within BTCPay Server

Limitations

Receive-only Lightning integration — You can receive sats into your Bare Bitcoin account through BTCPay Server. Sending sats from your Bare Bitcoin account through BTCPay Server, including refunds, is not supported.

Tracked Invoice Migration

Plugin versions that used the legacy flat tracked-invoice file, or schema version 2 account-scoped state, did not persist which BTCPay store owned each invoice. On upgrade, those invoice IDs are retained in an unassigned quarantine instead of being deleted or exposed to every configured store. Until ownership is recovered, no plugin listener can enumerate, query, or remove them.

BTCPay Server independently persists each monitored Lightning invoice with its owning store and connection. During startup reconciliation, BTCPay calls GetInvoice through that store's connection rather than through the plugin's legacy registry. An invoice is then atomically reclaimed into the correct store connection scope; concurrent or later claims from another scope are ignored. A paid invoice is returned directly to BTCPay for payment recording and remains scoped until the normal listener-delivery path untracks it, preserving crash recovery. Expired invoices are removed after the successful terminal lookup. This restores monitoring without assigning a legacy ID to the first or every Bare Bitcoin connection.

The persisted connection string requires a server-authenticated store binding. The BTCPay web setup automatically injects the current store-id and its signed store-binding before testing or saving a Bare Bitcoin connection. During configuration, the plugin also compares that binding with BTCPay's authenticated current store, so a valid binding copied from another store is rejected. This keeps invoice tracking isolated when multiple stores use the same Bare Bitcoin account or API credentials. The Node helper intentionally remains store-agnostic; complete configuration through the web setup so BTCPay can add the binding securely.

Important

Existing configurations without the signed store binding fail closed after upgrading. Before accepting payments, open each store's Lightning setup and save its Bare Bitcoin connection again. Direct API or manual connection-string configuration cannot mint a store binding and is not supported for this migration.

If the plugin encounters a registry schema newer than it understands, it leaves the file unchanged and disables tracking mutations instead of overwriting future-version state. Installing a compatible plugin version or an explicit migration is then required before persistence resumes.

Installation

1. In BTCPay Server, go to Server Settings > Plugins
2. Search for "Bare Bitcoin"
3. Click Install
4. Restart BTCPay Server when prompted

Setup

1. Create API Keys

1. Log in to your Bare Bitcoin account
2. Navigate to API Key Creation
3. Create a new key with:
   • Name: A descriptive name (e.g., "BTCPay Server")
   • Permissions: Select both Read and Receive
4. Save your Public Key and Secret Key securely — the secret key is only shown once

2. Generate Connection String

Use the provided script to generate your BTCPay Server connection string:

1. Ensure Node.js is installed
2. Run:

   node barebitcoin-lightning-connection-setup.js

3. Enter your Public Key and Secret Key when prompted
4. Select which Bitcoin account to use (if you have multiple)
5. Copy the generated connection string

3. Configure BTCPay Server

1. In BTCPay Server, go to your store's Lightning settings
2. Select Bare Bitcoin as the Lightning connection type
3. Paste your connection string
4. Test or save the connection; BTCPay automatically adds this store's authenticated binding

Development

Prerequisites

Install the .NET 10.0 SDK. The plugin and tests target net10.0. The repository global.json pins SDK 10.0.100 with rollForward: latestFeature, which is the same policy CI uses.

This branch supports BTCPay Server 2.3.7 and newer at runtime.

Release builds target BTCPay Server 2.3.9 through the tracked submodule so package builds stay free of BTCPay transitive dependency vulnerability warnings.

Use one of these BTCPay Server source layouts:

• Clone BTCPay Server adjacent to this repository for local development.
• Or initialize the submodules/btcpayserver submodule, which is what Plugin Builder uses.

Adjacent checkout:

git clone https://github.com/btcpayserver/btcpayserver.git

Submodule checkout:

git submodule update --init --recursive

Build

Build BTCPay Server if you are using the adjacent checkout:

dotnet build ../btcpayserver/BTCPayServer/BTCPayServer.csproj

Add the plugin to the BTCPay Server solution:

cd btcpayserver
dotnet sln add ../btcpayserver-plugin-barebitcoin/plugin -s Plugins

Build the plugin:

dotnet build ../btcpayserver-plugin-barebitcoin/plugin/BTCPayServer.Plugins.BareBitcoin.csproj

ConfigBuilder container

ConfigBuilder is an optional development helper that writes DEBUG_PLUGINS into BTCPay Server's appsettings.dev.json. This repository still publishes it as a container so the runtime image stays coupled to the project's net10.0 target framework.

There is no Dockerfile. Publish the image with the .NET 10 SDK:

dotnet publish ConfigBuilder/ConfigBuilder.csproj -c Release --os linux /t:PublishContainer

The SDK selects mcr.microsoft.com/dotnet/runtime:10.0-noble from TargetFramework (net10.0) plus ContainerFamily (noble). That is Ubuntu 24.04, the default Linux distribution for official .NET 10 images. Debian variants are not published for .NET 10.

Program.cs resolves the plugin workspace four directories up from the process working directory:

• ../../../../Plugins — plugin project directories named after their DLLs
• ../../../../btcpayserver/BTCPayServer or ../../../../submodules/btcpayserver/BTCPayServer — a checkout that contains BTCPayServer.csproj

The published binaries stay in /app. Set the process working directory four levels below the mounted workspace so those relatives resolve to /workspace:

docker run --rm \
  --volume /path/to/plugins-workspace:/workspace \
  --workdir /workspace/ConfigBuilder/bin/Release/net10.0 \
  barebitcoin-config-builder:test

The container runs as root so it can write appsettings.dev.json on the bind mount. This single-plugin repository uses plugin/ rather than Plugins/; the README setup below writes appsettings.dev.json directly.

Test

Run the test suite through Microsoft Testing Platform:

dotnet test --project BTCPayServer.Plugins.Tests/BTCPayServer.Plugins.Tests.csproj --minimum-expected-tests 1

After building, the test executable can also be run directly:

./BTCPayServer.Plugins.Tests/bin/Debug/net10.0/BTCPayServer.Plugins.Tests

On Windows, run the executable at the same path with the .exe extension.

Run Locally

Configure BTCPay Server to load the plugin:

echo '{
  "DEBUG_PLUGINS": "<absolute-path-to>/plugin/bin/Debug/net10.0/BTCPayServer.Plugins.BareBitcoin.dll"
}' > BTCPayServer/appsettings.dev.json

Start the development environment:

cd BTCPayServer.Tests
docker-compose up dev

Launch BTCPay Server (e.g., via VS Code's ".NET Core Launch (web)") and navigate to https://localhost:14142

Public Release

To publish a new public plugin build for BTCPay Server, use the Plugin Builder:

• URL: https://plugin-builder.btcpayserver.org/
• Public plugin page: https://plugin-builder.btcpayserver.org/public/plugins/barebitcoin

Prepare a reproducible release tag with:

./pluginpacker.sh 2.0.1

The script updates the plugin version, runs tests, commits the version bump, creates and pushes the release tag, optionally creates a local .btcpay package, and prints the Plugin Builder form values.

Create a new Plugin Builder build with:

1. Git repository: https://github.com/schjonhaug/btcpayserver-plugin-barebitcoin
2. Git branch or tag: the release tag, for example v2.0.1
3. Directory to the plugin's project: plugin
4. Dotnet build configuration: Release

Every new Plugin Builder build starts as a pre-release. Pre-release builds are not visible to BTCPay Server instances unless the admin has explicitly enabled pre-release plugins.

Use the pre-release stage to install and test the plugin on your own BTCPay Server instance before promoting it. Once verified, release the build in the Plugin Builder UI to make it available to all users.

The GitHub release alone does not publish the plugin to the public BTCPay plugin directory.

Before building a release, keep the tracked submodules/btcpayserver checkout aligned with the BTCPay Server version used for warning-free release builds. Plugin Builder uses the submodule layout, so an outdated submodule can surface transitive BTCPay dependency warnings even when local adjacent-checkout builds are clean.

To update it, replace v2.3.9 with the BTCPay Server version used for the release build target:

git submodule update --init submodules/btcpayserver
git -C submodules/btcpayserver fetch --tags
git -C submodules/btcpayserver checkout v2.3.9
git add submodules/btcpayserver