BTCPay Boltz Plugin einrichten
Lightning-Zahlungen ohne Lightning Node direkt auf die eigene Hardware Wallet empfangen (BitBox Beispiel)
Viele Betreiber eines BTCPay Servers möchten ihren Kunden nicht nur klassische Bitcoin-Onchain-Zahlungen, sondern auch Lightning-Zahlungen anbieten. In der Praxis scheitert das oft an der zusätzlichen Komplexität: Wer Lightning mit einer eigenen Node betreiben will, muss sich um Kanäle, Liquidität, Rebalancing, Backups und den laufenden Betrieb kümmern. Genau hier wird das BTCPay Boltz Plugin interessant. Das Plugin ermöglicht es, Lightning-Zahlungen in einem non-custodial Setup anzunehmen, ohne selbst eine Lightning Node zu betreiben. Laut offizieller Boltz-Dokumentation unterstützt das Plugin dafür zwei Betriebsarten: Rebalance Mode für bestehende Lightning-Nodes und einen Nodeless Mode für Händler ohne eigene Node.
Für Händler ist das besonders spannend, wenn alle Einnahmen am Ende auf der eigenen Hardware Wallet landen sollen. In diesem Beitrag zeige ich Schritt für Schritt, wie du das Boltz BTCPay Plugin so einrichtest, dass dein BTCPay Server sowohl Onchain-Zahlungen als auch Lightning-Zahlungen akzeptiert und die Bitcoin anschließend auf der gleichen Hardware Wallet landen. Als Beispiel verwende ich eine BitBox Wallet und den dazugehörigen zpub-Key. BTCPay unterstützt Watch-only-Wallets ausdrücklich, sodass der Server Adressen erzeugen und Zahlungen überwachen kann, ohne die privaten Schlüssel zu speichern.
Kurz erklärt:
Mit dem BTCPay Boltz Plugin kann ein BTCPay Server Lightning-Zahlungen empfangen, ohne eine eigene Lightning Node zu betreiben. Im Nodeless Mode wird eine Lightning-Zahlung über Boltz zuerst in Liquid Bitcoin (L-BTC) umgewandelt. Anschließend kann das Guthaben automatisch wieder in Bitcoin auf der Mainchain zurückgeswappt werden. Dadurch können sowohl Onchain- als auch Lightning-Einnahmen am Ende auf derselben Hardware Wallet landen.
Für wen ist dieses Setup gedacht?
Diese Anleitung richtet sich an alle, die bereits einen eigenen BTCPay Server betreiben oder gerade einrichten und keine eigene Lightning Node betreiben möchten. Typische Anwendungsfälle sind Händler, Freiberufler, Online-Shops oder Vereine, die Bitcoin möglichst einfach akzeptieren möchten, aber trotzdem Wert auf Self-Custody und die eigene Hardware Wallet legen. BTCPay beschreibt sich selbst als self-hosted und non-custodial Payment Gateway, bei dem Zahlungen direkt an die eigene Wallet gehen.
Das Setup ist besonders interessant, wenn du Folgendes möchtest:
Onchain-Zahlungen sollen direkt auf deine Bitcoin-Wallet gehen. Lightning-Zahlungen sollen ebenfalls akzeptiert werden. Und am Ende sollen beide Zahlungsarten in derselben Wallet zusammenlaufen, zum Beispiel auf einer BitBox. Das ist mit dem BTCPay Boltz Plugin möglich, weil BTCPay für die Bitcoin-Seite mit einer Watch-only-Wallet arbeiten kann, während das Boltz Plugin die Lightning-Zahlung per Swap verarbeitet.
Was ist das BTCPay Boltz Plugin?
Das Boltz BTCPay Plugin ist ein Plugin für BTCPay Server, mit dem Händler Lightning-Zahlungen non-custodial annehmen können. Laut offizieller Dokumentation kann das Plugin entweder die Liquidität einer bestehenden Lightning Node automatisch verwalten oder Lightning-Zahlungen ganz ohne eigene Node annehmen. Im zweiten Fall arbeitet das Plugin mit Lightning-to-Liquid-Swaps.
Wichtig ist dabei die technische Logik: Im Nodeless Mode wird eine Lightning-Zahlung nicht direkt auf Bitcoin Mainchain empfangen. Stattdessen erstellt BTCPay über Boltz einen Swap für denselben Betrag. Nach erfolgreicher Lightning-Zahlung wird der Betrag abzüglich Gebühren in eine Liquid Wallet ausgezahlt. Boltz erklärt selbst, dass Liquid in diesem Modus die einzige Option ist, weil die Netzwerkgebühren dort zuverlässig niedrig sind und auch kleinere Lightning-Zahlungen wirtschaftlich bleiben.
Wie funktioniert das Setup technisch?
Damit du das Setup später sauber erklären oder dokumentieren kannst, hilft ein kurzer Blick auf den Zahlungsfluss.
Onchain Zahlung
Bei einer normalen Bitcoin-Onchain-Zahlung läuft alles klassisch:
BTCPay erzeugt aus dem hinterlegten zpub/xpub eine neue Empfangsadresse. Der Kunde zahlt direkt auf diese Adresse. Die Bitcoin landen in der Wallet, die zu diesem zpub gehört. Watch-only-Wallets in BTCPay können genau dafür verwendet werden: Adressen ableiten, Zahlungen überwachen, aber nicht eigenständig Coins ausgeben.
Lightning Zahlung
Bei einer Lightning-Zahlung im Boltz Nodeless Mode läuft der Weg anders:
Der Kunde zahlt per Lightning. Boltz führt einen Lightning → Liquid Swap aus. Das Ergebnis landet zunächst in einer Liquid Wallet. Danach kann das Guthaben automatisch per Chain Swap zurück in Bitcoin Mainchain umgewandelt werden. Als Ziel dient dann die bereits im Store konfigurierte Bitcoin-Wallet. Genau diese Logik beschreibt BTCPay in seiner Lightning-Dokumentation für Swapping Services wie Boltz.
Der praktische Effekt ist entscheidend:
Der Händler braucht keine eigene Lightning Node, kann aber trotzdem Lightning-Zahlungen annehmen. Am Ende kann dasselbe Bitcoin-Wallet-Ziel für Onchain-Zahlungen und für die aus Lightning zurückgeswappten BTC verwendet werden.
Was du für das Setup brauchst
Bevor du startest, solltest du diese Dinge bereithalten:
- einen laufenden BTCPay Server
- Zugriff auf Server Settings
- Zugriff auf Manage Plugins
- eine BitBox Wallet oder eine andere Hardware Wallet
- den zpub oder xpub der Wallet, die als Bitcoin-Zielwallet dienen soll
- optional Sparrow Wallet, wenn du den zpub komfortabel auslesen oder prüfen möchtest
BTCPay dokumentiert verschiedene Wege zur Wallet-Einrichtung, darunter Watch-only-Wallets auf Basis von Extended Public Keys. Für Hardware Wallets empfiehlt BTCPay Setups, bei denen die privaten Schlüssel auf dem Gerät bleiben.
Schritt 1: Bitcoin-Wallet im BTCPay Server einrichten
Der erste Schritt ist die Einrichtung deiner normalen Bitcoin-Wallet im Store. Diese Wallet wird später doppelt genutzt:
erstens für direkte Onchain-Zahlungen und zweitens als Zielwallet für die automatisch zurückgeswappten Lightning-Einnahmen.
Öffne in deinem Store den Bereich Wallets und richte dort deine Bitcoin Wallet ein. Wenn du mit einer BitBox arbeitest, ist der sauberste Weg eine Watch-only-Wallet auf Basis des zpub/xpub. BTCPay beschreibt Watch-only-Wallets ausdrücklich als Wallets, bei denen keine privaten Schlüssel auf dem Server gespeichert werden.
Für die Praxis bedeutet das:
Du nimmst den zpub deiner BitBox-Wallet und hinterlegst ihn in BTCPay. Von diesem Moment an kann BTCPay neue Bitcoin-Empfangsadressen ableiten. Die Coins gehören weiterhin deiner BitBox-Wallet. BTCPay kann sie nicht ausgeben, solange nur der Public Key hinterlegt ist.
Wichtig für dieses Setup:
Du brauchst keinen zweiten zpub für Lightning. Derselbe zpub kann später auch für die Bitcoin-Zielwallet der Boltz-Chain-Swaps verwendet werden. Solange BTCPay diese Wallet verwaltet, kann das System aus demselben Wallet-Pool Adressen für Onchain-Zahlungen und für die aus Lightning zurückkommenden Bitcoin verwenden. Das entspricht dem normalen Verhalten einer HD-/Watch-only-Wallet in BTCPay.
Schritt 2: Das BTCPay Boltz Plugin installieren
Als Nächstes installierst du das Plugin auf Server-Ebene.
Gehe dazu in Server Settings und dann in Manage Plugins. Dort installierst du das Boltz Plugin. Nach der Installation erscheint in der Navigation ein eigener Bereich für Boltz. Boltz dokumentiert diesen Installationsweg für selbst gehostete BTCPay-Server ausdrücklich.
Falls du einen gemeinsam genutzten BTCPay-Server betreibst oder mehrere Nutzer auf dem Server hast, solltest du zusätzlich beachten, dass Administratoren das Plugin für Tenants manuell freigeben können oder müssen. Die Boltz-Dokumentation nennt dafür die Option Admin → Advanced → Allow Plugin for Tenants.
Schritt 3: Den richtigen Modus auswählen
Nach der Installation startest du die Konfiguration im Boltz-Bereich. Dort stehen zwei Betriebsarten zur Auswahl:
- Rebalance existing Lightning node
- Accept Lightning payments without running a node
Für dieses Tutorial ist die zweite Option die richtige:
Accept Lightning payments without running a node.
Das ist der sogenannte Nodeless Mode. Er ist genau für Betreiber gedacht, die zwar Lightning anbieten möchten, aber keine eigene Lightning Node betreiben. Laut Boltz ist das Plugin damit eine der Lösungen, mit denen Händler Lightning-Zahlungen non-custodial annehmen können, ohne selbst eine Lightning Node zu betreiben.
Schritt 4: Gebühren und Swap-Modell prüfen
Im nächsten Schritt zeigt dir das Plugin eine Übersicht über Gebühren, Netzwerkgebühren sowie Mindest- und Höchstbeträge. Gleichzeitig wird erklärt, dass der Nodeless Mode über Lightning → Liquid Swaps funktioniert. Genau das ist der Kern des Setups: Lightning wird nicht direkt zu Onchain-Bitcoin, sondern zunächst zu L-BTC.
Für den Händler ist die zentrale Information:
Er empfängt Lightning-Zahlungen nicht auf einer Lightning Node, sondern über einen Swap-Prozess. Der Vorteil ist die geringere technische Komplexität. Der Nachteil ist, dass Liquid als Zwischenschicht genutzt wird und zusätzliche Swap-Gebühren entstehen können. BTCPay nennt Swapping Services wie Boltz ausdrücklich als Option, um Lightning automatisch in Onchain-Bitcoin oder L-BTC umzuwandeln.
Schritt 5: Die interne Liquid Wallet anlegen
Jetzt fragt dich das Plugin nach einer Wallet für die L-BTC-Eingänge. Für dieses Setup wählst du:
Create a new wallet
Damit erzeugt BTCPay eine neue interne Liquid Wallet, die als Empfangsziel für die Lightning-to-Liquid-Swaps dient. Boltz beschreibt genau diesen Schritt in seiner Dokumentation: Händler können eine neue Wallet erzeugen oder eine vorhandene Liquid Wallet importieren.
Anschließend zeigt BTCPay dir eine Recovery Phrase an. Diese solltest du unbedingt sicher notieren. Gleichzeitig weist BTCPay darauf hin, dass diese Wallet als Hot Wallet auf dem Server gespeichert wird. Das ist wichtig für die Sicherheitsbetrachtung: Die interne Liquid Wallet ist eine praktische Zwischenstation für die Swaps, aber sie ist nicht mit einer Cold Wallet gleichzusetzen. BTCPay erklärt in seiner Wallet-Dokumentation den Unterschied zwischen Hot Wallet und Watch-only Wallet sehr deutlich.
Für den Leser deines Blogartikels ist hier die wichtigste Botschaft:
Du brauchst keine externe Liquid Wallet, wenn du nur das Standard-Setup mit dem Boltz Plugin verwenden willst. Die interne BTCPay-Liquid-Wallet reicht als Zwischenstufe aus.
Schritt 6: Chain Swaps einrichten
Im nächsten Schritt konfigurierst du die automatische Rückwandlung von L-BTC zu Bitcoin Mainchain. Im Plugin heißt dieser Abschnitt Set Up Chain Swaps.
Hier definierst du typischerweise zwei Werte:
- Max Balance
- Reserve Balance
Die Logik dahinter ist einfach:
Die interne Liquid Wallet darf bis zu einem bestimmten Schwellwert Guthaben halten. Wird dieser Wert überschritten, startet das Plugin einen Chain Swap zurück auf die Bitcoin Mainchain. Ein Teilbetrag kann dabei als Reserve in Liquid bleiben. Boltz beschreibt diese Funktion ausdrücklich als optionalen Schritt, um L-BTC automatisch wieder in reguläre Bitcoin umzuwandeln.
Für Händler, die möglichst alles direkt auf ihrer Hardware Wallet haben möchten, ist eine eher niedrige Max-Balance meist sinnvoll. So bleibt nur wenig Liquid-Guthaben auf dem Server liegen und der Großteil wird automatisch zurück in normales BTC umgewandelt. Das verbessert die Praxisnähe des Setups deutlich, auch wenn dabei zusätzliche Gebühren anfallen können.
Schritt 7: Als BTC-Zielwallet dieselbe BitBox-Wallet auswählen
Jetzt kommt der entscheidende Teil für dein gewünschtes Setup.
Das Plugin fragt, wohin die Onchain-Bitcoin aus den Chain Swaps gesendet werden sollen. Hier wählst du die bereits im Store eingerichtete Bitcoin-Wallet aus, also die Wallet auf Basis des zpub deiner BitBox.
Genau dadurch wird das Setup elegant:
Sowohl direkte Onchain-Zahlungen als auch die über Boltz zurückgeswappten Lightning-Einnahmen landen in derselben Wallet-Struktur. Der Händler braucht also nicht zwei verschiedene Bitcoin-Wallets, sondern nur eine einzige Watch-only-Bitcoin-Wallet im Store.
Das ist auch die Antwort auf die häufige Praxisfrage:
Reicht ein einziger zpub der BitBox?
Ja. Für dieses Setup reicht ein einziger zpub/xpub der BitBox-Wallet aus, wenn er im Store bereits für die Onchain-Zahlungen hinterlegt ist und dieselbe Wallet im Boltz-Plugin als Ziel der Chain Swaps ausgewählt wird. BTCPay kann auf Basis dieses Public Keys Empfangsadressen verwalten, ohne dass der Händler seine privaten Schlüssel preisgeben muss.
Schritt 8: Das Setup abschließen
Nach Abschluss der Konfiguration sollte im Boltz-Bereich angezeigt werden, dass Lightning aktiv ist. Die Boltz-Dokumentation beschreibt diesen Zustand sinngemäß als „Lightning shows active and running“. Anschließend empfiehlt Boltz ausdrücklich, eine kleine Testzahlung durchzuführen.
Spätestens jetzt ist dein BTCPay-Server-Setup vollständig:
- Onchain-Zahlungen gehen direkt an die Bitcoin-Wallet des Stores
- Lightning-Zahlungen laufen über das Boltz Plugin
- L-BTC landen kurzzeitig in der internen Liquid Wallet
- Chain Swaps schicken die Bitcoin zurück an die BitBox-Wallet
Schritt 9: Eine Testzahlung durchführen
Bevor du das Setup für einen Händler produktiv nutzt, solltest du unbedingt eine kleine Testzahlung ausführen.
Erstelle dazu eine Rechnung in deinem Store und prüfe, ob Bitcoin und Lightning als Zahlungsmethoden angeboten werden. Bezahle die Rechnung testweise mit einer Lightning-Wallet. Anschließend kontrollierst du im Bereich Boltz → Swaps, ob der Swap korrekt erstellt und verarbeitet wurde. Boltz empfiehlt selbst, nach dem Setup einen kleinen Testkauf zu machen.
Für die redaktionelle Einordnung im Blog ist dieser Praxistest wichtig:
Nur wenn du einmal den kompletten Ablauf gesehen hast, verstehst du wirklich, wie sich das Setup im Alltag verhält. Gerade beim ersten Test wird sichtbar, dass Lightning-Zahlungen nicht auf einer Lightning Node, sondern auf der Liquid-Zwischenstufe landen und erst danach zurück in Onchain-Bitcoin gehen.
Welche Daten werden vom Händler benötigt?
Wenn du das Setup für einen Händler einrichtest, brauchst du im einfachsten Fall nur sehr wenige Informationen:
- den zpub/xpub der Hardware Wallet, zum Beispiel der BitBox
- Zugriff auf den BTCPay Server
- die Zustimmung, dass das Plugin eine interne Liquid Wallet als Hot Wallet anlegt
- die gewünschte Einstellung für Max Balance und Reserve Balance
Was du nicht brauchst:
- keinen Seed der BitBox
- keine privaten Schlüssel der BitBox
- keine eigene Lightning Node des Händlers
Gerade das macht das Setup für viele Händler attraktiv: Die Cold Storage Wallet bleibt beim Händler, während BTCPay nur mit öffentlichen Wallet-Daten arbeitet und Boltz den Lightning-Empfang per Swap ermöglicht.
Die Vorteile dieses Setups
Der größte Vorteil ist die einfache Kombination aus Self-Custody und Lightning-Unterstützung. Händler müssen sich nicht in die Tiefen des Lightning-Node-Betriebs einarbeiten, können aber trotzdem Lightning-Zahlungen annehmen. BTCPay führt Boltz genau als eine der Swapping-Service-Optionen für diesen Zweck auf.
Ein weiterer Vorteil ist die klare Zielwallet:
Sowohl Onchain-Zahlungen als auch die aus Lightning zurückkommenden Bitcoin können in derselben Hardware Wallet zusammenlaufen. Für die Buchhaltung und das operative Handling ist das oft deutlich einfacher als mehrere getrennte Wallets oder separate Zahlungswege.
Nicht zuletzt bleibt das Setup non-custodial auf der Bitcoin-Seite des Händlers. Der Händler gibt weder Seed noch private Schlüssel seiner Hardware Wallet an den Server weiter. Die Zielwallet bleibt damit unter seiner Kontrolle.
Die Nachteile und Grenzen
Ganz ohne Trade-offs kommt das Setup nicht aus.
Erstens nutzt das System im Nodeless Mode zwingend Liquid als Zwischenschicht. Boltz nennt Liquid in diesem Modus ausdrücklich als die einzige Option. Wer keinerlei Berührung mit Liquid möchte, wird mit diesem Setup also nicht glücklich.
Zweitens ist die interne Liquid Wallet eine Hot Wallet. Das ist bequem, aber sicherheitstechnisch nicht dasselbe wie eine reine Watch-only-Wallet oder eine Cold Wallet. Deshalb sollte die Liquid-Zwischenbalance nicht unnötig hoch gewählt werden.
Drittens entstehen zusätzliche Gebühren, weil der Weg aus zwei Swaps bestehen kann:
Lightning → Liquid und Liquid → Bitcoin Mainchain. Für sehr kleine Zahlungen muss man die Wirtschaftlichkeit deshalb im Blick behalten. Boltz zeigt diese Gebühren im Setup transparent an.
Fazit
Das BTCPay Boltz Plugin ist eine sehr interessante Lösung für alle, die mit ihrem BTCPay Server Lightning-Zahlungen annehmen möchten, ohne eine eigene Lightning Node zu betreiben. Im Nodeless Mode verarbeitet das Plugin Lightning-Zahlungen über Atomic Swaps und nutzt dabei Liquid als Zwischenschicht. Anschließend können die Bitcoin automatisch zurück auf die Mainchain geswappt werden.
Für die Praxis bedeutet das:
Ein Händler kann sowohl Onchain-Bitcoin als auch Lightning-Zahlungen akzeptieren und am Ende alles auf derselben Hardware Wallet sammeln. Im gezeigten Beispiel reicht dafür ein einziger zpub der BitBox, der im Store bereits für die Onchain-Wallet verwendet wird. Genau dieses Zusammenspiel macht das Boltz BTCPay Plugin für viele BTCPay-Server-Betreiber zu einer der spannendsten Optionen für den Einstieg in Lightning ohne eigene Node.
FAQ: BTCPay Boltz Plugin, Lightning und Hardware Wallet
Was ist das BTCPay Boltz Plugin?
Das BTCPay Boltz Plugin ist ein Plugin für BTCPay Server, mit dem Händler Lightning-Zahlungen entweder mit einer bestehenden Lightning Node verwalten oder im Nodeless Mode ohne eigene Lightning Node annehmen können.
Brauche ich für das Boltz BTCPay Plugin eine eigene Lightning Node?
Nein. Im Nodeless Mode kannst du Lightning-Zahlungen annehmen, ohne eine eigene Lightning Node zu betreiben.
Kann ich mit dem BTCPay Boltz Plugin Lightning-Zahlungen direkt auf meine Hardware Wallet empfangen?
Ja, indirekt. Die Zahlung wird zuerst in L-BTC auf Liquid umgewandelt und kann danach automatisch zurück in Bitcoin Mainchain geswappt werden. Als Ziel kann deine Hardware Wallet dienen.
Reicht ein einziger zpub der BitBox für Onchain und Lightning?
Ja. Wenn derselbe zpub bereits für die Bitcoin-Wallet des Stores verwendet wird, kann diese Wallet auch als Ziel der Chain Swaps dienen.
Kann BTCPay mit einem zpub Coins ausgeben?
Nein. Bei einer Watch-only-Wallet speichert BTCPay keine privaten Schlüssel. Der Server kann Zahlungen überwachen und Adressen erzeugen, aber nicht eigenständig Coins ausgeben.
Warum wird Liquid im Nodeless Mode verwendet?
Boltz nutzt im Nodeless Mode Liquid, weil dort die Netzwerkgebühren niedrig und die Swaps für kleinere Lightning-Zahlungen wirtschaftlich bleiben.
Ist das Setup custodial?
Auf Seiten der Bitcoin-Zielwallet nicht. Der Händler behält die Kontrolle über seine Hardware Wallet. BTCPay und Boltz beschreiben das Setup als non-custodial beziehungsweise auf Atomic Swaps basierend.
Brauche ich eine externe Liquid Wallet?
Nicht zwingend. Du kannst im Boltz-Plugin eine interne Liquid Wallet erstellen, die als Zwischenstufe für die Swaps dient.
Ist die interne Liquid Wallet sicher?
Sie ist praktisch, aber sie ist eine Hot Wallet. Deshalb sollte man die Recovery Phrase sichern und die Liquid-Balance nicht unnötig hoch halten.
Ja, grundsätzlich schon. Laut Boltz ist das Plugin auch für Merchants auf Shared Instances gedacht. Administratoren müssen es gegebenenfalls manuell freigeben.
Unterstützt das Boltz Plugin BTCPay Server v1?
Nein. Laut Boltz wird nur BTCPay Server v2 unterstützt.
Wo installiere ich das Plugin?
Über Server Settings → Manage Plugins.
Kann ich statt BitBox auch andere Hardware Wallets verwenden?
Ja. BTCPay unterstützt grundsätzlich Hardware-Wallet-Integrationen. Für dieses Setup ist entscheidend, dass du eine Wallet mit Public-Key-/Watch-only-Import sauber anbinden kannst.
Welche Gebühren entstehen?
Es fallen je nach Zahlung Boltz-Service-Gebühren, Netzwerkgebühren und gegebenenfalls Gebühren für den Chain Swap zurück auf Bitcoin Mainchain an. Das Plugin zeigt diese im Setup an.
Wo sehe ich, ob ein Swap funktioniert hat?
Im Boltz-Bereich deines BTCPay Servers, insbesondere unter Swaps. Dort kannst du den Verlauf der über Boltz abgewickelten Zahlungen prüfen. Das Testen mit einer kleinen Zahlung wird von Boltz ausdrücklich empfohlen.
