ListSwaps

ListSwaps returns a list of all currently known swaps and their current status.

Source: looprpc/client.proto

gRPC

rpc ListSwaps (ListSwapsRequest) returns (ListSwapsResponse);

REST

HTTP Method	Path
GET	/v1/loop/swaps

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 = {
  list_swap_filter: <ListSwapsFilter>,
};
client.listSwaps(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "swaps": <SwapStatus>,
//  }

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.ListSwapsRequest(
  list_swap_filter=<ListSwapsFilter>,
)
response = stub.ListSwaps(request)
print(response)
# {
#    "swaps": <SwapStatus>,
# }

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/loop/swaps`,
  // 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:
//  {
//    "swaps": <array>, // <SwapStatus> 
//  }

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/swaps'
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())
# {
#    "swaps": <SwapStatus>,
# }

Shell

$ loop listswaps --help

NAME:
   loop listswaps - list all swaps in the local database

USAGE:
   loop listswaps [command options] [arguments...]

DESCRIPTION:
   Allows the user to get a list of all swaps that are currently stored in the database

OPTIONS:
   --loop_out_only   only list swaps that are loop out swaps
   --loop_in_only    only list swaps that are loop in swaps
   --pending_only    only list pending swaps
   --label value     an optional label for this swap,limited to 500 characters. The label may not start with our reserved prefix: [reserved].
   --channel value   the comma-separated list of short channel IDs of the channels to loop out
   --last_hop value  the pubkey of the last hop to use for this swap
   

Messages

looprpc.ListSwapsRequest

Source: looprpc/client.proto

Field	gRPC Type	REST Type	REST Placement
list_swap_filter Optional filter to only return swaps that match the filter. Nested REST Parameters list_swap_filter.outgoing_chan_set: array in query list_swap_filter.label: string in query list_swap_filter.loop_in_last_hop: string in query list_swap_filter.swap_type: string in query list_swap_filter.pending_only: boolean in query	ListSwapsFilter	object	query

looprpc.ListSwapsResponse

Source: looprpc/client.proto

Field	gRPC Type	REST Type
swaps The list of all currently known swaps and their status.	SwapStatus[]	array

Nested Messages

looprpc.ListSwapsFilter

Field	gRPC Type	REST Type
swap_type The type of the swap.	SwapTypeFilter	string
pending_only If set, only pending swaps are returned.	bool	boolean
outgoing_chan_set If specified on creation, the outgoing channel set of the swap.	uint64[]	array
label Label of swap to filter for.	string	string
loop_in_last_hop If specified on creation, the last hop of the swap.	bytes	string

looprpc.SwapStatus

Field	gRPC Type	REST Type
amt Requested swap amount in sat. This does not include the swap and miner fee.	int64	string
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
type The type of the swap.	SwapType	string
state State the swap is currently in, see State enum.	SwapState	string
failure_reason A failure reason for the swap, only set if the swap has failed.	FailureReason	string
initiation_time Initiation time of the swap.	int64	string
last_update_time Initiation time of the swap.	int64	string
htlc_addressdeprecated DEPRECATED: This field stores the address of the onchain htlc. - 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 HTLC address (native segwit), used in loop-in and loop-out swaps.	string	string
htlc_address_p2tr The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.	string	string
cost_server Swap server cost	int64	string
cost_onchain On-chain transaction cost	int64	string
cost_offchain Off-chain routing fees	int64	string
last_hop Optional last hop if provided in the loop in request.	bytes	string
outgoing_chan_set Optional outgoing channel set if provided in the loop out request.	uint64[]	array
label An optional label given to the swap on creation.	string	string

Enums

looprpc.FailureReason

Name	Number
FAILURE_REASON_NONE FAILURE_REASON_NONE is set when the swap did not fail, it is either in progress or succeeded.	0
FAILURE_REASON_OFFCHAIN FAILURE_REASON_OFFCHAIN indicates that a loop out failed because it wasn't possible to find a route for one or both off chain payments that met the fee and timelock limits required.	1
FAILURE_REASON_TIMEOUT FAILURE_REASON_TIMEOUT indicates that the swap failed because on chain htlc did not confirm before its expiry, or it confirmed too late for us to reveal our preimage and claim.	2
FAILURE_REASON_SWEEP_TIMEOUT FAILURE_REASON_SWEEP_TIMEOUT indicates that a loop out permanently failed because the on chain htlc wasn't swept before the server revoked the htlc.	3
FAILURE_REASON_INSUFFICIENT_VALUE FAILURE_REASON_INSUFFICIENT_VALUE indicates that a loop out has failed because the on chain htlc had a lower value than requested.	4
FAILURE_REASON_TEMPORARY FAILURE_REASON_TEMPORARY indicates that a swap cannot continue due to an internal error. Manual intervention such as a restart is required.	5
FAILURE_REASON_INCORRECT_AMOUNT FAILURE_REASON_INCORRECT_AMOUNT indicates that a loop in permanently failed because the amount extended by an external loop in htlc is insufficient.	6
FAILURE_REASON_ABANDONED FAILURE_REASON_ABANDONED indicates that a swap permanently failed because the client manually abandoned the swap.	7
FAILURE_REASON_INSUFFICIENT_CONFIRMED_BALANCE FAILURE_REASON_INSUFFICIENT_CONFIRMED_BALANCE indicates that a swap wasn't published due to insufficient confirmed balance.	8
FAILURE_REASON_INCORRECT_HTLC_AMT_SWEPT FAILURE_REASON_INCORRECT_HTLC_AMT_SWEPT indicates that a swap wasn't published due to insufficient confirmed balance.	9

looprpc.ListSwapsFilter.SwapTypeFilter

Name	Number
ANY ANY indicates that no filter is applied.	0
LOOP_OUT LOOP_OUT indicates an loop out swap (off-chain to on-chain).	1
LOOP_IN LOOP_IN indicates a loop in swap (on-chain to off-chain).	2

looprpc.SwapState

Name	Number
INITIATED INITIATED is the initial state of a swap. At that point, the initiation call to the server has been made and the payment process has been started for the swap and prepayment invoices.	0
PREIMAGE_REVEALED PREIMAGE_REVEALED is reached when the sweep tx publication is first attempted. From that point on, we should consider the preimage to no longer be secret and we need to do all we can to get the sweep confirmed. This state will mostly coalesce with StateHtlcConfirmed, except in the case where we wait for fees to come down before we sweep.	1
HTLC_PUBLISHED HTLC_PUBLISHED is reached when the htlc tx has been published in a loop in swap.	2
SUCCESS SUCCESS is the final swap state that is reached when the sweep tx has the required confirmation depth.	3
FAILED FAILED is the final swap state for a failed swap with or without loss of the swap amount.	4
INVOICE_SETTLED INVOICE_SETTLED is reached when the swap invoice in a loop in swap has been paid, but we are still waiting for the htlc spend to confirm.	5

looprpc.SwapType

Name	Number
LOOP_OUT LOOP_OUT indicates an loop out swap (off-chain to on-chain)	0
LOOP_IN LOOP_IN indicates a loop in swap (on-chain to off-chain)	1