Current REST APIs supported are
BTCpay executes on the input provided then executes BTCpayApi which makes the appropriate REST api calls and outputs the results for human consumption.
These scripts are used daily to interact with my BTCPay server and LND Lightning node instances running in the cloud.
It is nice to be able to check on the status of stuff and make changes without have to log into a Web interface. The other added benefit if needed is the ability to fully automate any repetitve work that needs to happen. My grand plan is to add other REST Api(s) that are Bitcoin and Lightning related like Coinos.
Here is an example of executing the ListChannels Api call
Active Public Payment Channels
Node Active Capacity RemBalance(In) LocBalance(Out) Sent Received HTLCs Fee Weight
---- ------ -------- -------------- --------------- ---- -------- ----- --- ------
Node1 True 1,000,000 118,175 880,534 4,060,999 3,942,824 0 631 1116
Node2 True 1,000,000 158,246 840,497 1,060,684 902,438 0 597 1116
Node3 True 1,000,000 527,966 470,743 2,746,878 2,218,912 0 631 1116
Node4 True 260,000 13,661 245,082 3,306,025 3,292,364 0 597 1116
Node5 True 1,000,000 977,953 20,756 7,321,434 7,342,191 0 631 1116
Node6 True 115,459 98,920 15,316 931,880 947,196 0 563 1116
Node7 True 1,000,000 983,904 14,839 24,526,583 23,542,679 0 597 1116
Node8 True 200,000 189,105 9,604 1,682,898 1,493,793 0 631 1116
The BTCpay and BTCpayApi scripts do NOT store any sensitivity data and requires either manual input for this data or a supported implementation of a password manager for retrieving this type of data.
The supported and tested password manager applications are Keybase and Hashicorp Vault.
Keybase also requires installation of PSKeyBase and Keybase client
Hashicorp Vault also requires installation of VaultApi and Hashicorp Vault server
Any password manager that has a CLI available should work too.
These scripts can be executed on any OS supporting PowerShell Core.
Currently only tested on Linux OS.
PS> Get-Help BTCpay
PS> Get-Help BTCpay -full
PS> Get-Help BTCpay -Examples
The -Examples option above shows the full set of commands available in BTCpay.
SYNTAX
BTCpay 'command1,command2' ['option1,option2']
Version Date Whom Notes
======= ==== ======== =====================================================
0.1.0 03/15/2025 cadayton Initial release
In the above xml file there needs to be a node alias assigned for each of your public channels.
The above json file is updated with the correct information when making a SendPaymentV2 api call.
This configuration is used for gathering sensitive data from the password manager application.
Install Gpaste for clipboard functionality
sudo apt install xclip xsel
sudo apt install gpaste
See the following links for a guide on how to setup a Bitcoin wallet and use it with Cold Storage
Bitcoin and key/value using Hashicorp Vault
PS> BTCpay ListChannels
Active Public Payment Channels
Node Active Capacity RemBalance(In) LocBalance(Out) Sent Received HTLCs Fee Weight
---- ------ -------- -------------- --------------- ---- -------- ----- --- ------
Node1 True 1,000,000 118,175 880,534 4,060,999 3,942,824 0 631 1116
Node2 True 1,000,000 158,246 840,497 1,060,684 902,438 0 597 1116
Node3 True 1,000,000 527,966 470,743 2,746,878 2,218,912 0 631 1116
Node4 True 260,000 13,661 245,082 3,306,025 3,292,364 0 597 1116
Node5 True 1,000,000 977,953 20,756 7,321,434 7,342,191 0 631 1116
Node6 True 115,459 98,920 15,316 931,880 947,196 0 563 1116
Node7 True 1,000,000 983,904 14,839 24,526,583 23,542,679 0 597 1116
Node8 True 200,000 189,105 9,604 1,682,898 1,493,793 0 631 1116
$r = BTCpay ListChannels noformat --- With this option, the same data as above is return in array represented by $r
$r = BTCpay ListChannels raw ... With this option, the full set of channel attributes are returned in an array from the API call. This option will not have the node alias attribute because API data doesn't contain the node alias.
The BalanceChannel is performing a Circular Rebalance of the liquidity between two channels with execessive liquidity on either end of the channel.
This operation is making 2 API calls AddInvoice and SendPaymentV2 as well as prompting for input.
Referring to the ListChannels example, we see that Node1 channel as a Local balance of 880,534 sats while the Node7 channel has Remote balance of 983,904 sats. Notice that the ListChannels output sorts on a descending order of the LocBalance(Out) column. One should always do a Circular Rebalance between channels that have a high LocBalance(Out) balance and a channel with high RemBalance(In) balance.
For this example, sats will be moved from Node1 channel to Node7 channel.
$paym = BTCpay BalanceChannel Node1,Node7,2000
Proceed with sending 2088 sats from channel Node1 to Node7 [Yes or No]:
Creating Invoice... Paying Invoice... Paid Invoice for 2088 sats satfee: 4 msatfee: 4783
If the ListChannels command is ran again, you'll notice that Node1's LocBalance(Out) has decreased by 2088 sats while it's RemBalance(In) balance has increased by the same amount. Node7's LocBalance(Out) balance will have increase by 2088 sats while it's RemBalance(In) balance has decrease by the same amount.
With the command BTCpay BalanceChannel Node1,Node7,2000 you may be asking why balances changed by 2088 sats and not the 2000 sats passed to the BalanceChannel command. This is because the sats value passed in is considered the minimum amount and the actual value will be a random value between the minimum plus 500 sats.
Also, notice in the command responce there was a charge of 4 sats for performing the transaction. This is fee charged by the lightning node operators.
If the payment fails, you'll be prompted has to whether or not to save the payment request. On the next execution of this command the prior payment request will be used. Also note on failure, the variable $paym may contain more information about the failure.
$result = BTCpay AddInvoice
$result = BTCpay AddInvoice value=1000,memo=testinvoice
On success, $result.payment_request contains the payment request. The first example will prompt for an amount in sats for the invoice. Reference the API documentation for the set of options that can be used.
BTCpay GetChannelAttribute Node1,chanid
This command returns the 'chanid' attribute associated with the node alias, Node1
Execute BTCpay ListChannels noformat to see the list of attributes that can be specified.
Sending a Circular Reblance payment from one payment channel to another channel. First AddInvoice command would need to be executed to create an payment invoice.
$result = BTCpay AddInvoice value=1000,memo=testinvoice
Second get the chan_id of the channel with a high Local balance compared to it's Remote balance
$chanid = BTCpay GetChannelAttribute Node1,chanid
Third get the pubkey of the channel with a high Remote balance compared to it's Local balance
$pubkey = BTCpay GetChannelAttribute Node7,pubkey
$paym = BTCpay SendPaymentV2 $chanid,$pubkey,$result.payment_request
Note the BalanceChannel command does all these steps for you so it should be easier so use.
List a summary of the inbound and outbound channel liquidity
BTCpay ChannelBalance
The command prints the following formatted output.
InOutBalance InBound OutBound PendingOpen PendingIn PendingOut UnsettleIn UnsettleOut
------------ ------- -------- ----------- --------- ---------- ---------- -----------
5,565,448 3,068,078 2,497,370 0 0 0 0 0
This command outputs a formatted table showing forwarding events for the last 14 days or from the start time specified.
BTCpay ForwardingHistory
BTCpay ForwardingHistory start_time=mm/dd/yyyy
TimeStamp Alias_in Amount_in Amt_in_msat Alias_out Amount_out Amt_out_msat fee fee_msat
--------- -------- --------- ----------- --------- ---------- ------------ --- --------
03-06-2025 06:03 Node1 20747 20747087 Node7 20746 20747087 0 719
03-06-2025 02:03 Node2 4634 4634913 Node7 4634 4634913 0 541
03-06-2025 02:03 Node3 11146 11146851 Node7 11146 11146851 0 613
GetInfo returns general information concerning the lightning node including it's identity pubkey, alias, the chains it is connected to, and information concerning the number of open+pending channels.
BTCpay GetInfo
mainnet Information
Chain Network Block Block TS ChainSync GraphSync Active InActive Pending Peers
----- ------- ----- -------- --------- --------- ------ -------- ------- -----
bitcoin mainnet 886908 1741461776 True True 8 0 0 10
$g = BTCpay GetInfo raw
$g is a PSCustomObject containing the attributes of the LND node.
$i = BTCpay ListInvoices creation_date_start=03/04/2025,creation_date_end=03/07/2025
$i = BTCpay ListInvoices pending_only=true
Return a list of invoices as a PSCustomObject base on the options specified.
Enter $i.invoices to list all invoices returned.
$p = BTCpay ListPeers
Returns a list of peers as a PSCustomObject.
Enter $p.peers to see listing of all peers.
QueryRoutes attempts to query the daemon's Channel Router for a possible route to a target destination capable of carrying a specific amount of satoshis.
Get the pubkey for a channel node alias.
$pubkey = BTCpay GetChannelAttribute Node1,pubkey
$sats = 5000
$qr = BTCpay QueryRoutes $pubkey,$sats
$qr is a PSCustomObject containing the route(s) details
WalletBalance returns total onchain unspent outputs(confirmed and unconfirmed), all confirmed unspent outputs and all unconfirmed unspent outputs under control of the wallet.
BTCpay WalletBalance
total_balance : 241377
confirmed_balance : 241377
unconfirmed_balance : 0
locked_balance : 0
reserved_balance_anchor_chan : 80000
account_balance : @{default=}
ListTowers returns the list of watchtowers registered with the client.
$t = BTCpay ListTowers
$t.towers
pubkey : AhQnbWDuzr7+ztbMko4g08zJAFDBiV0XPn57ImIZmA4T
addresses : {nqto7jwed3pdef7vsdte3xelshxep7ofoc7abceag5dcjd2jw5augqyd.onion:9911}
active_session_candidate : True
num_sessions : 341
sessions : {}
GetTowerInfo retrieves information for a registered watchtower.
$t = BTCpay ListTowers
BTCpay GetTowerInfo $t.towers.pubkey
pubkey : AhQnbWDuzr7+ztbMko4g08zJAFDBiV0XPn57ImIZmA4T
addresses : {nqto7jwed3pdef7vsdte3xelshxep7ofoc7abceag5dcjd2jw5augqyd.onion:9911}
active_session_candidate : True
num_sessions : 1
sessions : {}
Stats returns the in-memory statistics of the client since startup.
BTCpay WTstats
num_backups : 1815
num_pending_backups : 0
num_failed_backups : 0
num_sessions_acquired : 2
num_sessions_exhausted : 2
GetInfo returns general information concerning the companion watchtower including its public key and URIs where the server is currently listening for clients.
BTCpay WTGetInfo
pubkey listeners uris
------ --------- ----
A3ASdCUK5KrzOkLgD+TBre/W1OYraTx0KrcADOsz3tb1 {172.69.0.59:9911, 127.0.0.1:9911} {
ExportAllChannelBackups returns static channel backups for all existing channels known to lnd. A set of regular singular static channel backups for each channel are returned. Additionally, a multi-channel backup is returned as well, which contains a single encrypted blob containing the backups of each channel.
BTCpay ExportAllChannelBackups SCB
Creates a static channel backup file named, scb-.xml
scb-.xml has been updated
To load the SCB file
execute: BTCPay LoadChannelBackup
$b = BTCpay ExportAllChannelBackups
$b is a PSCustomObject containing the exported backup information
Retrieves the backup data contained in the static channel backup file named, scb-
$scb = BTCpay LoadChannelBackup
View balance of the lightning node
BTCpay nodebal
Onchain Balance:
Confirmed: 241377 sats
unconfirmed: 0 sats
reserved: 0 sats
Offchain Balance:
Local: 497370 sats
Remote: 068094 sats
Opening: 0 sats
Closing: 0 sats
$nb = BTCpay nodebal raw
$ng is a PSCustomObject containing the node balance data.
Get Point of Sale app data
$pos = BTCpay GetPointOfSaleApp
$pos is a PSCustomObject containing Point of Sale attributes.
Display each item in the Point of Sales app interactively on the terminal console.
BTCPay GetPointOfSaleApp
Getting Point of Sale items
psConsole Price: $1
A PowerShell launch utility that supports:
Starting OpenSSH, Remote sessions, opening URLs and starting applications.
See the following link for details.
https://cadayton.onrender.com/scripts/psConsole.html
Enter to continue...:
Returns sales statistics for the Point of Sales app
BTCpay GetAppSales
BarnYard Market Sales for the Last 7 Days
date label salesCount
---- ----- ----------
1740960000 Mar 03 0
1741046400 Mar 04 0
1741132800 Mar 05 0
1741219200 Mar 06 0
1741305600 Mar 07 0
1741392000 Mar 08 0
1741478400 Mar 09 0
BTCpay GetAppSales 30
Get the last 30 days of sales.
The scripts can be purchased and downloaded using Bitcoin or Lightning from the Barnyard Market
The downloaded file is zip file containing the script files and the configuration files.
The configuation files need to be updated with content meaningful to your environment and saved with the '-example' portion removed from the file name.
There is a 50% markup in price, if you are wanting to use fiat money to purchase the scripts.