btcpay-plugin/README.md

Lethean BTCPay Server Plugin

Accept Lethean payments in BTCPay Server. Privacy-focused cryptocurrency with confidential transactions and integrated addresses.

Warning

This plugin shares a single Lethean wallet across all stores in the BTCPay Server instance. Use this plugin only if you are not sharing your instance.

How it works

When a customer creates an invoice, the plugin generates a unique integrated address (containing an embedded payment ID) for each payment. A background poller checks the wallet every 15 seconds for incoming payments matching pending invoices, tracks confirmations, and settles invoices based on your configured threshold.

Configuration

Environment variable	Required	Description	Example
BTCPAY_LTHN_DAEMON_URI	Yes	URI of the letheand RPC interface	http://127.0.0.1:36941
BTCPAY_LTHN_WALLET_DAEMON_URI	Yes	URI of the simplewallet RPC interface	http://127.0.0.1:36944
BTCPAY_LTHN_WALLET_DAEMON_WALLETDIR	No	Directory where wallet files are stored (for auto-loading on startup)	/wallet

Setup

1. Run Lethean daemon

letheand --rpc-bind-ip=0.0.0.0 --rpc-bind-port=36941

2. Run Lethean wallet in RPC mode

Create or open a wallet, then start simplewallet with RPC enabled:

simplewallet --wallet-file /path/to/wallet \
  --password "your-password" \
  --daemon-address 127.0.0.1:36941 \
  --rpc-bind-port 36944

For receive-only setups, create a watch-only wallet first:

simplewallet --generate-new-wallet /path/to/wallet
# Then from the wallet prompt:
save_watch_only /path/to/watch-only-wallet password

3. Install the plugin

In BTCPay Server, go to Server Settings > Plugins and install the Lethean plugin. Then configure the environment variables above and restart.

4. Enable Lethean for your store

Go to Store Settings > Lethean to enable it and set your preferred confirmation threshold.

Docker

A Docker image with letheand and simplewallet is available:

docker pull letheanio/letheand:latest

Run the daemon:

docker run -d --name letheand \
  -p 36941:36941 \
  -v lethean_data:/data \
  letheanio/letheand:latest

Run the wallet:

docker run -d --name lethean_wallet \
  -p 36944:36944 \
  -v lethean_wallet:/wallet \
  --entrypoint simplewallet \
  letheanio/letheand:latest \
  --rpc-bind-ip=0.0.0.0 --rpc-bind-port=36944 \
  --daemon-address=letheand:36941 \
  --wallet-file=/wallet/wallet --password=""

Development

Requirements

• .NET 8.0 SDK
• Git
• Docker and Docker Compose

Clone and build

git clone --recurse-submodules https://github.com/lethean-io/btcpayserver-lethean-plugin
cd btcpayserver-lethean-plugin
dotnet build btcpay-lethean-plugin.sln

Run unit tests

dotnet test BTCPayServer.Plugins.UnitTests

Run integration tests

docker compose -f BTCPayServer.Plugins.IntegrationTests/docker-compose.yml run tests

Local development

Start the dev dependencies:

cd BTCPayServer.Plugins.IntegrationTests/
docker compose up -d dev

Create appsettings.dev.json in btcpayserver/BTCPayServer:

{
  "DEBUG_PLUGINS": "../../Plugins/Lethean/bin/Debug/net8.0/BTCPayServer.Plugins.Lethean.dll",
  "LTHN_DAEMON_URI": "http://127.0.0.1:36941",
  "LTHN_WALLET_DAEMON_URI": "http://127.0.0.1:36944"
}

Then run BTCPay Server with the plugin loaded.

Technical details

• Address generation: Integrated addresses with random 8-byte payment IDs (unique per invoice)
• Payment detection: Polls get_bulk_payments every 15 seconds
• Fee: Fixed 0.01 LTHN per transaction
• Divisibility: 12 decimal places
• Rate source: CoinGecko (LTHN_BTC)
• Confirmations: Configurable (0, 1, 10, or custom)

License

MIT