PendingSweeps

PendingSweeps returns lists of on-chain outputs that lnd is currently attempting to sweep within its central batching engine. Outputs with similar fee rates are batched together in order to sweep them within a single transaction.

NOTE: Some of the fields within PendingSweepsRequest are not guaranteed to remain supported. This is an advanced API that depends on the internals of the UtxoSweeper, so things may change.

Source: walletrpc/walletkit.proto

gRPC

rpc PendingSweeps (PendingSweepsRequest) returns (PendingSweepsResponse);

REST

HTTP Method	Path
GET	/v2/wallet/sweeps/pending

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', 'walletrpc/walletkit.proto'], loaderOptions);
const walletrpc = grpc.loadPackageDefinition(packageDefinition).walletrpc;
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 walletrpc.WalletKit(GRPC_HOST, creds);
let request = {};
client.pendingSweeps(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "pending_sweeps": <PendingSweep>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the walletrpc/walletkit.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import walletkit_pb2 as walletrpc, walletkit_pb2_grpc as walletkitstub

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 = walletkitstub.WalletKitStub(channel)
request = walletrpc.PendingSweepsRequest()
response = stub.PendingSweeps(request)
print(response)
# {
#    "pending_sweeps": <PendingSweep>,
# }

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}/v2/wallet/sweeps/pending`,
  // 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:
//  {
//    "pending_sweeps": <array>, // <PendingSweep> 
//  }

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}/v2/wallet/sweeps/pending'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
r = requests.get(url, headers=headers, verify=TLS_PATH)
print(r.json())
# {
#    "pending_sweeps": <PendingSweep>,
# }

Shell

$ lncli wallet pendingsweeps --help

NAME:
   lncli wallet pendingsweeps - List all outputs that are pending to be swept within lnd.

USAGE:
   lncli wallet pendingsweeps [arguments...]

DESCRIPTION:
   
  List all on-chain outputs that lnd is currently attempting to sweep
  within its central batching engine. Outputs with similar fee rates are
  batched together in order to sweep them within a single transaction.
  

Messages

walletrpc.PendingSweepsRequest

Source: walletrpc/walletkit.proto

note

This request has no parameters.

walletrpc.PendingSweepsResponse

Source: walletrpc/walletkit.proto

Field	gRPC Type	REST Type
pending_sweeps The set of outputs currently being swept by lnd's central batching engine.	PendingSweep[]	array

Nested Messages

lnrpc.OutPoint

Field	gRPC Type	REST Type
txid_bytes Raw bytes representing the transaction id.	bytes	string
txid_str Reversed, hex-encoded string representing the transaction id.	string	string
output_index The index of the output on the transaction.	uint32	integer

walletrpc.PendingSweep

Field	gRPC Type	REST Type
outpoint The outpoint of the output we're attempting to sweep.	OutPoint	object
witness_type The witness type of the output we're attempting to sweep.	WitnessType	string
amount_sat The value of the output we're attempting to sweep.	uint32	integer
sat_per_bytedeprecated Deprecated, use sat_per_vbyte. The fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee rate is only determined once a sweeping transaction for the output is created, so it's possible for this to be 0 before this.	uint32	integer
broadcast_attempts The number of broadcast attempts we've made to sweep the output.	uint32	integer
next_broadcast_heightdeprecated Deprecated. The next height of the chain at which we'll attempt to broadcast the sweep transaction of the output.	uint32	integer
forcedeprecated Deprecated, use immediate. Whether this input must be force-swept. This means that it is swept immediately.	bool	boolean
requested_conf_targetdeprecated Deprecated, use deadline. The requested confirmation target for this output, which is the deadline used by the sweeper.	uint32	integer
requested_sat_per_bytedeprecated Deprecated, use requested_sat_per_vbyte. The requested fee rate, expressed in sat/vbyte, for this output.	uint32	integer
sat_per_vbyte The current fee rate we'll use to sweep the output, expressed in sat/vbyte. The fee rate is only determined once a sweeping transaction for the output is created, so it's possible for this to be 0 before this.	uint64	string
requested_sat_per_vbyte The requested starting fee rate, expressed in sat/vbyte, for this output. When not requested, this field will be 0.	uint64	string
immediate Whether this input will be swept immediately.	bool	boolean
budget The budget for this sweep, expressed in satoshis. This is the maximum amount that can be spent as fees to sweep this output.	uint64	string
deadline_height The deadline height used for this output when perform fee bumping.	uint32	integer

Enums

walletrpc.WitnessType

Name	Number
UNKNOWN_WITNESS	0
COMMITMENT_TIME_LOCK A witness that allows us to spend the output of a commitment transaction after a relative lock-time lockout.	1
COMMITMENT_NO_DELAY A witness that allows us to spend a settled no-delay output immediately on a counterparty's commitment transaction.	2
COMMITMENT_REVOKE A witness that allows us to sweep the settled output of a malicious counterparty's who broadcasts a revoked commitment transaction.	3
HTLC_OFFERED_REVOKE A witness that allows us to sweep an HTLC which we offered to the remote party in the case that they broadcast a revoked commitment state.	4
HTLC_ACCEPTED_REVOKE A witness that allows us to sweep an HTLC output sent to us in the case that the remote party broadcasts a revoked commitment state.	5
HTLC_OFFERED_TIMEOUT_SECOND_LEVEL A witness that allows us to sweep an HTLC output that we extended to a party, but was never fulfilled. This HTLC output isn't directly on the commitment transaction, but is the result of a confirmed second-level HTLC transaction. As a result, we can only spend this after a CSV delay.	6
HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL A witness that allows us to sweep an HTLC output that was offered to us, and for which we have a payment preimage. This HTLC output isn't directly on our commitment transaction, but is the result of confirmed second-level HTLC transaction. As a result, we can only spend this after a CSV delay.	7
HTLC_OFFERED_REMOTE_TIMEOUT A witness that allows us to sweep an HTLC that we offered to the remote party which lies in the commitment transaction of the remote party. We can spend this output after the absolute CLTV timeout of the HTLC as passed.	8
HTLC_ACCEPTED_REMOTE_SUCCESS A witness that allows us to sweep an HTLC that was offered to us by the remote party. We use this witness in the case that the remote party goes to chain, and we know the pre-image to the HTLC. We can sweep this without any additional timeout.	9
HTLC_SECOND_LEVEL_REVOKE A witness that allows us to sweep an HTLC from the remote party's commitment transaction in the case that the broadcast a revoked commitment, but then also immediately attempt to go to the second level to claim the HTLC.	10
WITNESS_KEY_HASH A witness type that allows us to spend a regular p2wkh output that's sent to an output which is under complete control of the backing wallet.	11
NESTED_WITNESS_KEY_HASH A witness type that allows us to sweep an output that sends to a nested P2SH script that pays to a key solely under our control.	12
COMMITMENT_ANCHOR A witness type that allows us to spend our anchor on the commitment transaction.	13
COMMITMENT_NO_DELAY_TWEAKLESS A witness type that is similar to the COMMITMENT_NO_DELAY type, but it omits the tweak that randomizes the key we need to spend with a channel peer supplied set of randomness.	14
COMMITMENT_TO_REMOTE_CONFIRMED A witness type that allows us to spend our output on the counterparty's commitment transaction after a confirmation.	15
HTLC_OFFERED_TIMEOUT_SECOND_LEVEL_INPUT_CONFIRMED A witness type that allows us to sweep an HTLC output that we extended to a party, but was never fulfilled. This is the HTLC output directly on our commitment transaction, and the input to the second-level HTLC timeout transaction. It can only be spent after CLTV expiry, and commitment confirmation.	16
HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL_INPUT_CONFIRMED A witness type that allows us to sweep an HTLC output that was offered to us, and for which we have a payment preimage. This is the HTLC output directly on our commitment transaction, and the input to the second-level HTLC success transaction. It can only be spent after the commitment has confirmed.	17
LEASE_COMMITMENT_TIME_LOCK A witness type that allows us to spend our output on our local commitment transaction after a relative and absolute lock-time lockout as part of the script enforced lease commitment type.	18
LEASE_COMMITMENT_TO_REMOTE_CONFIRMED A witness type that allows us to spend our output on the counterparty's commitment transaction after a confirmation and absolute locktime as part of the script enforced lease commitment type.	19
LEASE_HTLC_OFFERED_TIMEOUT_SECOND_LEVEL A witness type that allows us to sweep an HTLC output that we extended to a party, but was never fulfilled. This HTLC output isn't directly on the commitment transaction, but is the result of a confirmed second-level HTLC transaction. As a result, we can only spend this after a CSV delay and CLTV locktime as part of the script enforced lease commitment type.	20
LEASE_HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL A witness type that allows us to sweep an HTLC output that was offered to us, and for which we have a payment preimage. This HTLC output isn't directly on our commitment transaction, but is the result of confirmed second-level HTLC transaction. As a result, we can only spend this after a CSV delay and CLTV locktime as part of the script enforced lease commitment type.	21
TAPROOT_PUB_KEY_SPEND A witness type that allows us to spend a regular p2tr output that's sent to an output which is under complete control of the backing wallet.	22
TAPROOT_LOCAL_COMMIT_SPEND A witness type that allows us to spend our settled local commitment after a CSV delay when we force close the channel.	23
TAPROOT_REMOTE_COMMIT_SPEND A witness type that allows us to spend our settled local commitment after a CSV delay when the remote party has force closed the channel.	24
TAPROOT_ANCHOR_SWEEP_SPEND A witness type that we'll use for spending our own anchor output.	25
TAPROOT_HTLC_OFFERED_TIMEOUT_SECOND_LEVEL A witness that allows us to timeout an HTLC we offered to the remote party on our commitment transaction. We use this when we need to go on chain to time out an HTLC.	26
TAPROOT_HTLC_ACCEPTED_SUCCESS_SECOND_LEVEL A witness type that allows us to sweep an HTLC we accepted on our commitment transaction after we go to the second level on chain.	27
TAPROOT_HTLC_SECOND_LEVEL_REVOKE A witness that allows us to sweep an HTLC on the revoked transaction of the remote party that goes to the second level.	28
TAPROOT_HTLC_ACCEPTED_REVOKE A witness that allows us to sweep an HTLC sent to us by the remote party in the event that they broadcast a revoked state.	29
TAPROOT_HTLC_OFFERED_REVOKE A witness that allows us to sweep an HTLC we offered to the remote party if they broadcast a revoked commitment.	30
TAPROOT_HTLC_OFFERED_REMOTE_TIMEOUT A witness that allows us to sweep an HTLC we offered to the remote party that lies on the commitment transaction for the remote party. We can spend this output after the absolute CLTV timeout of the HTLC as passed.	31
TAPROOT_HTLC_LOCAL_OFFERED_TIMEOUT A witness type that allows us to sign the second level HTLC timeout transaction when spending from an HTLC residing on our local commitment transaction. This is used by the sweeper to re-sign inputs if it needs to aggregate several second level HTLCs.	32
TAPROOT_HTLC_ACCEPTED_REMOTE_SUCCESS A witness that allows us to sweep an HTLC that was offered to us by the remote party for a taproot channels. We use this witness in the case that the remote party goes to chain, and we know the pre-image to the HTLC. We can sweep this without any additional timeout.	33
TAPROOT_HTLC_ACCEPTED_LOCAL_SUCCESS A witness type that allows us to sweep the HTLC offered to us on our local commitment transaction. We'll use this when we need to go on chain to sweep the HTLC. In this case, this is the second level HTLC success transaction.	34
TAPROOT_COMMITMENT_REVOKE A witness that allows us to sweep the settled output of a malicious counterparty's who broadcasts a revoked taproot commitment transaction.	35