Methods for synchronizing metadata about Lightning Network nodes, channels, and payments.
Confirm that a peer will accept a channel open
{
capacity: <Channel Capacity Tokens Number>
[cooperative_close_address]: <Restrict Coop Close To Address String>
[give_tokens]: <Tokens to Gift To Partner Number> // Defaults to zero
[is_private]: <Channel is Private Bool> // Defaults to false
lnd: <Authenticated LND API Object>
[min_htlc_mtokens]: <Minimum HTLC Millitokens String>
[partner_csv_delay]: <Peer Output CSV Delay Number>
partner_public_key: <Public Key Hex String>
}
@returns via cbk or Promise
{
is_accepted: <Channel Proposal Is Accepted Bool>
}
Ask to get a chain fee rate
{
ask: <Inquirer Ask Function>
lnd: <Authenticated LND API Object>
}
@returns via cbk or Promise
{
tokens_per_vbyte: <Chain Fee Tokens Per VByte Number>
}
Assemble an unsigned PSBT with funding from multiple parties
{
capacity: <Channel Capacity Tokens Number>
proposed: [{
[change]: <Change Output Hex String>
[funding]: [<Funding Output Hex String>]
utxos: [{
[non_witness_utxo]: <Spending Transaction Hex String>
transaction_id: <Transaction Id Hex String>
transaction_vout: <Transaction Output Index Number>
witness_utxo: {
script_pub: <Witness Output Script Hex String>
tokens: <Tokens Number>
}
}]
}]
rate: <Fee Rate Number>
}
@returns via cbk or Promise
{
psbt: <Unsigned Funding Transaction PSBT Hex String>
}
Broadcast a chain transaction until it gets confirmed in a block
{
[description]: <Transaction Description String>
lnd: <Authenticated LND API Object>
logger: <Winston Logger Object>
transaction: <Transaction String>
}
@returns via cbk or Promise
{
transaction_confirmed_in_block: <Block Height Number>
}
Connect a peer
{
id: <Node Public Key Hex String>
lnd: <Authenticated LND API Object>
[sockets]: [<Host Network Address And Optional Port String>]
}
@returns via cbk or Promise
Find a confirmed on-chain output
{
lnd: <Authenticated LND API Object>
[min_confirmations]: <Minimum Confirmations Count Number>
output_script: <Chain Output Script Hex String>
start_height: <Start Chain Height Number>
timeout_ms: <Timeout Milliseconds Number>
tokens: <Tokens Sent To Script Number>
}
@returns via cbk or Promise
{
confirmation_height: <Transaction Confirmed At Height Number>
is_coinbase: <Transaction is Coinbase Transaction Bool>
transaction_id: <Transaction Id Hex String>
transaction_vout: <Transaction Output Index Number>
}
Find a public key given a query
{
[channels]: [{
partner_public_key: <Partner Public Key Hex String>
}]
lnd: <Authenticated LND API Object>
[query]: <Query String>
}
@returns via cbk or Promise
{
[public_key]: <Public Key Hex String>
}
Format tokens for display
{
is_monochrome: <Avoid Applying Colors Bool>
tokens: <Tokens Number>
}
@returns
{
display: <Display Formatted Tokens String>
}
Get all invoices
{
[confirmed_after]: <Confirmed At or After ISO 8601 Date String>
[created_after]: <Confirmed At or After ISO 8601 Date String>
lnd: <Authenticated LND API Object>
}
@returns via cbk or Promise
{
invoices: [{
[chain_address]: <Fallback Chain Address String>
cltv_delta: <Final CLTV Delta Number>
[confirmed_at]: <Settled at ISO 8601 Date String>
created_at: <ISO 8601 Date String>
description: <Description String>
[description_hash]: <Description Hash Hex String>
expires_at: <ISO 8601 Date String>
features: [{
bit: <BOLT 09 Feature Bit Number>
is_known: <Feature is Known Bool>
is_required: <Feature Support is Required To Pay Bool>
type: <Feature Type String>
}]
id: <Payment Hash String>
[is_canceled]: <Invoice is Canceled Bool>
is_confirmed: <Invoice is Confirmed Bool>
[is_held]: <HTLC is Held Bool>
is_private: <Invoice is Private Bool>
[is_push]: <Invoice is Push Payment Bool>
payments: [{
[confirmed_at]: <Payment Settled At ISO 8601 Date String>
created_at: <Payment Held Since ISO 860 Date String>
created_height: <Payment Held Since Block Height Number>
in_channel: <Incoming Payment Through Channel Id String>
is_canceled: <Payment is Canceled Bool>
is_confirmed: <Payment is Confirmed Bool>
is_held: <Payment is Held Bool>
messages: [{
type: <Message Type Number String>
value: <Raw Value Hex String>
}]
mtokens: <Incoming Payment Millitokens String>
[pending_index]: <Pending Payment Channel HTLC Index Number>
tokens: <Payment Tokens Number>
[total_mtokens]: <Total Millitokens String>
}]
received: <Received Tokens Number>
received_mtokens: <Received Millitokens String>
[request]: <Bolt 11 Invoice String>
secret: <Secret Preimage Hex String>
tokens: <Tokens Number>
}]
}
Get a funded transaction
{
ask: <Inquirer Ask Function>
[chain_fee_tokens_per_vbyte]: <Internal Funding Uses Tokens/Vbyte Number>
[is_external]: <Transaction Uses External Funds Bool>
lnd: Authenticated LND API Object>
logger: <Winston Logger Object>
outputs: [{
address: <Chain Address String>
tokens: <Tokens To Send To Output Number>
}]
}
@returns via cbk or Promise
{
id: <Transaction Id Hex String>
[inputs]: [{
[lock_expires_at]: <UTXO Lock Expires At ISO 8601 Date String>
[lock_id]: <UTXO Lock Id Hex String>
transaction_id: <Transaction Hex Id String>
transaction_vout: <Transaction Output Index Number>
}]
[psbt]: <Transaction As Finalized PSBT Hex String>
transaction: <Raw Transaction Hex String>
}
Get the channel available liquidity
A request function is required when min_node_score is specified
{
[is_outbound]: <Return Outbound Liquidity Bool>
[is_top]: <Return Top Liquidity Bool>
lnd: <Authenticated LND API Object>
[min_node_score]: <Minimum Node Score Number>
[max_fee_rate]: <Max Inbound Fee Rate Parts Per Million Number>
[request]: <Request Function>
[with]: [<Liquidity With Specific Node Public Key Hex String>]
}
@returns via cbk
{
tokens: [<Liquidity Tokens Number>]
}
Get network name for lnd
{
lnd: <Authenticated LND API Object>
}
@returns via cbk or Promise
{
[bitcoinjs]: <Bitcoin JS Network Name String>
network: <Network Name String>
}
Get the alias of a node, ignoring errors
{
id: <Node Identity Public Key Hex String>
lnd: <Authenticated LND API Object>
}
@returns via cbk or Promise
{
alias: <Node Alias String>
id: <Node Identity Public Key Hex String>
}
Get a detailed balance that categorizes balance of tokens on the node
{
[is_confirmed]: <Only Consider Confirmed Transactions Bool>
lnd: <Authenticated LND API Object>
}
@returns via cbk or Promise
{
[closing_balance]: <Total Coins Closing Tokens Number>
[conflicted_pending]: <Conflicted Transaction Tokens Number>
[invalid_pending]: <Invalid Pending Tokens Tokens Number>
[offchain_balance]: <Channel Tokens Balance Tokens Number>
[offchain_pending]: <Pending Channel Tokens Balance Tokens Number>
[onchain_confirmed]: <Confirmed On Chain Balance Tokens Number>
[onchain_pending]: <Pending Chain Tokens Balance Tokens Number>
[onchain_vbytes]: <UTXO Footprint Virtual Bytes Number>
[utxos_count]: <Total UTXOs Count Number>
}
Find the max amount that can be used for funding outputs given inputs
{
addresses: [<Send to Address String>]
fee_tokens_per_vbyte: <Funding Fee Tokens Per VByte Number>
inputs: [{
tokens: <Input Tokens Number>
transaction_id: <UTXO Transaction Id Hex String>
transaction_vout: <UTXO Transaction Output Index Number>
}]
lnd: <Authenticated LND API Object>
}
@returns via cbk or Promise
{
fee_tokens_per_vbyte: <Effective Final Fee Tokens Per VByte Number>
max_tokens: <Maximum Spendable Tokens Number>
}
Get payments
{
[after]: <Get Only Payments Create At Or After ISO 8601 Date String>
lnd: <Authenticated LND API Object>
}
@returns via cbk or Promise
{
payments: [{
attempts: [{
[failure]: {
code: <Error Type Code Number>
[details]: {
[channel]: <Standard Format Channel Id String>
[height]: <Error Associated Block Height Number>
[index]: <Failed Hop Index Number>
[mtokens]: <Error Millitokens String>
[policy]: {
base_fee_mtokens: <Base Fee Millitokens String>
cltv_delta: <Locktime Delta Number>
fee_rate: <Fees Charged in Millitokens Per Million Number>
[is_disabled]: <Channel is Disabled Bool>
max_htlc_mtokens: <Maximum HLTC Millitokens Value String>
min_htlc_mtokens: <Minimum HTLC Millitokens Value String>
updated_at: <Updated At ISO 8601 Date String>
}
[timeout_height]: <Error CLTV Timeout Height Number>
[update]: {
chain: <Chain Id Hex String>
channel_flags: <Channel Flags Number>
extra_opaque_data: <Extra Opaque Data Hex String>
message_flags: <Message Flags Number>
signature: <Channel Update Signature Hex String>
}
}
message: <Error Message String>
}
[index]: <Payment Add Index Number>
is_confirmed: <Payment Attempt Succeeded Bool>
is_failed: <Payment Attempt Failed Bool>
is_pending: <Payment Attempt is Waiting For Resolution Bool>
route: {
fee: <Route Fee Tokens Number>
fee_mtokens: <Route Fee Millitokens String>
hops: [{
channel: <Standard Format Channel Id String>
channel_capacity: <Channel Capacity Tokens Number>
fee: <Fee Number>
fee_mtokens: <Fee Millitokens String>
forward: <Forward Tokens Number>
forward_mtokens: <Forward Millitokens String>
[public_key]: <Forward Edge Public Key Hex String>
[timeout]: <Timeout Block Height Number>
}]
mtokens: <Total Fee-Inclusive Millitokens String>
[payment]: <Payment Identifier Hex String>
timeout: <Timeout Block Height Number>
tokens: <Total Fee-Inclusive Tokens Number>
[total_mtokens]: <Total Millitokens String>
}
}]
created_at: <Payment at ISO-8601 Date String>
destination: <Destination Node Public Key Hex String>
fee: <Paid Routing Fee Rounded Down Tokens Number>
fee_mtokens: <Paid Routing Fee in Millitokens String>
hops: [<First Route Hop Public Key Hex String>]
id: <Payment Preimage Hash String>
[index]: <Payment Add Index Number>
is_confirmed: <Payment is Confirmed Bool>
is_outgoing: <Transaction Is Outgoing Bool>
mtokens: <Millitokens Sent to Destination String>
[request]: <BOLT 11 Payment Request String>
safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
safe_tokens: <Payment Tokens Rounded Up Number>
secret: <Payment Preimage Hex String>
tokens: <Rounded Down Tokens Sent to Destination Number>
}]
}
Get the rundown on liquidity with a specific peer
{
lnd: <Authenticated LND API Object>
public_key: <Peer Public Key Hex String>
[settled]: <Known Settled Payment Id String>
}
@returns via cbk or Promise
{
alias: <Alias String>
inbound: <Inbound Liquidity Tokens Number>
inbound_pending: <Pending Inbound Liquidity Tokens Number>
outbound: <Outbound Liquidity Tokens Number>
outbound_pending: <Pending Outbound Liquidity Tokens Number>
}
Get payments that were rebalances
{
after: <Rebalance Payments After ISO 8601 Date String>
lnds: [<Authenticated LND API Object>]
}
@returns via cbk or Promise
{
payments: [{
attempts: [{
[failure]: {
code: <Error Type Code Number>
[details]: {
[channel]: <Standard Format Channel Id String>
[height]: <Error Associated Block Height Number>
[index]: <Failed Hop Index Number>
[mtokens]: <Error Millitokens String>
[policy]: {
base_fee_mtokens: <Base Fee Millitokens String>
cltv_delta: <Locktime Delta Number>
fee_rate: <Fees Charged in Millitokens Per Million Number>
[is_disabled]: <Channel is Disabled Bool>
max_htlc_mtokens: <Maximum HLTC Millitokens Value String>
min_htlc_mtokens: <Minimum HTLC Millitokens Value String>
updated_at: <Updated At ISO 8601 Date String>
}
[timeout_height]: <Error CLTV Timeout Height Number>
[update]: {
chain: <Chain Id Hex String>
channel_flags: <Channel Flags Number>
extra_opaque_data: <Extra Opaque Data Hex String>
message_flags: <Message Flags Number>
signature: <Channel Update Signature Hex String>
}
}
message: <Error Message String>
}
[index]: <Payment Add Index Number>
[confirmed_at]: <Payment Confirmed At ISO 8601 Date String>
is_confirmed: <Payment Attempt Succeeded Bool>
is_failed: <Payment Attempt Failed Bool>
is_pending: <Payment Attempt is Waiting For Resolution Bool>
route: {
fee: <Route Fee Tokens Number>
fee_mtokens: <Route Fee Millitokens String>
hops: [{
channel: <Standard Format Channel Id String>
channel_capacity: <Channel Capacity Tokens Number>
fee: <Fee Number>
fee_mtokens: <Fee Millitokens String>
forward: <Forward Tokens Number>
forward_mtokens: <Forward Millitokens String>
[public_key]: <Forward Edge Public Key Hex String>
[timeout]: <Timeout Block Height Number>
}]
mtokens: <Total Fee-Inclusive Millitokens String>
[payment]: <Payment Identifier Hex String>
timeout: <Timeout Block Height Number>
tokens: <Total Fee-Inclusive Tokens Number>
[total_mtokens]: <Total Millitokens String>
}
}]
confirmed_at: <Payment Confirmed At ISO 8601 Date String>
created_at: <Payment at ISO-8601 Date String>
destination: <Destination Node Public Key Hex String>
fee: <Paid Routing Fee Rounded Down Tokens Number>
fee_mtokens: <Paid Routing Fee in Millitokens String>
hops: [<First Route Hop Public Key Hex String>]
id: <Payment Preimage Hash String>
[index]: <Payment Add Index Number>
is_confirmed: <Payment is Confirmed Bool>
is_outgoing: <Transaction Is Outgoing Bool>
mtokens: <Millitokens Sent to Destination String>
[request]: <BOLT 11 Payment Request String>
safe_fee: <Payment Forwarding Fee Rounded Up Tokens Number>
safe_tokens: <Payment Tokens Rounded Up Number>
secret: <Payment Preimage Hex String>
tokens: <Rounded Down Tokens Sent to Destination Number>
}]
}
Get scored nodes
{
network: <Network Name String>
request: <Request Function>
}
@returns via cbk or Promise
{
nodes: [{
public_key: <Public Key Hex String>
score: <Forwarding Quality Score Out Of One Hundred Million Number>
}]
}
Get LND internal record associated with a transaction id
{
[chain_transactions]: [{
[block_id]: <Block Hash String>
[confirmation_count]: <Confirmation Count Number>
[confirmation_height]: <Confirmation Block Height Number>
created_at: <Created ISO 8601 Date String>
[description]: <Transaction Label String>
[fee]: <Fees Paid Tokens Number>
id: <Transaction Id String>
is_confirmed: <Is Confirmed Bool>
is_outgoing: <Transaction Outbound Bool>
output_addresses: [<Address String>]
tokens: <Tokens Including Fee Number>
[transaction]: <Raw Transaction Hex String>
}]
[channels]: [{
capacity: <Capacity Tokens Numberr>
id: <Standard Format Short Channel Id Hex String>
partner_public_key: <Peer Public Key Hex String>
transaction_id: <Channel Transaction Id Hex String>
}]
[closed_channels]: [{
capacity: <Closed Channel Capacity Tokens Number>
[close_balance_spent_by]: <Channel Balance Output Spent By Tx Id String>
[close_balance_vout]: <Channel Balance Close Tx Output Index Number>
[close_confirm_height]: <Channel Close Confirmation Height Number>
close_payments: [{
is_outgoing: <Payment Is Outgoing Bool>
is_paid: <Payment Is Claimed With Preimage Bool>
is_pending: <Payment Resolution Is Pending Bool>
is_refunded: <Payment Timed Out And Went Back To Payer Bool>
[spent_by]: <Close Transaction Spent By Transaction Id Hex String>
tokens: <Associated Tokens Number>
transaction_id: <Transaction Id Hex String>
transaction_vout: <Transaction Output Index Number>
}]
[close_transaction_id]: <Closing Transaction Id Hex String>
final_local_balance: <Channel Close Final Local Balance Tokens Number>
final_time_locked_balance: <Closed Channel Timelocked Tokens Number>
[id]: <Closed Standard Format Channel Id String>
is_breach_close: <Is Breach Close Bool>
is_cooperative_close: <Is Cooperative Close Bool>
is_funding_cancel: <Is Funding Cancelled Close Bool>
is_local_force_close: <Is Local Force Close Bool>
[is_partner_closed]: <Channel Was Closed By Channel Peer Bool>
[is_partner_initiated]: <Channel Was Initiated By Channel Peer Bool>
is_remote_force_close: <Is Remote Force Close Bool>
partner_public_key: <Partner Public Key Hex String>
transaction_id: <Channel Funding Transaction Id Hex String>
transaction_vout: <Channel Funding Output Index Number>
}]
id: <Transaction Id Hex String>
lnd: <Authenticated LND API Object>
[pending_channels]: [{
[close_transaction_id]: <Channel Closing Transaction Id String>
is_active: <Channel Is Active Bool>
is_closing: <Channel Is Closing Bool>
is_opening: <Channel Is Opening Bool>
is_partner_initiated: <Channel Partner Initiated Channel Bool>
local_balance: <Channel Local Tokens Balance Number>
local_reserve: <Channel Local Reserved Tokens Number>
partner_public_key: <Channel Peer Public Key String>
[pending_balance]: <Tokens Pending Recovery Number>
[pending_payments]: [{
is_incoming: <Payment Is Incoming Bool>
timelock_height: <Payment Timelocked Until Height Number>
tokens: <Payment Tokens Number>
transaction_id: <Payment Transaction Id String>
transaction_vout: <Payment Transaction Vout Number>
}]
received: <Tokens Received Number>
[recovered_tokens]: <Tokens Recovered From Close Number>
remote_balance: <Remote Tokens Balance Number>
remote_reserve: <Channel Remote Reserved Tokens Number>
sent: <Send Tokens Number>
[timelock_expiration]: <Pending Tokens Block Height Timelock Number>
[transaction_fee]: <Funding Transaction Fee Tokens Number>
transaction_id: <Channel Funding Transaction Id String>
transaction_vout: <Channel Funding Transaction Vout Number>
[transaction_weight]: <Funding Transaction Weight Number>
}]
}
@returns via cbk or Promise
{
[chain_fee]: <Paid Transaction Fee Tokens Number>
[received]: <Received Tokens Number>
related_channels: [{
action: <Channel Action String>
[balance]: <Channel Balance Tokens Number>
[capacity]: <Channel Capacity Value Number>
[channel]: <Channel Standard Format Id String>
[close_tx]: <Channel Closing Transaction Id Hex String>
[open_tx]: <Channel Opening Transaction id Hex String>
[timelock]: <Channel Funds Timelocked Until Height Number>
with: <Channel Peer Public Key Hex String>
}]
[sent]: <Sent Tokens Number>
[sent_to]: [<Sent to Address String>]
[tx]: <Transaction Id Hex String>
}
Make a refund transaction for transit funds
{
funded_tokens: <Tokens Sent to Transit Address Number>
lnd: <Authenticated LND API Object>
network: <Network Name String>
refund_address: <Refund Coins to On Chain Address String>
transit_address: <Transit On Chain Bech32 Address String>
transit_key_index: <Transit Key Index Number>
transit_public_key: <Transit Public Key Hex String>
transaction_id: <Transaction Id Hex String>
transaction_vout: <Transaction Output Index Number>
}
@returns via cbk or Promise
{
refund: <Fully Signed Refund Transaction Hex String>
}
Get on-chain funding and a refund
{
ask: <Ask Function>
lnd: <Authenticated LND API Object>
logger: <Winston Logger Object>
[rate]: <Chain Fee Rate Tokens Per VByte Number>
tokens: <Fund Tokens Number>
}
@returns via cbk or Promise
{
address: <Transit Address String>
id: <Transaction Id Hex String>
index: <Transit Public Key Index Number>
[inputs]: [{
[lock_expires_at]: <UTXO Lock Expires At ISO 8601 Date String>
[lock_id]: <UTXO Lock Id Hex String>
transaction_id: <Transaction Hex Id String>
transaction_vout: <Transaction Output Index Number>
}]
key: <Transit Key Public Key Hex String>
output: <Transit Output Script Hex String>
[psbt]: <Transaction As Finalized PSBT Hex String>
refund: <Refund Transaction Hex String>
script: <Transit Signing Witness Script Hex String>
transaction: <Raw Transaction Hex String>
vout: <Funds Reserved At Output Index Number>
}
Partially sign and fund a PSBT and create a conflicting transaction
Only P2TR and P2WPKH inputs are supported
To allow for funding a channel, a dummy "finalized" PSBT is returned
{
lnd: <Authenticated Signing LND API Object>
psbt: <Base Funding With Bare Inputs PSBT Hex String>
utxos: [{
bip32_derivations: [{
fingerprint: <Public Key Fingerprint Hex String>
[leaf_hashes]: <Taproot Leaf Hash Hex String>
path: <BIP 32 Child / Hardened Child / Index Derivation Path String>
public_key: <Public Key Hex String>
}]
[non_witness_utxo]: <UTXO Spending Transaction Hex String>
transaction_id: <Unspent Transaction Id Hex String>
transaction_vout: <Unspent Transaction Output Index Number>
witness_utxo: {
script_pub: <UTXO Output Script Hex String>
tokens: <UTXO Tokens Value Number>
}
}]
}
@returns via cbk or Promise
{
conflict: <Conflict Transaction Hex String>
funding: <Funding Dummy PSBT Hex String>
psbt: <Partially Signed PSBT Hex String>
}
Update the fee for an individual channel
{
[base_fee_mtokens]: <Base Fee Millitokens String>
[cltv_delta]: <CLTV Delta to Use Number>
fee_rate: <Fee Rate Number>
from: <Local Node Public Key Hex String>
[inbound_rate_discount]: <Source Based PPM Fee Rate Discount Number>
lnd: <Authenticated LND API Object>
[max_htlc_mtokens]: <Maximum HTLC Millitokens to Forward String>
[min_htlc_mtokens]: <Minimum HTLC Millitokens to Forward String>
transaction_id: <Funding Transaction Id Hex String>
transaction_vout: <Funding Transaction Output Index Number>
}
@returns via cbk or Promise
Wait for a peer to connect
{
id: <Node Identity Public Key Hex String>
lnd: <Authenticated LND API Object>
[timeout]: <Timeout Milliseconds Number>
}
@returns via cbk or Promise
Wait for an incoming pending open channel matching specific criteria
{
[capacity]: <Channel Capacity Tokens Number>
interval: <Check Time Milliseconds Number>
lnd: <Authenticated LND API Object>
local_balance: <Starting Local Balance Number>
partner_public_key: <Peer Public Key Hex String>
times: <Total Check Times Number>
transaction_id: <Transaction Id Hex String>
transaction_vout: <Transaction Output Index Number>
}
@returns via cbk or Promise
{
transaction_id: <Transaction Id Hex String>
transaction_vout: <Transaction Output Index Number>
}