BTCPay Server Plugin Template

A template for your own BTCPay Server plugin.

Learn more in our plugin documentation.

Requirements

• .NET SDK 10.0 or later
• Git with submodule support
• Docker, for running the BTCPay Server development dependencies

Getting started

First, clone this repository:

mkdir my-plugin && cd my-plugin
git clone --recurse-submodules https://github.com/btcpayserver/btcpayserver-plugin-template.git .

If you already cloned without submodules, initialize them with:

git submodule update --init --recursive

Update the btcpayserver submodule to the latest tagged version

Make sure that your submodules reference the latest stable version of BTCPay Server.

cd submodules/btcpayserver
git fetch --tags
latest_tag=$(
  git tag -l 'v[0-9]*.[0-9]*.[0-9]*' \
    | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
    | sort -V \
    | tail -n 1
)
git checkout "$latest_tag"
cd ../..

Update src/BTCPayServer.Plugins.Template/Plugin.cs's PluginDependency with the version of BTCPayServer that you fetched in latest_tag.

Rename the plugin

For renaming the plugin, choose a name following .NET assembly naming conventions: PascalCase, optionally separated by dots. For example: MyPlugin or MyCompany.MyPlugin.

Then replace all occurrences of BTCPayServer.Plugins.Template with PLUGIN_NAME.

Here is a script you can run to do this automatically:

PLUGIN_NAME="MyPlugin"
OLD_NAME="BTCPayServer.Plugins.Template"
AREA_NAME="MyPlugin"
OLD_AREA="TemplateArea"
export OLD_NAME PLUGIN_NAME AREA_NAME OLD_AREA

git grep -l -z "$OLD_NAME" -- . ':!submodules' | xargs -0 perl -pi -e 's/\Q$ENV{OLD_NAME}\E/$ENV{PLUGIN_NAME}/g'

git mv "src/$OLD_NAME" "src/$PLUGIN_NAME"
git mv "src/$PLUGIN_NAME/$OLD_NAME.csproj" "src/$PLUGIN_NAME/$PLUGIN_NAME.csproj"
git mv "src/$PLUGIN_NAME/Plugins/$OLD_AREA" "src/$PLUGIN_NAME/Plugins/$AREA_NAME"
perl -pi -e 's/\Q"$ENV{OLD_AREA}"\E/"$ENV{AREA_NAME}"/' "src/$PLUGIN_NAME/Plugin.cs"

git mv "tests/$OLD_NAME.Tests" "tests/$PLUGIN_NAME.Tests"
git mv "tests/$PLUGIN_NAME.Tests/$OLD_NAME.Tests.csproj" "tests/$PLUGIN_NAME.Tests/$PLUGIN_NAME.Tests.csproj"

git mv "$OLD_NAME.slnx" "$PLUGIN_NAME.slnx"

Then update the plugin metadata in src/<YourPluginName>/<YourPluginName>.csproj:

• Product
• Description
• Version

The area name must match the directory between Plugins and Views. The script updates both. Then customize the example controller, route, view text, and test for your plugin.

Verify that the plugin builds:

dotnet build

Clean up template project references

Finally, clean up the remaining template project references.

Replace this README with documentation for your own plugin. Keep it user-centric. Document what the plugin does and how to configure it. We advise to include screenshots and video. Avoid developer-centric jargon.

You may also want to review and update:

• LICENSE
• package metadata in your plugin .csproj

Switching this branch to your own git repository

Switch origin to your own repository:

git remote set-url origin git@github.com:<your-github-user>/<your-plugin-repository>.git

If you want to start your plugin without the template's git history, create a new initial commit:

git switch --orphan initial
git add -A
git commit -m "Initial commit"
git branch -M main

Then push it to your repository.

git push --force-with-lease origin main

Debugging the plugin

Register the plugin with the BTCPay Server development environment:

./plugin-register.sh

It will configure BTCPay Server for loading your plugin during debug.

Start the BTCPay Server development dependencies:

cd submodules/btcpayserver/BTCPayServer.Tests
docker compose up -d dev

Open the solution file in your IDE and use the BTCPayServer: Bitcoin-HTTPS launch profile. When the debugger starts BTCPay Server, it should load your plugin. A breakpoint in src/<YourPluginName>/Plugin.cs, such as inside Plugin.Execute, should be hit during startup.

Sign in and open /template to verify the example page and account-menu entry.

Adding plugin code

The template includes a working authenticated controller, Razor view, and account-menu UI extension. Views are stored under Plugins/{AreaName}/Views, matching BTCPay Server's area view conventions, so controller actions can use View() without an explicit view path. UI extensions still use Plugin.ViewsDirectory because they render outside the controller's area context.

Register additional services, controllers, hosted services, migrations, or other plugin components from Plugin.Execute.

If your plugin needs Entity Framework or bundled project dependencies, see the commented examples in the plugin .csproj file.

You can take examples from other plugins and BTCPay Server's own system plugins in submodules/btcpayserver/BTCPayServer/Plugins.