SuggestSwaps

SuggestSwaps returns a list of recommended swaps based on the current state of your node's channels and it's liquidity manager parameters. Note that only loop out suggestions are currently supported. [EXPERIMENTAL]: endpoint is subject to change.

Source: looprpc/client.proto

gRPC

rpc SuggestSwaps (SuggestSwapsRequest) returns (SuggestSwapsResponse);

REST

HTTP Method	Path
GET	/v1/auto/suggest

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 = {};
client.suggestSwaps(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "loop_out": <LoopOutRequest>,
//    "loop_in": <LoopInRequest>,
//    "disqualified": <Disqualified>,
//  }

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.SuggestSwapsRequest()
response = stub.SuggestSwaps(request)
print(response)
# {
#    "loop_out": <LoopOutRequest>,
#    "loop_in": <LoopInRequest>,
#    "disqualified": <Disqualified>,
# }

REST

Javascript

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

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

let options = {
  url: `https://${REST_HOST}/v1/auto/suggest`,
  // 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:
//  {
//    "loop_out": <array>, // <LoopOutRequest> 
//    "loop_in": <array>, // <LoopInRequest> 
//    "disqualified": <array>, // <Disqualified> 
//  }

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/auto/suggest'
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())
# {
#    "loop_out": <LoopOutRequest>,
#    "loop_in": <LoopInRequest>,
#    "disqualified": <Disqualified>,
# }

Shell

$ loop suggestswaps --help

NAME:
   loop suggestswaps - show a list of suggested swaps

USAGE:
   loop suggestswaps [arguments...]

DESCRIPTION:
   Displays a list of suggested swaps that aim to obtain the liquidity balance as specified by the rules set in the liquidity manager.

Messages

looprpc.SuggestSwapsRequest

Source: looprpc/client.proto

note

This request has no parameters.

looprpc.SuggestSwapsResponse

Source: looprpc/client.proto

Field	gRPC Type	REST Type
loop_out The set of recommended loop outs.	LoopOutRequest[]	array
loop_in The set of recommended loop in swaps	LoopInRequest[]	array
disqualified Disqualified contains the set of channels that swaps are not recommended for.	Disqualified[]	array

Nested Messages

looprpc.AssetLoopOutRequest

Field	gRPC Type	REST Type
asset_id The asset id to use to pay for the swap invoice. If set an asset client is needed to set to be able to pay the invoice.	bytes	string
asset_edge_node The node identity public key of the peer to ask for a quote for sending out the assets and converting them to satoshis. This must be specified if an asset id is set.	bytes	string
max_limit_multiplier An optional maximum multiplier for the rfq rate. If not set, the default will be 1.1. This means if we request a loop out quote for 1 BTC, the off chain cost will be at most 1.1 BTC.	double	number
expiry An optional expiry unix timestamp for when the rfq quote should expire.	int64	string

looprpc.AssetRfqInfo

Field	gRPC Type	REST Type
prepay_rfq_id The Prepay RFQ ID to use to pay for the prepay invoice.	bytes	string
max_prepay_asset_amt The maximum asset amt we'll pay for the prepay payment. This includes the max limit multiplier that was set in the request.	uint64	string
prepay_asset_rate The asset to BTC conversion rate for the prepay invoice.	FixedPoint	object
swap_rfq_id The Swap RFQ ID to use to pay for the swap invoice.	bytes	string
max_swap_asset_amt The maximum asset amt we'll pay for the swap payment. This includes the max limit multiplier that was set in the request.	uint64	string
swap_asset_rate The asset to BTC conversion rate for the swap invoice.	FixedPoint	object
asset_name The name of the asset to swap.	string	string

looprpc.Disqualified

Field	gRPC Type	REST Type
channel_id The short channel ID of the channel that was excluded from our suggestions.	uint64	string
pubkey The public key of the peer that was excluded from our suggestions.	bytes	string
reason The reason that we excluded the channel from the our suggestions.	AutoReason	string

looprpc.FixedPoint

Field	gRPC Type	REST Type
coefficient The coefficient is the fractional value scaled-up as an integer. This integer is represented as a string as it may be too large to fit in a uint64.	string	string
scale The scale is the component that determines how many decimal places the coefficient should be divided by to obtain the fractional value.	uint32	integer

looprpc.LoopInRequest

Field	gRPC Type	REST Type
amt Requested swap amount in sat. This does not include the swap and miner fee.	int64	string
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.	int64	string
max_miner_fee Maximum in on-chain fees that we are willing to spend. If we want to publish the on-chain htlc and the fee estimate turns out higher than this value, we cancel the swap. max_miner_fee is typically taken from the response of the GetQuote call.	int64	string
last_hop The last hop to use for the loop in swap. If empty, the last hop is selected based on the lowest routing fee for the swap payment from the server.	bytes	string
external_htlc If external_htlc is true, we expect the htlc to be published by an external actor.	bool	boolean
htlc_conf_target The number of blocks that the on chain htlc should confirm within.	int32	integer
label An optional label for this swap. This field is limited to 500 characters and may not be one of the reserved values in loop/labels Reserved list.	string	string
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
route_hints Optional route hints to reach the destination through private channels.	RouteHint[]	array
private Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.	bool	boolean

looprpc.LoopOutRequest

Field	gRPC Type	REST Type
amt Requested swap amount in sat. This does not include the swap and miner fee.	int64	string
dest Base58 encoded destination address for the swap.	string	string
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
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
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
max_prepay_amt Maximum amount of the swap fee that may be charged as a prepayment.	int64	string
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
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
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
sweep_conf_target The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.	int32	integer
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
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
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
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
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
account_addr_type The address type of the account specified in the account field.	AddressType	string
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
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
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
asset_info The optional asset information to use for the swap. If set, the swap will be paid in the specified asset using the provided edge node. An Asset client must be connected to the loop client to use this feature.	AssetLoopOutRequest	object
asset_rfq_info The optional RFQ information to use for the swap. If set, the swap will use the provided RFQs to pay for the swap invoice.	AssetRfqInfo	object

Enums

looprpc.AddressType

Name	Number
ADDRESS_TYPE_UNKNOWN	0
TAPROOT_PUBKEY	1

looprpc.AutoReason

Name	Number
AUTO_REASON_UNKNOWN	0
AUTO_REASON_BUDGET_NOT_STARTED Budget not started indicates that we do not recommend any swaps because the start time for our budget has not arrived yet.	1
AUTO_REASON_SWEEP_FEES Sweep fees indicates that the estimated fees to sweep swaps are too high right now.	2
AUTO_REASON_BUDGET_ELAPSED Budget elapsed indicates that the autoloop budget for the period has been elapsed.	3
AUTO_REASON_IN_FLIGHT In flight indicates that the limit on in-flight automatically dispatched swaps has already been reached.	4
AUTO_REASON_SWAP_FEE Swap fee indicates that the server fee for a specific swap is too high.	5
AUTO_REASON_MINER_FEE Miner fee indicates that the miner fee for a specific swap is to high.	6
AUTO_REASON_PREPAY Prepay indicates that the prepay fee for a specific swap is too high.	7
AUTO_REASON_FAILURE_BACKOFF Failure backoff indicates that a swap has recently failed for this target, and the backoff period has not yet passed.	8
AUTO_REASON_LOOP_OUT Loop out indicates that a loop out swap is currently utilizing the channel, so it is not eligible.	9
AUTO_REASON_LOOP_IN Loop In indicates that a loop in swap is currently in flight for the peer, so it is not eligible.	10
AUTO_REASON_LIQUIDITY_OK Liquidity ok indicates that a target meets the liquidity balance expressed in its rule, so no swap is needed.	11
AUTO_REASON_BUDGET_INSUFFICIENT Budget insufficient indicates that we cannot perform a swap because we do not have enough pending budget available. This differs from budget elapsed, because we still have some budget available, but we have allocated it to other swaps.	12
AUTO_REASON_FEE_INSUFFICIENT Fee insufficient indicates that the fee estimate for a swap is higher than the portion of total swap amount that we allow fees to consume.	13