LoopOut

LoopOut initiates an loop out swap with the given parameters. The call returns after the swap has been set up with the swap server. From that point onwards, progress can be tracked via the SwapStatus stream that is returned from Monitor().

Source: looprpc/client.proto

gRPC

rpc LoopOut (LoopOutRequest) returns (SwapResponse);

REST

HTTP Method	Path
POST	/v1/loop/out

Code Samples

gRPC

Javascript

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

const GRPC_HOST = 'localhost:11010'
const MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'
const TLS_PATH = 'LOOP_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('looprpc/client.proto', loaderOptions);
const looprpc = grpc.loadPackageDefinition(packageDefinition).looprpc;
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 looprpc.SwapClient(GRPC_HOST, creds);
let request = {
  amt: <int64>,
  dest: <string>,
  max_swap_routing_fee: <int64>,
  max_prepay_routing_fee: <int64>,
  max_swap_fee: <int64>,
  max_prepay_amt: <int64>,
  max_miner_fee: <int64>,
  loop_out_channel: <uint64>,
  outgoing_chan_set: <uint64>,
  sweep_conf_target: <int32>,
  htlc_confirmations: <int32>,
  swap_publication_deadline: <uint64>,
  label: <string>,
  initiator: <string>,
  account: <string>,
  account_addr_type: <AddressType>,
  is_external_addr: <bool>,
  reservation_ids: <bytes>,
  payment_timeout: <uint32>,
};
client.loopOut(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "id": <string>,
//    "id_bytes": <bytes>,
//    "htlc_address": <string>,
//    "htlc_address_p2wsh": <string>,
//    "htlc_address_p2tr": <string>,
//    "server_message": <string>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the looprpc/client.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import client_pb2 as looprpc, client_pb2_grpc as clientstub

GRPC_HOST = 'localhost:11010'
MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'
TLS_PATH = 'LOOP_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 = clientstub.SwapClientStub(channel)
request = looprpc.LoopOutRequest(
  amt=<int64>,
  dest=<string>,
  max_swap_routing_fee=<int64>,
  max_prepay_routing_fee=<int64>,
  max_swap_fee=<int64>,
  max_prepay_amt=<int64>,
  max_miner_fee=<int64>,
  loop_out_channel=<uint64>,
  outgoing_chan_set=<uint64>,
  sweep_conf_target=<int32>,
  htlc_confirmations=<int32>,
  swap_publication_deadline=<uint64>,
  label=<string>,
  initiator=<string>,
  account=<string>,
  account_addr_type=<AddressType>,
  is_external_addr=<bool>,
  reservation_ids=<bytes>,
  payment_timeout=<uint32>,
)
response = stub.LoopOut(request)
print(response)
# {
#    "id": <string>,
#    "id_bytes": <bytes>,
#    "htlc_address": <string>,
#    "htlc_address_p2wsh": <string>,
#    "htlc_address_p2tr": <string>,
#    "server_message": <string>,
# }

REST

Javascript

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

const REST_HOST = 'localhost:8081'
const MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'

let requestBody = {
  amt: <string>, // <int64> 
  dest: <string>, // <string> 
  max_swap_routing_fee: <string>, // <int64> 
  max_prepay_routing_fee: <string>, // <int64> 
  max_swap_fee: <string>, // <int64> 
  max_prepay_amt: <string>, // <int64> 
  max_miner_fee: <string>, // <int64> 
  loop_out_channel: <string>, // <uint64> 
  outgoing_chan_set: <array>, // <uint64> 
  sweep_conf_target: <integer>, // <int32> 
  htlc_confirmations: <integer>, // <int32> 
  swap_publication_deadline: <string>, // <uint64> 
  label: <string>, // <string> 
  initiator: <string>, // <string> 
  account: <string>, // <string> 
  account_addr_type: <string>, // <AddressType> 
  is_external_addr: <boolean>, // <bool> 
  reservation_ids: <array>, // <bytes> (base64 encoded)
  payment_timeout: <integer>, // <uint32> 
};
let options = {
  url: `https://${REST_HOST}/v1/loop/out`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "id": <string>, // <string> 
//    "id_bytes": <string>, // <bytes> 
//    "htlc_address": <string>, // <string> 
//    "htlc_address_p2wsh": <string>, // <string> 
//    "htlc_address_p2tr": <string>, // <string> 
//    "server_message": <string>, // <string> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8081'
MACAROON_PATH = 'LOOP_DIR/regtest/loop.macaroon'
TLS_PATH = 'LOOP_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/loop/out'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'amt': <int64>,
  'dest': <string>,
  'max_swap_routing_fee': <int64>,
  'max_prepay_routing_fee': <int64>,
  'max_swap_fee': <int64>,
  'max_prepay_amt': <int64>,
  'max_miner_fee': <int64>,
  'loop_out_channel': <uint64>,
  'outgoing_chan_set': <uint64>,
  'sweep_conf_target': <int32>,
  'htlc_confirmations': <int32>,
  'swap_publication_deadline': <uint64>,
  'label': <string>,
  'initiator': <string>,
  'account': <string>,
  'account_addr_type': <AddressType>,
  'is_external_addr': <bool>,
  'reservation_ids': base64.b64encode(<bytes>),
  'payment_timeout': <uint32>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "id": <string>,
#    "id_bytes": <bytes>,
#    "htlc_address": <string>,
#    "htlc_address_p2wsh": <string>,
#    "htlc_address_p2tr": <string>,
#    "server_message": <string>,
# }

Shell

$ loop out --help

NAME:
   loop out - perform an off-chain to on-chain swap (looping out)

USAGE:
   loop out [command options] amt [addr]

DESCRIPTION:
   
  Attempts to loop out the target amount into either the backing lnd's
  wallet, or a targeted address.

  The amount is to be specified in satoshis.

  Optionally a BASE58/bech32 encoded bitcoin destination address may be
  specified. If not specified, a new wallet address will be generated.

OPTIONS:
   --addr value                  the optional address that the looped out funds should be sent to, if let blank the funds will go to lnd's wallet
   --account value               the name of the account to generate a new address from. You can list the names of valid accounts in your backing lnd instance with "lncli wallet accounts list"
   --account_addr_type value     the address type of the extended public key specified in account. Currently only pay-to-taproot-pubkey(p2tr) is supported (default: "p2tr")
   --amt value                   the amount in satoshis to loop out. To check for the minimum and maximum amounts to loop out please consult "loop terms" (default: 0)
   --htlc_confs value            the number of confirmations (in blocks) that we require for the htlc extended by the server before we reveal the preimage (default: 1)
   --conf_target value           the number of blocks from the swap initiation height that the on-chain HTLC should be swept within (default: 9)
   --max_swap_routing_fee value  the max off-chain swap routing fee in satoshis, if not specified, a default max fee will be used (default: 0)
   --fast                        indicate you want to swap immediately, paying potentially a higher fee. If not set the swap server might choose to wait up to 30 minutes before publishing the swap HTLC on-chain, to save on its chain fees. Not setting this flag therefore might result in a lower swap fee
   --payment_timeout value       the timeout for each individual off-chain payment attempt. If not set, the default timeout of 1 hour will be used. As the payment might be retried, the actual total time may be longer (default: 0s)
   --force, -f                   Assumes yes during confirmation. Using this option will result in an immediate swap
   --label value                 an optional label for this swap,limited to 500 characters. The label may not start with our reserved prefix: [reserved].
   --verbose, -v                 show expanded details
   --channel value               the comma-separated list of short channel IDs of the channels to loop out
   

Messages

looprpc.LoopOutRequest

Source: looprpc/client.proto

Field	gRPC Type	REST Type	REST Placement
amt Requested swap amount in sat. This does not include the swap and miner fee.	int64	string	body
dest Base58 encoded destination address for the swap.	string	string	body
max_swap_routing_fee Maximum off-chain fee in sat that may be paid for swap payment to the server. This limit is applied during path finding. Typically this value is taken from the response of the GetQuote call.	int64	string	body
max_prepay_routing_fee Maximum off-chain fee in sat that may be paid for the prepay to the server. This limit is applied during path finding. Typically this value is taken from the response of the GetQuote call.	int64	string	body
max_swap_fee Maximum we are willing to pay the server for the swap. This value is not disclosed in the swap initiation call, but if the server asks for a higher fee, we abort the swap. Typically this value is taken from the response of the GetQuote call. It includes the prepay amount.	int64	string	body
max_prepay_amt Maximum amount of the swap fee that may be charged as a prepayment.	int64	string	body
max_miner_fee Maximum in on-chain fees that we are willing to spend. If we want to sweep the on-chain htlc and the fee estimate turns out higher than this value, we cancel the swap. If the fee estimate is lower, we publish the sweep tx. If the sweep tx is not confirmed, we are forced to ratchet up fees until it is swept. Possibly even exceeding max_miner_fee if we get close to the htlc timeout. Because the initial publication revealed the preimage, we have no other choice. The server may already have pulled the off-chain htlc. Only when the fee becomes higher than the swap amount, we can only wait for fees to come down and hope - if we are past the timeout - that the server is not publishing the revocation. max_miner_fee is typically taken from the response of the GetQuote call.	int64	string	body
loop_out_channeldeprecated Deprecated, use outgoing_chan_set. The channel to loop out, the channel to loop out is selected based on the lowest routing fee for the swap payment to the server.	uint64	string	body
outgoing_chan_set A restriction on the channel set that may be used to loop out. The actual channel(s) that will be used are selected based on the lowest routing fee for the swap payment to the server.	uint64[]	array	body
sweep_conf_target The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.	int32	integer	body
htlc_confirmations The number of confirmations that we require for the on chain htlc that will be published by the server before we reveal the preimage.	int32	integer	body
swap_publication_deadline The latest time (in unix seconds) we allow the server to wait before publishing the HTLC on chain. Setting this to a larger value will give the server the opportunity to batch multiple swaps together, and wait for low-fee periods before publishing the HTLC, potentially resulting in a lower total swap fee.	uint64	string	body
label An optional label for this swap. This field is limited to 500 characters and may not start with the prefix [reserved], which is used to tag labels produced by the daemon.	string	string	body
initiator An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of loop. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (loopd, LiT) and the method used for triggering the swap (loop CLI, autolooper, LiT UI, other 3rd party UI).	string	string	body
account An alternative destination address source for the swap. This field represents the name of the account in the backing lnd instance. Refer to lnd's wallet import functions for reference.	string	string	body
account_addr_type The address type of the account specified in the account field.	AddressType	string	body
is_external_addr A flag indicating whether the defined destination address does not belong to the wallet. This is used to flag whether this loop out swap could have its associated sweep batched.	bool	boolean	body
reservation_ids The reservations to use for the swap. If this field is set, loop will try to use the instant out flow using the given reservations. If the reservations are not sufficient, the swap will fail. The swap amount must be equal to the sum of the amounts of the reservations.	bytes[]	array	body
payment_timeout The timeout in seconds to use for off-chain payments. Note that the swap payment is attempted multiple times where each attempt will set this value as the timeout for the payment.	uint32	integer	body

looprpc.SwapResponse

Source: looprpc/client.proto

Field	gRPC Type	REST Type
iddeprecated Swap identifier to track status in the update stream that is returned from the Start() call. Currently this is the hash that locks the htlcs. DEPRECATED: To make the API more consistent, this field is deprecated in favor of id_bytes and will be removed in a future release.	string	string
id_bytes Swap identifier to track status in the update stream that is returned from the Start() call. Currently this is the hash that locks the htlcs.	bytes	string
htlc_addressdeprecated DEPRECATED. This field stores the address of the onchain htlc, but depending on the request, the semantics are different. - For internal loop-in htlc_address contains the address of the native segwit (P2WSH) htlc. / - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.	string	string
htlc_address_p2wsh The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.	string	string
htlc_address_p2tr The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.	string	string
server_message A human-readable message received from the loop server.	string	string

Enums

looprpc.AddressType

Name	Number
ADDRESS_TYPE_UNKNOWN	0
TAPROOT_PUBKEY	1