SubscribeTransactions

SubscribeTransactions creates a uni-directional stream from the server to the client in which any newly discovered transactions relevant to the wallet are sent over.

Source: lightning.proto

gRPC

info

This is a server-streaming RPC

rpc SubscribeTransactions (GetTransactionsRequest) returns (stream Transaction);

REST

HTTP Method	Path
GET	/v1/transactions/subscribe

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('lightning.proto', loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new lnrpc.Lightning(GRPC_HOST, creds);
let request = {
  start_height: <int32>,
  end_height: <int32>,
  account: <string>,
};
let call = client.subscribeTransactions(request);
call.on('data', function(response) {
  // A response was received from the server.
  console.log(response);
});
call.on('status', function(status) {
  // The current status of the stream.
});
call.on('end', function() {
  // The server has closed the stream.
});
// Console output:
//  {
//    "tx_hash": <string>,
//    "amount": <int64>,
//    "num_confirmations": <int32>,
//    "block_hash": <string>,
//    "block_height": <int32>,
//    "time_stamp": <int64>,
//    "total_fees": <int64>,
//    "dest_addresses": <string>,
//    "output_details": <OutputDetail>,
//    "raw_tx_hex": <string>,
//    "label": <string>,
//    "previous_outpoints": <PreviousOutPoint>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the lightning.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import lightning_pb2 as lnrpc, lightning_pb2_grpc as lightningstub

GRPC_HOST = 'localhost:10009'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = lightningstub.LightningStub(channel)
request = lnrpc.GetTransactionsRequest(
  start_height=<int32>,
  end_height=<int32>,
  account=<string>,
)
for response in stub.SubscribeTransactions(request):
  print(response)
# {
#    "tx_hash": <string>,
#    "amount": <int64>,
#    "num_confirmations": <int32>,
#    "block_hash": <string>,
#    "block_height": <int32>,
#    "time_stamp": <int64>,
#    "total_fees": <int64>,
#    "dest_addresses": <string>,
#    "output_details": <OutputDetail>,
#    "raw_tx_hex": <string>,
#    "label": <string>,
#    "previous_outpoints": <PreviousOutPoint>,
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let options = {
  url: `https://${REST_HOST}/v1/transactions/subscribe`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
}
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "tx_hash": <string>, // <string> 
//    "amount": <string>, // <int64> 
//    "num_confirmations": <integer>, // <int32> 
//    "block_hash": <string>, // <string> 
//    "block_height": <integer>, // <int32> 
//    "time_stamp": <string>, // <int64> 
//    "total_fees": <string>, // <int64> 
//    "dest_addresses": <array>, // <string> 
//    "output_details": <array>, // <OutputDetail> 
//    "raw_tx_hex": <string>, // <string> 
//    "label": <string>, // <string> 
//    "previous_outpoints": <array>, // <PreviousOutPoint> 
//  }



// --------------------------
// Example with websockets:
// --------------------------
const WebSocket = require('ws');
const fs = require('fs');

const REST_HOST = 'localhost:8080'
const MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'

let ws = new WebSocket(`wss://${REST_HOST}/v1/transactions/subscribe?method=GET`, {
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  headers: {
    'Grpc-Metadata-Macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
});
let requestBody = {
  start_height: <int32>, // <int32> 
  end_height: <int32>, // <int32> 
  account: <string>, // <string> 
};
ws.on('open', function() {
    ws.send(JSON.stringify(requestBody));
});
ws.on('error', function(err) {
    console.log('Error: ' + err);
});
ws.on('message', function(body) {
    console.log(body);
});
// Console output:
//  {
//    "tx_hash": <string>, // <string>
//    "amount": <string>, // <int64>
//    "num_confirmations": <integer>, // <int32>
//    "block_hash": <string>, // <string>
//    "block_height": <integer>, // <int32>
//    "time_stamp": <string>, // <int64>
//    "total_fees": <string>, // <int64>
//    "dest_addresses": <array>, // <string>
//    "output_details": <array>, // <OutputDetail>
//    "raw_tx_hex": <string>, // <string>
//    "label": <string>, // <string>
//    "previous_outpoints": <array>, // <PreviousOutPoint>
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
MACAROON_PATH = 'LND_DIR/data/chain/bitcoin/regtest/admin.macaroon'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/transactions/subscribe'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, stream=True, verify=TLS_PATH)
for raw_response in r.iter_lines():
  json_response = json.loads(raw_response)
  print(json_response)
# {
#    "tx_hash": <string>,
#    "amount": <int64>,
#    "num_confirmations": <int32>,
#    "block_hash": <string>,
#    "block_height": <int32>,
#    "time_stamp": <int64>,
#    "total_fees": <int64>,
#    "dest_addresses": <string>,
#    "output_details": <OutputDetail>,
#    "raw_tx_hex": <string>,
#    "label": <string>,
#    "previous_outpoints": <PreviousOutPoint>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.GetTransactionsRequest

Source: lightning.proto

Field	gRPC Type	REST Type	REST Placement
start_height The height from which to list transactions, inclusive. If this value is greater than end_height, transactions will be read in reverse.	int32	integer	query
end_height The height until which to list transactions, inclusive. To include unconfirmed transactions, this value should be set to -1, which will return transactions from start_height until the current chain tip and unconfirmed transactions. If no end_height is provided, the call will default to this option.	int32	integer	query
account An optional filter to only include transactions relevant to an account.	string	string	query

lnrpc.Transaction

Source: lightning.proto

Field	gRPC Type	REST Type
tx_hash The transaction hash	string	string
amount The transaction amount, denominated in satoshis	int64	string
num_confirmations The number of confirmations	int32	integer
block_hash The hash of the block this transaction was included in	string	string
block_height The height of the block this transaction was included in	int32	integer
time_stamp Timestamp of this transaction	int64	string
total_fees Fees paid for this transaction	int64	string
dest_addresses Addresses that received funds for this transaction. Deprecated as it is now incorporated in the output_details field.	string[]	array
output_details Outputs that received funds for this transaction	OutputDetail[]	array
raw_tx_hex The raw transaction hex.	string	string
label A label that was optionally set on transaction broadcast.	string	string
previous_outpoints PreviousOutpoints/Inputs of this transaction.	PreviousOutPoint[]	array

Nested Messages

lnrpc.OutputDetail

Field	gRPC Type	REST Type
output_type The type of the output	OutputScriptType	string
address The address	string	string
pk_script The pkscript in hex	string	string
output_index The output index used in the raw transaction	int64	string
amount The value of the output coin in satoshis	int64	string
is_our_address Denotes if the output is controlled by the internal wallet	bool	boolean

lnrpc.PreviousOutPoint

Field	gRPC Type	REST Type
outpoint The outpoint in format txid:n.	string	string
is_our_output Denotes if the outpoint is controlled by the internal wallet. The flag will only detect p2wkh, np2wkh and p2tr inputs as its own.	bool	boolean

Enums

lnrpc.OutputScriptType

Name	Number
SCRIPT_TYPE_PUBKEY_HASH	0
SCRIPT_TYPE_SCRIPT_HASH	1
SCRIPT_TYPE_WITNESS_V0_PUBKEY_HASH	2
SCRIPT_TYPE_WITNESS_V0_SCRIPT_HASH	3
SCRIPT_TYPE_PUBKEY	4
SCRIPT_TYPE_MULTISIG	5
SCRIPT_TYPE_NULLDATA	6
SCRIPT_TYPE_NON_STANDARD	7
SCRIPT_TYPE_WITNESS_UNKNOWN	8
SCRIPT_TYPE_WITNESS_V1_TAPROOT	9