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.
Version 0.1.7 Now implements the Coinos.io REST Api end points along with many additional Greenfield Api end points.
Below 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.7 04/16/2025 cadayton Added suport for Coinos.io REST Api
0.1.6 03/30/2025 cadayton Greenfield Api Added GetLnAddresses and GetLnAddress methods
0.1.5 03/30/2025 cadayton Greenfield Api Added GetFile and DeleteFile method
0.1.4 03/28/2025 cadayton Greenfield Api Added UploadFile method to upload a file to the BTCpay server
0.1.3 03/27/2025 cadayton Greenfield Api Added GetFiles returns listing of files uploaded to BTCpay server
0.1.2 03/19/2025 cadayton LND Api ForwardingHistory new parameter "total_fees" tallys mfees for events returned
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.
The above json file is updated with the correct information when making a COS-CreateInvoice api call.
The above json file is updated with the correct information when making a COS-Register 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 GetNodeBal
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.
View information about the lightning node
BTCpay GetNodeInfo
nodeURIs : {02f576c4fe7ec82a459dbc194b33b55f4e9a606442f69464a90e18f7bea9e4b414@155.248.200.221:9
735, 02f576c4fe7ec82a459dbc194b44b55f4e9a606442f69464a90e18f7bea9e4b414@xbwg6xxlgw24v
f4z2ddzsvqg8claril2xyxncqqp9rzeibj64dwrvvyd.onion:9735}
blockHeight : 893396
alias : LIGHTNING_NODE
color : #3399ff
version : 0.18.5-beta commit=basedon-v0.18.5-beta-fresh-btcpay
peersCount : 210
activeChannelsCount : 209
inactiveChannelsCount : 0
pendingChannelsCount : 0
View information about the lightning node channels
BTCpay GetNodeChannels
remoteNode : 021eb4cebc4aee0e565d6ec77131065e817ad69c6c7577e0582e14ca06c502596a
isPublic : True
isActive : True
capacity : 1000000000
localBalance : 276216000
channelPoint : 5049be9c508ccfeae2d69c1fe5905b4918bdad5776606c6d8a60e1f01f8c5d0b-1
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.
Returns a list of files uploaded to BTCpay Server and creates a tinyurl for each file.
BTCpay GetFiles
Created Name URL
------- ---- ---
03-17-2025 23:03 File1.jpeg https://tinyurl.com/2c5rsag5
03-17-2025 23:03 File2.jpeg https://tinyurl.com/29c5lmh2
03-10-2025 19:03 File3.png https://tinyurl.com/2zsh5x89
03-10-2025 19:03 File4.zip https://tinyurl.com/2bcfexxs
02-16-2025 15:02 File5.ps1 https://tinyurl.com/2fenbj5f
Uploads a file to the BTCpay Server.
BTCpay UploadFile detect.sh
Since path information is not included with the file name, the $HOME directory will be searched for the file.
View information about the specified file
BTCpay GetFile 5f753389-a286-450b-a646-4471e2b7737b
id : 5f753389-a286-450b-a646-4471e2b7737b
userId : 9e638aaf-a45c-4f07-8e91-062cd01c7fc6
uri : fileid:b34959af-d810-4c3d-9263-117ca18b8705
url : https:///LocalStorage/50dcd3e5-6ecc-4180-acc5-b03d113610a5-detect.sh
originalName : detect.sh
storageName : 50dcd3e5-6ecc-4180-acc5-b03d113610a5-detect.sh
createdAt : 1743214224
Deletes the specified file
BTCpay DeleteFile 5f753389-a286-450b-a646-4471e2b7737b
This file as been deleted
Get Lightning addresses for a specified store ID
BTCpay GetLnAddresses
List the lightning address information for addresses configured on the default store ID
BTCpay GetLnAddresses
List the lightning address information for addresses configured on the specified store ID
Get an on-chain deposit address for the lightning node
BTCpay GetDepositAddress
Default is to get a BTC deposit address for the lightning node
BTCpay GetDepositAddress
should support future supported currencies.
Information about the server, chains and sync states
BTCpay GetServerInfo
Returns the following details:
syncStatus :
version : 2.0.7
onion :
supportedPaymentMethods : {BTC-CHAIN, BTC-LN, BTC-LNURL}
fullySynched :
View information about the store's roles at the server's scope
BTCPay GetStoreRoles
View information about the specified wallet
BTCPay GetWalletOverview
Returns following output:
"balance": "string",
"unconfirmedBalance": "string",
"confirmedBalance": "string"
View the balance histogram of the specified wallet
BTCpay GetWalletHistogram
Coinos REST Api Documentation
Get account details and balance
Return object with values for the following
about, balance, banner, currencies, currency, display, email, fiat, haspin, id, npub,
nwc, picture, prompt, pubkey, username, verified
Get all payments sent or received by the current user
BTCpay COS-payments
returns PSCustomObject
Name MemberType Definition
---- ---------- ----------
count NoteProperty long count=1
incoming NoteProperty System.Management.Automation.PSCustomObject incoming=@{USD=}
outgoing NoteProperty System.Management.Automation.PSCustomObject outgoing=
payments NoteProperty Object[] payments=System.Object[]
Login to an account to get its auth token
BTCpay COS-login
Logs in with the default account configured in BTCpayApiCfg.xml
BTCpay COS-login username
Logs in with the specified username and the password is exacted from the password manager
returns PSCustomObject
Name MemberType Definition
---- ---------- ----------
token NoteProperty string token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImQ2Nzk1YTAxLTgβ¦
user NoteProperty System.Management.Automation.PSCustomObject user=@{about=; banner=https:/β¦
Create a lightning or Bitcoin invoice
BTCpay COS-CreateInvoice ,lightning | bitcoin
BTCpay COS-CreateInvoice 100,lightning
Successfully create a lightning invoice for 100 sats using USD
Invoice details have been saved in $HOME/ps/COS-Invoice-lightning-lnbc150n1p5q8cp.xml
Execute: BTCpay COS-ShowInvoice to see all invoice details
Display details of a saved invoice created with the COS-CreateInvoice execution
BTCpay COS-ShowInvoice
Displays a file list of saved invoices
BTCpay COS-ShowInvoice COS-Invoice-lightning-lnbc150n1p5q8cp.xml
list the details of a saved invoice
Fetch an invoice by passing a bitcoin address or lightning payment hash
BTCpay COS-GetInvoice
Get invoice details for (bitcoin or lightning)?:
Copy the Lighnting Payment Hash to the Clipboard Press enter when ready:
Register a new user account with a username and password
BTCpay COS-Register username,password
Send a lightning payment
BTCPay COS-PayLNinvoice
Pay Lightning Invoice
Copy Lightning Invoice to the clipboard and Press 'Enter' when ready
Send an internal payment to another Coinos user
BTCpay COS-PayInternal username,sats
Send a bitcoin payment
BTCpay COS-PayBitcoin address,sats
WARNING the last 3 payment API calls haven't been fully tested.
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.