NAV
shell python javascript

Loop gRPC API Reference

Welcome to the gRPC API reference documentation for Lightning Loop.

Lightning Loop is a non-custodial service offered by Lightning Labs to bridge on-chain and off-chain Bitcoin using submarine swaps. This repository is home to the Loop client and depends on the Lightning Network daemon lnd. All of lnd’s supported chain backends are fully supported when using the Loop client: Neutrino, Bitcoin Core, and btcd.

The service can be used in various situations:

This site features the documentation for loop (CLI), and the API documentation for Python and JavaScript clients in order to communicate with a local loopd instance through gRPC.

The examples to the right assume that the there is a local loopd instance running and listening for gRPC connections on port 11010. LOOP_DIR will be used as a placeholder to denote the base directory of the loopd instance. By default, this is ~/.loop on Linux and ~/Library/Application Support/Loop on macOS.

At the time of writing this documentation, two things are needed in order to make a gRPC request to a loopd instance: a TLS/SSL connection and a macaroon used for RPC authentication. The examples to the right will show how these can be used in order to make a successful, secure, and authenticated gRPC request.

The original *.proto files from which the gRPC documentation was generated can be found here:

This is the reference for the gRPC API. Alternatively, there is also a REST API which is documented here.

This documentation was generated automatically against commit 9c301015001663d96adc4ba906bb7daaa21d0e4e.

Service Debug

Debug.ForceAutoLoop

Unary RPC

ForceAutoLoop is intended for testing purposes only and will not work on mainnet. This endpoint ticks our autoloop timer, triggering automated dispatch of a swap if one is suggested.



>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /looprpc/debug.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import debug_pb2 as looprpc, debug_pb2_grpc as debugstub
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = debugstub.DebugStub(channel)
>>> request = looprpc.ForceAutoLoopRequest()
>>> response = stub.ForceAutoLoop(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('looprpc/debug.proto', loaderOptions);
const looprpc = grpc.loadPackageDefinition(packageDefinition).looprpc;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const debug = new looprpc.Debug('localhost:11010', creds);
let request = {}
debug.forceAutoLoop(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: looprpc.ForceAutoLoopRequest

This request has no parameters.

gRPC Response: looprpc.ForceAutoLoopResponse

This response has no parameters.

Service SwapClient

SwapClient.GetLiquidityParams

Unary RPC

GetLiquidityParams gets the parameters that the daemon's liquidity manager is currently configured with. This may be nil if nothing is configured. [EXPERIMENTAL]: endpoint is subject to change.


# Displays the current set of parameters that are set for the liquidity manager.

$ loop getparams [arguments...]


>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.GetLiquidityParamsRequest()
>>> response = stub.GetLiquidityParams(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "rules": <array LiquidityRule>,
    "fee_ppm": <uint64>,
    "sweep_fee_rate_sat_per_vbyte": <uint64>,
    "max_swap_fee_ppm": <uint64>,
    "max_routing_fee_ppm": <uint64>,
    "max_prepay_routing_fee_ppm": <uint64>,
    "max_prepay_sat": <uint64>,
    "max_miner_fee_sat": <uint64>,
    "sweep_conf_target": <int32>,
    "failure_backoff_sec": <uint64>,
    "autoloop": <bool>,
    "autoloop_budget_sat": <uint64>,
    "autoloop_budget_start_sec": <uint64>,
    "auto_max_in_flight": <uint64>,
    "min_swap_amount": <uint64>,
    "max_swap_amount": <uint64>,
    "htlc_conf_target": <int32>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = {}
swapClient.getLiquidityParams(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "rules": <array LiquidityRule>,
//      "fee_ppm": <uint64>,
//      "sweep_fee_rate_sat_per_vbyte": <uint64>,
//      "max_swap_fee_ppm": <uint64>,
//      "max_routing_fee_ppm": <uint64>,
//      "max_prepay_routing_fee_ppm": <uint64>,
//      "max_prepay_sat": <uint64>,
//      "max_miner_fee_sat": <uint64>,
//      "sweep_conf_target": <int32>,
//      "failure_backoff_sec": <uint64>,
//      "autoloop": <bool>,
//      "autoloop_budget_sat": <uint64>,
//      "autoloop_budget_start_sec": <uint64>,
//      "auto_max_in_flight": <uint64>,
//      "min_swap_amount": <uint64>,
//      "max_swap_amount": <uint64>,
//      "htlc_conf_target": <int32>,
//  }

gRPC Request: looprpc.GetLiquidityParamsRequest

This request has no parameters.

gRPC Response: looprpc.LiquidityParameters

Parameter Type Description
rules array LiquidityRule A set of liquidity rules that describe the desired liquidity balance.
fee_ppm uint64 The parts per million of swap amount that is allowed to be allocated to swap fees. This value is applied across swap categories and may not be set in conjunction with sweep fee rate, swap fee ppm, routing fee ppm, prepay routing, max prepay and max miner fee.
sweep_fee_rate_sat_per_vbyte uint64 The limit we place on our estimated sweep cost for a swap in sat/vByte. If the estimated fee for our sweep transaction within the specified confirmation target is above this value, we will not suggest any swaps.
max_swap_fee_ppm uint64 The maximum fee paid to the server for facilitating the swap, expressed as parts per million of the swap volume.
max_routing_fee_ppm uint64 The maximum fee paid to route the swap invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_routing_fee_ppm uint64 The maximum fee paid to route the prepay invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_sat uint64 The maximum no-show penalty in satoshis paid for a swap.
max_miner_fee_sat uint64 The maximum miner fee we will pay to sweep the swap on chain. Note that we will not suggest a swap if the estimate is above the sweep limit set by these parameters, and we use the current fee estimate to sweep on chain so this value is only a cap placed on the amount we spend on fees in the case where the swap needs to be claimed on chain, but fees have suddenly spiked.
sweep_conf_target int32 The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
failure_backoff_sec uint64 The amount of time we require pass since a channel was part of a failed swap due to off chain payment failure until it will be considered for swap suggestions again, expressed in seconds.
autoloop bool Set to true to enable automatic dispatch of swaps. All swaps will be limited to the fee categories set by these parameters, and total expenditure will be limited to the autoloop budget.
autoloop_budget_sat uint64 The total budget for automatically dispatched swaps since the budget start time, expressed in satoshis.
autoloop_budget_start_sec uint64 The start time for autoloop budget, expressed as a unix timestamp in seconds. If this value is 0, the budget will be applied for all automatically dispatched swaps. Swaps that were completed before this date will not be included in budget calculations.
auto_max_in_flight uint64 The maximum number of automatically dispatched swaps that we allow to be in flight at any point in time.
min_swap_amount uint64 The minimum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
max_swap_amount uint64 The maximum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
htlc_conf_target int32 The confirmation target for loop in on-chain htlcs.

SwapClient.GetLoopInQuote

Unary RPC

GetQuote returns a quote for a swap with the provided parameters.


# get a quote for the cost of a swap

$ out  get a quote for the cost of a loop out swap

# --help, -h  show help

>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.QuoteRequest(
        amt=<int64>,
        conf_target=<int32>,
        external_htlc=<bool>,
        swap_publication_deadline=<uint64>,
        loop_in_last_hop=<bytes>,
        loop_in_route_hints=<array RouteHint>,
        private=<bool>,
    )
>>> response = stub.GetLoopInQuote(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "swap_fee_sat": <int64>,
    "htlc_publish_fee_sat": <int64>,
    "cltv_delta": <int32>,
    "conf_target": <int32>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = { 
  amt: <int64>, 
  conf_target: <int32>, 
  external_htlc: <bool>, 
  swap_publication_deadline: <uint64>, 
  loop_in_last_hop: <bytes>, 
  loop_in_route_hints: <array RouteHint>, 
  private: <bool>, 
};
swapClient.getLoopInQuote(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "swap_fee_sat": <int64>,
//      "htlc_publish_fee_sat": <int64>,
//      "cltv_delta": <int32>,
//      "conf_target": <int32>,
//  }

gRPC Request: looprpc.QuoteRequest

Parameter Type Description
amt int64 The amount to swap in satoshis.
conf_target int32 The confirmation target that should be used either for the sweep of the on-chain HTLC broadcast by the swap server in the case of a Loop Out, or for the confirmation of the on-chain HTLC broadcast by the swap client in the case of a Loop In.
external_htlc bool If external_htlc is true, we expect the htlc to be published by an external actor.
swap_publication_deadline uint64 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. This only has an effect on loop out quotes.
loop_in_last_hop bytes Optionally the client can specify the last hop pubkey when requesting a loop-in quote. This is useful to get better off-chain routing fee from the server.
loop_in_route_hints array RouteHint Optional route hints to reach the destination through private channels.
private bool Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

gRPC Response: looprpc.InQuoteResponse

Parameter Type Description
swap_fee_sat int64 The fee that the swap server is charging for the swap.
htlc_publish_fee_sat int64 An estimate of the on-chain fee that needs to be paid to publish the HTLC If a miner fee of 0 is returned, it means the external_htlc flag was set for a loop in and the fee estimation was skipped. If a miner fee of -1 is returned, it means lnd's wallet tried to estimate the fee but was unable to create a sample estimation transaction because not enough funds are available. An information message should be shown to the user in this case.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used to publish the on-chain HTLC.

SwapClient.GetLoopInTerms

Unary RPC

GetTerms returns the terms that the server enforces for swaps.


# Display the current swap terms imposed by the server.

$ loop terms [arguments...]


>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.TermsRequest()
>>> response = stub.GetLoopInTerms(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "min_swap_amount": <int64>,
    "max_swap_amount": <int64>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = {}
swapClient.getLoopInTerms(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "min_swap_amount": <int64>,
//      "max_swap_amount": <int64>,
//  }

gRPC Request: looprpc.TermsRequest

This request has no parameters.

gRPC Response: looprpc.InTermsResponse

Parameter Type Description
min_swap_amount int64 Minimum swap amount (sat)
max_swap_amount int64 Maximum swap amount (sat)

SwapClient.GetLsatTokens

Unary RPC

GetLsatTokens returns all LSAT tokens the daemon ever paid for.


# Shows a list of all LSAT tokens that loopd has paid for

$ loop listauth [arguments...]


>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.TokensRequest()
>>> response = stub.GetLsatTokens(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "tokens": <array LsatToken>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = {}
swapClient.getLsatTokens(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "tokens": <array LsatToken>,
//  }

gRPC Request: looprpc.TokensRequest

This request has no parameters.

gRPC Response: looprpc.TokensResponse

Parameter Type Description
tokens array LsatToken List of all tokens the daemon knows of, including old/expired tokens.

SwapClient.ListSwaps

Unary RPC

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


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

$ loop listswaps [arguments...]


>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.ListSwapsRequest()
>>> response = stub.ListSwaps(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "swaps": <array SwapStatus>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = {}
swapClient.listSwaps(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "swaps": <array SwapStatus>,
//  }

gRPC Request: looprpc.ListSwapsRequest

This request has no parameters.

gRPC Response: looprpc.ListSwapsResponse

Parameter Type Description
swaps array SwapStatus The list of all currently known swaps and their status.

SwapClient.LoopIn

Unary RPC

LoopIn initiates a loop in 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().


# Send the amount in satoshis specified by the amt argument
# off-chain.
# By default the swap client will create and broadcast the
# on-chain htlc. The fee priority of this transaction can
# optionally be set using the conf_target flag.
# The external flag can be set to publish the on chain htlc
# independently. Note that this flag cannot be set with the
# conf_target flag.

$ loop in [command options] amt

# --amt value          the amount in satoshis to loop in (default: 0)
# --external           expect htlc to be published externally
# --conf_target value  the target number of blocks the on-chain htlc broadcast by the swap client should confirm within (default: 0)
# --last_hop value     the pubkey of the last hop to use for this swap
# --label value        an optional label for this swap,limited to 500 characters. The label may not start with our reserved prefix: [reserved].
# --force, -f          Assumes yes during confirmation. Using this option will result in an immediate swap
# --verbose, -v        show expanded details
# --route_hints value  Route hints that can each be individually used to assist in reaching the invoice's destination.
# --private            Generates and passes routehints. Should be used if the connected node is only reachable via private channels

>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.LoopInRequest(
        amt=<int64>,
        max_swap_fee=<int64>,
        max_miner_fee=<int64>,
        last_hop=<bytes>,
        external_htlc=<bool>,
        htlc_conf_target=<int32>,
        label=<string>,
        initiator=<string>,
        route_hints=<array RouteHint>,
        private=<bool>,
    )
>>> response = stub.LoopIn(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "id": <string>,
    "id_bytes": <bytes>,
    "htlc_address": <string>,
    "htlc_address_np2wsh": <string>,
    "htlc_address_p2wsh": <string>,
    "htlc_address_p2tr": <string>,
    "server_message": <string>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = { 
  amt: <int64>, 
  max_swap_fee: <int64>, 
  max_miner_fee: <int64>, 
  last_hop: <bytes>, 
  external_htlc: <bool>, 
  htlc_conf_target: <int32>, 
  label: <string>, 
  initiator: <string>, 
  route_hints: <array RouteHint>, 
  private: <bool>, 
};
swapClient.loopIn(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "id": <string>,
//      "id_bytes": <bytes>,
//      "htlc_address": <string>,
//      "htlc_address_np2wsh": <string>,
//      "htlc_address_p2wsh": <string>,
//      "htlc_address_p2tr": <string>,
//      "server_message": <string>,
//  }

gRPC Request: looprpc.LoopInRequest

Parameter Type Description
amt int64 Requested swap amount in sat. This does not include the swap and miner fee.
max_swap_fee int64 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.
max_miner_fee int64 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.
last_hop bytes 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.
external_htlc bool If external_htlc is true, we expect the htlc to be published by an external actor.
htlc_conf_target int32 The number of blocks that the on chain htlc should confirm within.
label string 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.
initiator string 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).
route_hints array RouteHint Optional route hints to reach the destination through private channels.
private bool Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

gRPC Response: looprpc.SwapResponse

Parameter Type Description
id string 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.
id_bytes 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.
htlc_address string 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 external loop-in htlc_address contains the address of the nested segwit (NP2WSH) htlc. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_np2wsh string The nested segwit address of the on-chain htlc. This field remains empty for loop-out.
htlc_address_p2wsh string The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
server_message string A human-readable message received from the loop server.

SwapClient.LoopOut

Unary RPC

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().


# 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.

$ loop out [command options] amt [addr]

# --channel value               the comma-separated list of short channel IDs of the channels to loop out
# --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
# --amt value                   the amount in satoshis to loop out (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.
# --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

>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_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=<array uint64>,
        sweep_conf_target=<int32>,
        htlc_confirmations=<int32>,
        swap_publication_deadline=<uint64>,
        label=<string>,
        initiator=<string>,
    )
>>> response = stub.LoopOut(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "id": <string>,
    "id_bytes": <bytes>,
    "htlc_address": <string>,
    "htlc_address_np2wsh": <string>,
    "htlc_address_p2wsh": <string>,
    "htlc_address_p2tr": <string>,
    "server_message": <string>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', 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: <array uint64>, 
  sweep_conf_target: <int32>, 
  htlc_confirmations: <int32>, 
  swap_publication_deadline: <uint64>, 
  label: <string>, 
  initiator: <string>, 
};
swapClient.loopOut(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "id": <string>,
//      "id_bytes": <bytes>,
//      "htlc_address": <string>,
//      "htlc_address_np2wsh": <string>,
//      "htlc_address_p2wsh": <string>,
//      "htlc_address_p2tr": <string>,
//      "server_message": <string>,
//  }

gRPC Request: looprpc.LoopOutRequest

Parameter Type Description
amt int64 Requested swap amount in sat. This does not include the swap and miner fee.
dest string Base58 encoded destination address for the swap.
max_swap_routing_fee int64 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.
max_prepay_routing_fee int64 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.
max_swap_fee int64 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.
max_prepay_amt int64 Maximum amount of the swap fee that may be charged as a prepayment.
max_miner_fee int64 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.
loop_out_channel uint64 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.
outgoing_chan_set array uint64 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.
sweep_conf_target int32 The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
htlc_confirmations int32 The number of confirmations that we require for the on chain htlc that will be published by the server before we reveal the preimage.
swap_publication_deadline uint64 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.
label string 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.
initiator string 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).

gRPC Response: looprpc.SwapResponse

Parameter Type Description
id string 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.
id_bytes 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.
htlc_address string 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 external loop-in htlc_address contains the address of the nested segwit (NP2WSH) htlc. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_np2wsh string The nested segwit address of the on-chain htlc. This field remains empty for loop-out.
htlc_address_p2wsh string The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
server_message string A human-readable message received from the loop server.

SwapClient.LoopOutQuote

Unary RPC

LoopOutQuote returns a quote for a loop out swap with the provided parameters.


# get a quote for the cost of a swap

$ out  get a quote for the cost of a loop out swap

# --help, -h  show help

>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.QuoteRequest(
        amt=<int64>,
        conf_target=<int32>,
        external_htlc=<bool>,
        swap_publication_deadline=<uint64>,
        loop_in_last_hop=<bytes>,
        loop_in_route_hints=<array RouteHint>,
        private=<bool>,
    )
>>> response = stub.LoopOutQuote(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "swap_fee_sat": <int64>,
    "prepay_amt_sat": <int64>,
    "htlc_sweep_fee_sat": <int64>,
    "swap_payment_dest": <bytes>,
    "cltv_delta": <int32>,
    "conf_target": <int32>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = { 
  amt: <int64>, 
  conf_target: <int32>, 
  external_htlc: <bool>, 
  swap_publication_deadline: <uint64>, 
  loop_in_last_hop: <bytes>, 
  loop_in_route_hints: <array RouteHint>, 
  private: <bool>, 
};
swapClient.loopOutQuote(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "swap_fee_sat": <int64>,
//      "prepay_amt_sat": <int64>,
//      "htlc_sweep_fee_sat": <int64>,
//      "swap_payment_dest": <bytes>,
//      "cltv_delta": <int32>,
//      "conf_target": <int32>,
//  }

gRPC Request: looprpc.QuoteRequest

Parameter Type Description
amt int64 The amount to swap in satoshis.
conf_target int32 The confirmation target that should be used either for the sweep of the on-chain HTLC broadcast by the swap server in the case of a Loop Out, or for the confirmation of the on-chain HTLC broadcast by the swap client in the case of a Loop In.
external_htlc bool If external_htlc is true, we expect the htlc to be published by an external actor.
swap_publication_deadline uint64 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. This only has an effect on loop out quotes.
loop_in_last_hop bytes Optionally the client can specify the last hop pubkey when requesting a loop-in quote. This is useful to get better off-chain routing fee from the server.
loop_in_route_hints array RouteHint Optional route hints to reach the destination through private channels.
private bool Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

gRPC Response: looprpc.OutQuoteResponse

Parameter Type Description
swap_fee_sat int64 The fee that the swap server is charging for the swap.
prepay_amt_sat int64 The part of the swap fee that is requested as a prepayment.
htlc_sweep_fee_sat int64 An estimate of the on-chain fee that needs to be paid to sweep the HTLC for a loop out.
swap_payment_dest bytes The node pubkey where the swap payment needs to be paid to. This can be used to test connectivity before initiating the swap.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used for the sweep of the on-chain HTLC.

SwapClient.LoopOutTerms

Unary RPC

LoopOutTerms returns the terms that the server enforces for a loop out swap.


# Display the current swap terms imposed by the server.

$ loop terms [arguments...]


>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.TermsRequest()
>>> response = stub.LoopOutTerms(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "min_swap_amount": <int64>,
    "max_swap_amount": <int64>,
    "min_cltv_delta": <int32>,
    "max_cltv_delta": <int32>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = {}
swapClient.loopOutTerms(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "min_swap_amount": <int64>,
//      "max_swap_amount": <int64>,
//      "min_cltv_delta": <int32>,
//      "max_cltv_delta": <int32>,
//  }

gRPC Request: looprpc.TermsRequest

This request has no parameters.

gRPC Response: looprpc.OutTermsResponse

Parameter Type Description
min_swap_amount int64 Minimum swap amount (sat)
max_swap_amount int64 Maximum swap amount (sat)
min_cltv_delta int32 The minimally accepted cltv delta of the on-chain htlc.
max_cltv_delta int32 The maximally accepted cltv delta of the on-chain htlc.

SwapClient.Monitor

Server-streaming RPC

Monitor will return a stream of swap updates for currently active swaps.


# Allows the user to monitor progress of any active swaps

$ loop monitor [arguments...]


>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.MonitorRequest()
>>> for response in stub.Monitor(request, metadata=[('macaroon', macaroon)]):
        print(response)
{ 
    "amt": <int64>,
    "id": <string>,
    "id_bytes": <bytes>,
    "type": <SwapType>,
    "state": <SwapState>,
    "failure_reason": <FailureReason>,
    "initiation_time": <int64>,
    "last_update_time": <int64>,
    "htlc_address": <string>,
    "htlc_address_p2wsh": <string>,
    "htlc_address_np2wsh": <string>,
    "htlc_address_p2tr": <string>,
    "cost_server": <int64>,
    "cost_onchain": <int64>,
    "cost_offchain": <int64>,
    "last_hop": <bytes>,
    "outgoing_chan_set": <array uint64>,
    "label": <string>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = {}
let call = swapClient.monitor(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:
//  { 
//      "amt": <int64>,
//      "id": <string>,
//      "id_bytes": <bytes>,
//      "type": <SwapType>,
//      "state": <SwapState>,
//      "failure_reason": <FailureReason>,
//      "initiation_time": <int64>,
//      "last_update_time": <int64>,
//      "htlc_address": <string>,
//      "htlc_address_p2wsh": <string>,
//      "htlc_address_np2wsh": <string>,
//      "htlc_address_p2tr": <string>,
//      "cost_server": <int64>,
//      "cost_onchain": <int64>,
//      "cost_offchain": <int64>,
//      "last_hop": <bytes>,
//      "outgoing_chan_set": <array uint64>,
//      "label": <string>,
//  }

gRPC Request: looprpc.MonitorRequest

This request has no parameters.

gRPC Response: looprpc.SwapStatus (Streaming)

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

SwapClient.Probe

Unary RPC

Probe asks he sever to probe the route to us to have a better upfront estimate about routing fees when loopin-in.



>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.ProbeRequest(
        amt=<int64>,
        last_hop=<bytes>,
        route_hints=<array RouteHint>,
    )
>>> response = stub.Probe(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = { 
  amt: <int64>, 
  last_hop: <bytes>, 
  route_hints: <array RouteHint>, 
};
swapClient.probe(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: looprpc.ProbeRequest

Parameter Type Description
amt int64 The amount to probe.
last_hop bytes Optional last hop of the route to probe.
route_hints array RouteHint Optional route hints to reach the destination through private channels.

gRPC Response: looprpc.ProbeResponse

This response has no parameters.

SwapClient.SetLiquidityParams

Unary RPC

SetLiquidityParams sets a new set of parameters for the daemon's liquidity manager. Note that the full set of parameters must be provided, because this call fully overwrites our existing parameters. [EXPERIMENTAL]: endpoint is subject to change.


# Updates the parameters set for the liquidity manager. Note the parameters are persisted in db to save the trouble of setting them again upon loopd restart. To get the default values, use `getparams` before any `setparams`.

$ loop setparams [command options] [arguments...]

# --sweeplimit value      the limit placed on our estimated sweep fee in sat/vByte. (default: 0)
# --feepercent value      the maximum percentage of swap amount to be used across all fee categories (default: 0)
# --maxswapfee value      the maximum percentage of swap volume we are willing to pay in server fees. (default: 0)
# --maxroutingfee value   the maximum percentage of off-chain payment volume that are are willing to pay in routing fees. (default: 0)
# --maxprepayfee value    the maximum percentage of off-chain prepay volume that are are willing to pay in routing fees. (default: 0)
# --maxprepay value       the maximum no-show (prepay) in satoshis that swap suggestions should be limited to. (default: 0)
# --maxminer value        the maximum miner fee in satoshis that swap suggestions should be limited to. (default: 0)
# --sweepconf value       the number of blocks from htlc height that swap suggestion sweeps should target, used to estimate max miner fee. (default: 0)
# --failurebackoff value  the amount of time, in seconds, that should pass before a channel that previously had a failed swap will be included in suggestions. (default: 0)
# --autoloop              set to true to enable automated dispatch of swaps, limited to the budget set by autobudget
# --autobudget value      the maximum amount of fees in satoshis that automatically dispatched loop out swaps may spend (default: 0)
# --budgetstart value     the start time for the automated loop out budget, expressed as a unix timestamp in seconds (default: 0)
# --autoinflight value    the maximum number of automatically dispatched swaps that we allow to be in flight (default: 0)
# --minamt value          the minimum amount in satoshis that the autoloop client will dispatch per-swap (default: 0)
# --maxamt value          the maximum amount in satoshis that the autoloop client will dispatch per-swap (default: 0)
# --htlc_conf value       the confirmation target for loop in on-chain htlcs (default: 0)

>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.SetLiquidityParamsRequest(
        parameters=<LiquidityParameters>,
    )
>>> response = stub.SetLiquidityParams(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = { 
  parameters: <LiquidityParameters>, 
};
swapClient.setLiquidityParams(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: looprpc.SetLiquidityParamsRequest

Parameter Type Description
parameters LiquidityParameters Parameters is the desired new set of parameters for the liquidity management subsystem. Note that the current set of parameters will be completely overwritten by the parameters provided (if they are valid), so the full set of parameters should be provided for each call.

gRPC Response: looprpc.SetLiquidityParamsResponse

This response has no parameters.

SwapClient.SuggestSwaps

Unary RPC

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.


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

$ loop suggestswaps [arguments...]


>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.SuggestSwapsRequest()
>>> response = stub.SuggestSwaps(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "loop_out": <array LoopOutRequest>,
    "loop_in": <array LoopInRequest>,
    "disqualified": <array Disqualified>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = {}
swapClient.suggestSwaps(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "loop_out": <array LoopOutRequest>,
//      "loop_in": <array LoopInRequest>,
//      "disqualified": <array Disqualified>,
//  }

gRPC Request: looprpc.SuggestSwapsRequest

This request has no parameters.

gRPC Response: looprpc.SuggestSwapsResponse

Parameter Type Description
loop_out array LoopOutRequest The set of recommended loop outs.
loop_in array LoopInRequest The set of recommended loop in swaps
disqualified array Disqualified Disqualified contains the set of channels that swaps are not recommended for.

SwapClient.SwapInfo

Unary RPC

SwapInfo returns all known details about a single swap.


# Allows the user to get the status of a single swap currently stored in the database

$ loop swapinfo [command options] id

# --id value  the ID of the swap (default: 0)

>>> 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
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
>>> cert = open('LOOP_DIR/tls.cert', 'rb').read()
>>> ssl_creds = grpc.ssl_channel_credentials(cert)
>>> channel = grpc.secure_channel('localhost:11010', ssl_creds)
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.SwapInfoRequest(
        id=<bytes>,
    )
>>> response = stub.SwapInfo(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "amt": <int64>,
    "id": <string>,
    "id_bytes": <bytes>,
    "type": <SwapType>,
    "state": <SwapState>,
    "failure_reason": <FailureReason>,
    "initiation_time": <int64>,
    "last_update_time": <int64>,
    "htlc_address": <string>,
    "htlc_address_p2wsh": <string>,
    "htlc_address_np2wsh": <string>,
    "htlc_address_p2tr": <string>,
    "cost_server": <int64>,
    "cost_onchain": <int64>,
    "cost_offchain": <int64>,
    "last_hop": <bytes>,
    "outgoing_chan_set": <array uint64>,
    "label": <string>,
}

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
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;
const macaroon = fs.readFileSync("LOOP_DIR/regtest/loop.macaroon").toString('hex');
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const lndCert = fs.readFileSync('LOOP_DIR/tls.cert');
const sslCreds = grpc.credentials.createSsl(lndCert);
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);
const swapClient = new looprpc.SwapClient('localhost:11010', creds);
let request = { 
  id: <bytes>, 
};
swapClient.swapInfo(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "amt": <int64>,
//      "id": <string>,
//      "id_bytes": <bytes>,
//      "type": <SwapType>,
//      "state": <SwapState>,
//      "failure_reason": <FailureReason>,
//      "initiation_time": <int64>,
//      "last_update_time": <int64>,
//      "htlc_address": <string>,
//      "htlc_address_p2wsh": <string>,
//      "htlc_address_np2wsh": <string>,
//      "htlc_address_p2tr": <string>,
//      "cost_server": <int64>,
//      "cost_onchain": <int64>,
//      "cost_offchain": <int64>,
//      "last_hop": <bytes>,
//      "outgoing_chan_set": <array uint64>,
//      "label": <string>,
//  }

gRPC Request: looprpc.SwapInfoRequest

Parameter Type Description
id bytes The swap identifier which currently is the hash that locks the HTLCs. When using REST, this field must be encoded as URL safe base64.

gRPC Response: looprpc.SwapStatus

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

gRPC Messages

looprpc.Disqualified

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

looprpc.GetLiquidityParamsRequest

This message has no parameters.

looprpc.InQuoteResponse

Parameter Type Description
swap_fee_sat int64 The fee that the swap server is charging for the swap.
htlc_publish_fee_sat int64 An estimate of the on-chain fee that needs to be paid to publish the HTLC If a miner fee of 0 is returned, it means the external_htlc flag was set for a loop in and the fee estimation was skipped. If a miner fee of -1 is returned, it means lnd's wallet tried to estimate the fee but was unable to create a sample estimation transaction because not enough funds are available. An information message should be shown to the user in this case.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used to publish the on-chain HTLC.

looprpc.InTermsResponse

Parameter Type Description
min_swap_amount int64 Minimum swap amount (sat)
max_swap_amount int64 Maximum swap amount (sat)

looprpc.LiquidityParameters

Parameter Type Description
rules array LiquidityRule A set of liquidity rules that describe the desired liquidity balance.
fee_ppm uint64 The parts per million of swap amount that is allowed to be allocated to swap fees. This value is applied across swap categories and may not be set in conjunction with sweep fee rate, swap fee ppm, routing fee ppm, prepay routing, max prepay and max miner fee.
sweep_fee_rate_sat_per_vbyte uint64 The limit we place on our estimated sweep cost for a swap in sat/vByte. If the estimated fee for our sweep transaction within the specified confirmation target is above this value, we will not suggest any swaps.
max_swap_fee_ppm uint64 The maximum fee paid to the server for facilitating the swap, expressed as parts per million of the swap volume.
max_routing_fee_ppm uint64 The maximum fee paid to route the swap invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_routing_fee_ppm uint64 The maximum fee paid to route the prepay invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_sat uint64 The maximum no-show penalty in satoshis paid for a swap.
max_miner_fee_sat uint64 The maximum miner fee we will pay to sweep the swap on chain. Note that we will not suggest a swap if the estimate is above the sweep limit set by these parameters, and we use the current fee estimate to sweep on chain so this value is only a cap placed on the amount we spend on fees in the case where the swap needs to be claimed on chain, but fees have suddenly spiked.
sweep_conf_target int32 The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
failure_backoff_sec uint64 The amount of time we require pass since a channel was part of a failed swap due to off chain payment failure until it will be considered for swap suggestions again, expressed in seconds.
autoloop bool Set to true to enable automatic dispatch of swaps. All swaps will be limited to the fee categories set by these parameters, and total expenditure will be limited to the autoloop budget.
autoloop_budget_sat uint64 The total budget for automatically dispatched swaps since the budget start time, expressed in satoshis.
autoloop_budget_start_sec uint64 The start time for autoloop budget, expressed as a unix timestamp in seconds. If this value is 0, the budget will be applied for all automatically dispatched swaps. Swaps that were completed before this date will not be included in budget calculations.
auto_max_in_flight uint64 The maximum number of automatically dispatched swaps that we allow to be in flight at any point in time.
min_swap_amount uint64 The minimum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
max_swap_amount uint64 The maximum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
htlc_conf_target int32 The confirmation target for loop in on-chain htlcs.

looprpc.LiquidityRule

Parameter Type Description
channel_id uint64 The short channel ID of the channel that this rule should be applied to. This field may not be set when the pubkey field is set.
swap_type SwapType The type of swap that will be dispatched for this rule.
pubkey bytes The public key of the peer that this rule should be applied to. This field may not be set when the channel id field is set.
type LiquidityRuleType Type indicates the type of rule that this message rule represents. Setting this value will determine which fields are used in the message. The comments on each field in this message will be prefixed with the LiquidityRuleType they belong to.
incoming_threshold uint32 THRESHOLD: The percentage of total capacity that incoming capacity should not drop beneath.
outgoing_threshold uint32 THRESHOLD: The percentage of total capacity that outgoing capacity should not drop beneath.

looprpc.ListSwapsRequest

This message has no parameters.

looprpc.ListSwapsResponse

Parameter Type Description
swaps array SwapStatus The list of all currently known swaps and their status.

looprpc.LoopInRequest

Parameter Type Description
amt int64 Requested swap amount in sat. This does not include the swap and miner fee.
max_swap_fee int64 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.
max_miner_fee int64 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.
last_hop bytes 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.
external_htlc bool If external_htlc is true, we expect the htlc to be published by an external actor.
htlc_conf_target int32 The number of blocks that the on chain htlc should confirm within.
label string 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.
initiator string 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).
route_hints array RouteHint Optional route hints to reach the destination through private channels.
private bool Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

looprpc.LoopOutRequest

Parameter Type Description
amt int64 Requested swap amount in sat. This does not include the swap and miner fee.
dest string Base58 encoded destination address for the swap.
max_swap_routing_fee int64 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.
max_prepay_routing_fee int64 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.
max_swap_fee int64 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.
max_prepay_amt int64 Maximum amount of the swap fee that may be charged as a prepayment.
max_miner_fee int64 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.
loop_out_channel uint64 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.
outgoing_chan_set array uint64 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.
sweep_conf_target int32 The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
htlc_confirmations int32 The number of confirmations that we require for the on chain htlc that will be published by the server before we reveal the preimage.
swap_publication_deadline uint64 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.
label string 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.
initiator string 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).

looprpc.LsatToken

Parameter Type Description
base_macaroon bytes The base macaroon that was baked by the auth server.
payment_hash bytes The payment hash of the payment that was paid to obtain the token.
payment_preimage bytes The preimage of the payment hash, knowledge of this is proof that the payment has been paid. If the preimage is set to all zeros, this means the payment is still pending and the token is not yet fully valid.
amount_paid_msat int64 The amount of millisatoshis that was paid to get the token.
routing_fee_paid_msat int64 The amount of millisatoshis paid in routing fee to pay for the token.
time_created int64 The creation time of the token as UNIX timestamp in seconds.
expired bool Indicates whether the token is expired or still valid.
storage_name string Identifying attribute of this token in the store. Currently represents the file name of the token where it's stored on the file system.

looprpc.MonitorRequest

This message has no parameters.

looprpc.OutQuoteResponse

Parameter Type Description
swap_fee_sat int64 The fee that the swap server is charging for the swap.
prepay_amt_sat int64 The part of the swap fee that is requested as a prepayment.
htlc_sweep_fee_sat int64 An estimate of the on-chain fee that needs to be paid to sweep the HTLC for a loop out.
swap_payment_dest bytes The node pubkey where the swap payment needs to be paid to. This can be used to test connectivity before initiating the swap.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used for the sweep of the on-chain HTLC.

looprpc.OutTermsResponse

Parameter Type Description
min_swap_amount int64 Minimum swap amount (sat)
max_swap_amount int64 Maximum swap amount (sat)
min_cltv_delta int32 The minimally accepted cltv delta of the on-chain htlc.
max_cltv_delta int32 The maximally accepted cltv delta of the on-chain htlc.

looprpc.ProbeRequest

Parameter Type Description
amt int64 The amount to probe.
last_hop bytes Optional last hop of the route to probe.
route_hints array RouteHint Optional route hints to reach the destination through private channels.

looprpc.ProbeResponse

This message has no parameters.

looprpc.QuoteRequest

Parameter Type Description
amt int64 The amount to swap in satoshis.
conf_target int32 The confirmation target that should be used either for the sweep of the on-chain HTLC broadcast by the swap server in the case of a Loop Out, or for the confirmation of the on-chain HTLC broadcast by the swap client in the case of a Loop In.
external_htlc bool If external_htlc is true, we expect the htlc to be published by an external actor.
swap_publication_deadline uint64 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. This only has an effect on loop out quotes.
loop_in_last_hop bytes Optionally the client can specify the last hop pubkey when requesting a loop-in quote. This is useful to get better off-chain routing fee from the server.
loop_in_route_hints array RouteHint Optional route hints to reach the destination through private channels.
private bool Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

looprpc.SetLiquidityParamsRequest

Parameter Type Description
parameters LiquidityParameters Parameters is the desired new set of parameters for the liquidity management subsystem. Note that the current set of parameters will be completely overwritten by the parameters provided (if they are valid), so the full set of parameters should be provided for each call.

looprpc.SetLiquidityParamsResponse

This message has no parameters.

looprpc.SuggestSwapsRequest

This message has no parameters.

looprpc.SuggestSwapsResponse

Parameter Type Description
loop_out array LoopOutRequest The set of recommended loop outs.
loop_in array LoopInRequest The set of recommended loop in swaps
disqualified array Disqualified Disqualified contains the set of channels that swaps are not recommended for.

looprpc.SwapInfoRequest

Parameter Type Description
id bytes The swap identifier which currently is the hash that locks the HTLCs. When using REST, this field must be encoded as URL safe base64.

looprpc.SwapResponse

Parameter Type Description
id string 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.
id_bytes 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.
htlc_address string 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 external loop-in htlc_address contains the address of the nested segwit (NP2WSH) htlc. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_np2wsh string The nested segwit address of the on-chain htlc. This field remains empty for loop-out.
htlc_address_p2wsh string The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
server_message string A human-readable message received from the loop server.

looprpc.SwapStatus

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

looprpc.TermsRequest

This message has no parameters.

looprpc.TokensRequest

This message has no parameters.

looprpc.TokensResponse

Parameter Type Description
tokens array LsatToken List of all tokens the daemon knows of, including old/expired tokens.

looprpc.ForceAutoLoopRequest

This message has no parameters.

looprpc.ForceAutoLoopResponse

This message has no parameters.

gRPC Enums

AutoReason

Name Value Description
AUTO_REASON_UNKNOWN 0
AUTO_REASON_BUDGET_NOT_STARTED 1 Budget not started indicates that we do not recommend any swaps because the start time for our budget has not arrived yet.
AUTO_REASON_SWEEP_FEES 2 Sweep fees indicates that the estimated fees to sweep swaps are too high right now.
AUTO_REASON_BUDGET_ELAPSED 3 Budget elapsed indicates that the autoloop budget for the period has been elapsed.
AUTO_REASON_IN_FLIGHT 4 In flight indicates that the limit on in-flight automatically dispatched swaps has already been reached.
AUTO_REASON_SWAP_FEE 5 Swap fee indicates that the server fee for a specific swap is too high.
AUTO_REASON_MINER_FEE 6 Miner fee indicates that the miner fee for a specific swap is to high.
AUTO_REASON_PREPAY 7 Prepay indicates that the prepay fee for a specific swap is too high.
AUTO_REASON_FAILURE_BACKOFF 8 Failure backoff indicates that a swap has recently failed for this target, and the backoff period has not yet passed.
AUTO_REASON_LOOP_OUT 9 Loop out indicates that a loop out swap is currently utilizing the channel, so it is not eligible.
AUTO_REASON_LOOP_IN 10 Loop In indicates that a loop in swap is currently in flight for the peer, so it is not eligible.
AUTO_REASON_LIQUIDITY_OK 11 Liquidity ok indicates that a target meets the liquidity balance expressed in its rule, so no swap is needed.
AUTO_REASON_BUDGET_INSUFFICIENT 12 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.
AUTO_REASON_FEE_INSUFFICIENT 13 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.

FailureReason

Name Value Description
FAILURE_REASON_NONE 0 FAILURE_REASON_NONE is set when the swap did not fail, it is either in progress or succeeded.
FAILURE_REASON_OFFCHAIN 1 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.
FAILURE_REASON_TIMEOUT 2 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.
FAILURE_REASON_SWEEP_TIMEOUT 3 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.
FAILURE_REASON_INSUFFICIENT_VALUE 4 FAILURE_REASON_INSUFFICIENT_VALUE indicates that a loop out has failed because the on chain htlc had a lower value than requested.
FAILURE_REASON_TEMPORARY 5 FAILURE_REASON_TEMPORARY indicates that a swap cannot continue due to an internal error. Manual intervention such as a restart is required.
FAILURE_REASON_INCORRECT_AMOUNT 6 FAILURE_REASON_INCORRECT_AMOUNT indicates that a loop in permanently failed because the amount extended by an external loop in htlc is insufficient.

LiquidityRuleType

Name Value Description
UNKNOWN 0
THRESHOLD 1

SwapState

Name Value Description
INITIATED 0 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.
PREIMAGE_REVEALED 1 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.
HTLC_PUBLISHED 2 HTLC_PUBLISHED is reached when the htlc tx has been published in a loop in swap.
SUCCESS 3 SUCCESS is the final swap state that is reached when the sweep tx has the required confirmation depth.
FAILED 4 FAILED is the final swap state for a failed swap with or without loss of the swap amount.
INVOICE_SETTLED 5 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.

SwapType

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

Loop REST API Reference

Welcome to the REST API reference documentation for Lightning Loop.

Lightning Loop is a non-custodial service offered by Lightning Labs to bridge on-chain and off-chain Bitcoin using submarine swaps. This repository is home to the Loop client and depends on the Lightning Network daemon lnd. All of lnd’s supported chain backends are fully supported when using the Loop client: Neutrino, Bitcoin Core, and btcd.

The service can be used in various situations:

This site features the API documentation for shell script (CLI), Python and JavaScript clients in order to communicate with a local loopd instance through gRPC.

The examples to the right assume that the there is a local loopd instance running and listening for REST connections on port 8081. LOOP_DIR will be used as a placeholder to denote the base directory of the loopd instance. By default, this is ~/.loop on Linux and ~/Library/Application Support/Loop on macOS.

At the time of writing this documentation, two things are needed in order to make an HTTP request to an loopd instance: a TLS/SSL connection and a macaroon used for RPC authentication. The examples to the right will show how these can be used in order to make a successful, secure, and authenticated HTTP request.

The original *.swagger.js files from which the gRPC documentation was generated can be found here:

NOTE: The byte field type must be set as the base64 encoded string representation of a raw byte array. Also, any time this must be used in a URL path (ie. /v1/abc/xyz/{payment_hash}) the base64 string must be encoded using a URL and Filename Safe Alphabet. This means you must replace + with -, / with _, and keep the trailing = as is. Url encoding (ie. %2F) will not work.

This is the reference for the REST API. Alternatively, there is also a gRPC API which is documented here.

This documentation was generated automatically against commit 9c301015001663d96adc4ba906bb7daaa21d0e4e.

/v1/auto/suggest

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/auto/suggest
{ 
    "loop_out": <array looprpcLoopOutRequest>, 
    "loop_in": <array looprpcLoopInRequest>, 
    "disqualified": <array looprpcDisqualified>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/auto/suggest'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "loop_out": <array looprpcLoopOutRequest>, 
    "loop_in": <array looprpcLoopInRequest>, 
    "disqualified": <array looprpcDisqualified>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/auto/suggest',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "loop_out": <array looprpcLoopOutRequest>, 
//      "loop_in": <array looprpcLoopInRequest>, 
//      "disqualified": <array looprpcDisqualified>, 
//  }

GET /v1/auto/suggest

loop: 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.

This request has no parameters.

Response

Field Type Description
loop_out array looprpcLoopOutRequest The set of recommended loop outs.
loop_in array looprpcLoopInRequest The set of recommended loop in swaps
disqualified array looprpcDisqualified Disqualified contains the set of channels that swaps are not recommended for.

/v1/liquidity/params

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/liquidity/params
{ 
    "rules": <array looprpcLiquidityRule>, 
    "fee_ppm": <string>, 
    "sweep_fee_rate_sat_per_vbyte": <string>, 
    "max_swap_fee_ppm": <string>, 
    "max_routing_fee_ppm": <string>, 
    "max_prepay_routing_fee_ppm": <string>, 
    "max_prepay_sat": <string>, 
    "max_miner_fee_sat": <string>, 
    "sweep_conf_target": <int32>, 
    "failure_backoff_sec": <string>, 
    "autoloop": <boolean>, 
    "autoloop_budget_sat": <string>, 
    "autoloop_budget_start_sec": <string>, 
    "auto_max_in_flight": <string>, 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
    "htlc_conf_target": <int32>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/liquidity/params'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "rules": <array looprpcLiquidityRule>, 
    "fee_ppm": <string>, 
    "sweep_fee_rate_sat_per_vbyte": <string>, 
    "max_swap_fee_ppm": <string>, 
    "max_routing_fee_ppm": <string>, 
    "max_prepay_routing_fee_ppm": <string>, 
    "max_prepay_sat": <string>, 
    "max_miner_fee_sat": <string>, 
    "sweep_conf_target": <int32>, 
    "failure_backoff_sec": <string>, 
    "autoloop": <boolean>, 
    "autoloop_budget_sat": <string>, 
    "autoloop_budget_start_sec": <string>, 
    "auto_max_in_flight": <string>, 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
    "htlc_conf_target": <int32>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/liquidity/params',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "rules": <array looprpcLiquidityRule>, 
//      "fee_ppm": <string>, 
//      "sweep_fee_rate_sat_per_vbyte": <string>, 
//      "max_swap_fee_ppm": <string>, 
//      "max_routing_fee_ppm": <string>, 
//      "max_prepay_routing_fee_ppm": <string>, 
//      "max_prepay_sat": <string>, 
//      "max_miner_fee_sat": <string>, 
//      "sweep_conf_target": <int32>, 
//      "failure_backoff_sec": <string>, 
//      "autoloop": <boolean>, 
//      "autoloop_budget_sat": <string>, 
//      "autoloop_budget_start_sec": <string>, 
//      "auto_max_in_flight": <string>, 
//      "min_swap_amount": <string>, 
//      "max_swap_amount": <string>, 
//      "htlc_conf_target": <int32>, 
//  }

GET /v1/liquidity/params

loop: getparams GetLiquidityParams gets the parameters that the daemon's liquidity manager is currently configured with. This may be nil if nothing is configured. [EXPERIMENTAL]: endpoint is subject to change.

This request has no parameters.

Response

Field Type Description
rules array looprpcLiquidityRule A set of liquidity rules that describe the desired liquidity balance.
fee_ppm string The parts per million of swap amount that is allowed to be allocated to swap fees. This value is applied across swap categories and may not be set in conjunction with sweep fee rate, swap fee ppm, routing fee ppm, prepay routing, max prepay and max miner fee.
sweep_fee_rate_sat_per_vbyte string The limit we place on our estimated sweep cost for a swap in sat/vByte. If the estimated fee for our sweep transaction within the specified confirmation target is above this value, we will not suggest any swaps.
max_swap_fee_ppm string The maximum fee paid to the server for facilitating the swap, expressed as parts per million of the swap volume.
max_routing_fee_ppm string The maximum fee paid to route the swap invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_routing_fee_ppm string The maximum fee paid to route the prepay invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_sat string The maximum no-show penalty in satoshis paid for a swap.
max_miner_fee_sat string The maximum miner fee we will pay to sweep the swap on chain. Note that we will not suggest a swap if the estimate is above the sweep limit set by these parameters, and we use the current fee estimate to sweep on chain so this value is only a cap placed on the amount we spend on fees in the case where the swap needs to be claimed on chain, but fees have suddenly spiked.
sweep_conf_target int32 The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
failure_backoff_sec string The amount of time we require pass since a channel was part of a failed swap due to off chain payment failure until it will be considered for swap suggestions again, expressed in seconds.
autoloop boolean Set to true to enable automatic dispatch of swaps. All swaps will be limited to the fee categories set by these parameters, and total expenditure will be limited to the autoloop budget.
autoloop_budget_sat string The total budget for automatically dispatched swaps since the budget start time, expressed in satoshis.
autoloop_budget_start_sec string The start time for autoloop budget, expressed as a unix timestamp in seconds. If this value is 0, the budget will be applied for all automatically dispatched swaps. Swaps that were completed before this date will not be included in budget calculations.
auto_max_in_flight string The maximum number of automatically dispatched swaps that we allow to be in flight at any point in time.
min_swap_amount string The minimum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
max_swap_amount string The maximum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
htlc_conf_target int32 The confirmation target for loop in on-chain htlcs. 
$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X POST --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/liquidity/params -d '{ \
    "parameters":<looprpcLiquidityParameters>, \
}'
{ 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/liquidity/params'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = { 
        'parameters': <looprpcLiquidityParameters>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let requestBody = { 
  parameters: <looprpcLiquidityParameters>,
};
let options = {
  url: 'https://localhost:8081/v1/liquidity/params',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//  }

POST /v1/liquidity/params

loop: setparams SetLiquidityParams sets a new set of parameters for the daemon's liquidity manager. Note that the full set of parameters must be provided, because this call fully overwrites our existing parameters. [EXPERIMENTAL]: endpoint is subject to change.

Field Type Placement Description
parameters looprpcLiquidityParameters body Parameters is the desired new set of parameters for the liquidity management subsystem. Note that the current set of parameters will be completely overwritten by the parameters provided (if they are valid), so the full set of parameters should be provided for each call.

Response

This response has no parameters.

/v1/loop/in

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X POST --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/in -d '{ \
    "amt":<string>, \
    "max_swap_fee":<string>, \
    "max_miner_fee":<string>, \
    "last_hop":<byte>, \
    "external_htlc":<boolean>, \
    "htlc_conf_target":<int32>, \
    "label":<string>, \
    "initiator":<string>, \
    "route_hints":<array looprpcRouteHint>, \
    "private":<boolean>, \
}'
{ 
    "id": <string>, 
    "id_bytes": <byte>, 
    "htlc_address": <string>, 
    "htlc_address_np2wsh": <string>, 
    "htlc_address_p2wsh": <string>, 
    "htlc_address_p2tr": <string>, 
    "server_message": <string>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/in'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = { 
        'amt': <string>, 
        'max_swap_fee': <string>, 
        'max_miner_fee': <string>, 
        'last_hop': base64.b64encode(<byte>).decode(), 
        'external_htlc': <boolean>, 
        'htlc_conf_target': <int32>, 
        'label': <string>, 
        'initiator': <string>, 
        'route_hints': <array looprpcRouteHint>, 
        'private': <boolean>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "id": <string>, 
    "id_bytes": <byte>, 
    "htlc_address": <string>, 
    "htlc_address_np2wsh": <string>, 
    "htlc_address_p2wsh": <string>, 
    "htlc_address_p2tr": <string>, 
    "server_message": <string>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let requestBody = { 
  amt: <string>,
  max_swap_fee: <string>,
  max_miner_fee: <string>,
  last_hop: <byte>,
  external_htlc: <boolean>,
  htlc_conf_target: <int32>,
  label: <string>,
  initiator: <string>,
  route_hints: <array looprpcRouteHint>,
  private: <boolean>,
};
let options = {
  url: 'https://localhost:8081/v1/loop/in',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "id": <string>, 
//      "id_bytes": <byte>, 
//      "htlc_address": <string>, 
//      "htlc_address_np2wsh": <string>, 
//      "htlc_address_p2wsh": <string>, 
//      "htlc_address_p2tr": <string>, 
//      "server_message": <string>, 
//  }

POST /v1/loop/in

loop: in LoopIn initiates a loop in 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().

Field Type Placement Description
amt string body Requested swap amount in sat. This does not include the swap and miner fee.
max_swap_fee string body 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.
max_miner_fee string body 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.
last_hop byte body 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.
external_htlc boolean body If external_htlc is true, we expect the htlc to be published by an external actor.
htlc_conf_target int32 body The number of blocks that the on chain htlc should confirm within.
label string body 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.
initiator string body 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).
route_hints array looprpcRouteHint body Optional route hints to reach the destination through private channels.
private boolean body Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

Response

Field Type Description
id string 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.
id_bytes byte 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.
htlc_address string 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 external loop-in htlc_address contains the address of the nested segwit (NP2WSH) htlc. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_np2wsh string The nested segwit address of the on-chain htlc. This field remains empty for loop-out.
htlc_address_p2wsh string The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
server_message string A human-readable message received from the loop server.

/v1/loop/in/probe

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/in/probe/{amt}
{ 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/in/probe/{amt}'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/loop/in/probe/{amt}',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//  }

GET /v1/loop/in/probe/{amt}

Probe asks he sever to probe the route to us to have a better upfront estimate about routing fees when loopin-in.

Field Type Placement Description
amt string path The amount to probe.
last_hop string query Optional last hop of the route to probe.

Response

This response has no parameters.

/v1/loop/in/quote

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/in/quote/{amt}
{ 
    "swap_fee_sat": <string>, 
    "htlc_publish_fee_sat": <string>, 
    "cltv_delta": <int32>, 
    "conf_target": <int32>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/in/quote/{amt}'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "swap_fee_sat": <string>, 
    "htlc_publish_fee_sat": <string>, 
    "cltv_delta": <int32>, 
    "conf_target": <int32>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/loop/in/quote/{amt}',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "swap_fee_sat": <string>, 
//      "htlc_publish_fee_sat": <string>, 
//      "cltv_delta": <int32>, 
//      "conf_target": <int32>, 
//  }

GET /v1/loop/in/quote/{amt}

loop: quote GetQuote returns a quote for a swap with the provided parameters.

Field Type Placement Description
amt string path The amount to swap in satoshis.
conf_target int32 query The confirmation target that should be used either for the sweep of the on-chain HTLC broadcast by the swap server in the case of a Loop Out, or for the confirmation of the on-chain HTLC broadcast by the swap client in the case of a Loop In.
external_htlc boolean query If external_htlc is true, we expect the htlc to be published by an external actor.
swap_publication_deadline string query 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. This only has an effect on loop out quotes.
loop_in_last_hop string query Optionally the client can specify the last hop pubkey when requesting a loop-in quote. This is useful to get better off-chain routing fee from the server.
private boolean query Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

Response

Field Type Description
swap_fee_sat string The fee that the swap server is charging for the swap.
htlc_publish_fee_sat string An estimate of the on-chain fee that needs to be paid to publish the HTLC If a miner fee of 0 is returned, it means the external_htlc flag was set for a loop in and the fee estimation was skipped. If a miner fee of -1 is returned, it means lnd's wallet tried to estimate the fee but was unable to create a sample estimation transaction because not enough funds are available. An information message should be shown to the user in this case.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used to publish the on-chain HTLC.

/v1/loop/in/terms

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/in/terms
{ 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/in/terms'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/loop/in/terms',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "min_swap_amount": <string>, 
//      "max_swap_amount": <string>, 
//  }

GET /v1/loop/in/terms

loop: terms GetTerms returns the terms that the server enforces for swaps.

This request has no parameters.

Response

Field Type Description
min_swap_amount string Minimum swap amount (sat)
max_swap_amount string Maximum swap amount (sat)

/v1/loop/out

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X POST --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/out -d '{ \
    "amt":<string>, \
    "dest":<string>, \
    "max_swap_routing_fee":<string>, \
    "max_prepay_routing_fee":<string>, \
    "max_swap_fee":<string>, \
    "max_prepay_amt":<string>, \
    "max_miner_fee":<string>, \
    "loop_out_channel":<string>, \
    "outgoing_chan_set":<array string>, \
    "sweep_conf_target":<int32>, \
    "htlc_confirmations":<int32>, \
    "swap_publication_deadline":<string>, \
    "label":<string>, \
    "initiator":<string>, \
}'
{ 
    "id": <string>, 
    "id_bytes": <byte>, 
    "htlc_address": <string>, 
    "htlc_address_np2wsh": <string>, 
    "htlc_address_p2wsh": <string>, 
    "htlc_address_p2tr": <string>, 
    "server_message": <string>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/out'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> data = { 
        'amt': <string>, 
        'dest': <string>, 
        'max_swap_routing_fee': <string>, 
        'max_prepay_routing_fee': <string>, 
        'max_swap_fee': <string>, 
        'max_prepay_amt': <string>, 
        'max_miner_fee': <string>, 
        'loop_out_channel': <string>, 
        'outgoing_chan_set': <array string>, 
        'sweep_conf_target': <int32>, 
        'htlc_confirmations': <int32>, 
        'swap_publication_deadline': <string>, 
        'label': <string>, 
        'initiator': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "id": <string>, 
    "id_bytes": <byte>, 
    "htlc_address": <string>, 
    "htlc_address_np2wsh": <string>, 
    "htlc_address_p2wsh": <string>, 
    "htlc_address_p2tr": <string>, 
    "server_message": <string>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let requestBody = { 
  amt: <string>,
  dest: <string>,
  max_swap_routing_fee: <string>,
  max_prepay_routing_fee: <string>,
  max_swap_fee: <string>,
  max_prepay_amt: <string>,
  max_miner_fee: <string>,
  loop_out_channel: <string>,
  outgoing_chan_set: <array string>,
  sweep_conf_target: <int32>,
  htlc_confirmations: <int32>,
  swap_publication_deadline: <string>,
  label: <string>,
  initiator: <string>,
};
let options = {
  url: 'https://localhost:8081/v1/loop/out',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "id": <string>, 
//      "id_bytes": <byte>, 
//      "htlc_address": <string>, 
//      "htlc_address_np2wsh": <string>, 
//      "htlc_address_p2wsh": <string>, 
//      "htlc_address_p2tr": <string>, 
//      "server_message": <string>, 
//  }

POST /v1/loop/out

loop: out 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().

Field Type Placement Description
amt string body Requested swap amount in sat. This does not include the swap and miner fee.
dest string body Base58 encoded destination address for the swap.
max_swap_routing_fee string body 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.
max_prepay_routing_fee string body 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.
max_swap_fee string body 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.
max_prepay_amt string body Maximum amount of the swap fee that may be charged as a prepayment.
max_miner_fee string body 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.
loop_out_channel string body 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.
outgoing_chan_set array string body 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.
sweep_conf_target int32 body The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
htlc_confirmations int32 body The number of confirmations that we require for the on chain htlc that will be published by the server before we reveal the preimage.
swap_publication_deadline string body 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.
label string body 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.
initiator string body 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).

Response

Field Type Description
id string 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.
id_bytes byte 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.
htlc_address string 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 external loop-in htlc_address contains the address of the nested segwit (NP2WSH) htlc. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_np2wsh string The nested segwit address of the on-chain htlc. This field remains empty for loop-out.
htlc_address_p2wsh string The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
server_message string A human-readable message received from the loop server.

/v1/loop/out/quote

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/out/quote/{amt}
{ 
    "swap_fee_sat": <string>, 
    "prepay_amt_sat": <string>, 
    "htlc_sweep_fee_sat": <string>, 
    "swap_payment_dest": <byte>, 
    "cltv_delta": <int32>, 
    "conf_target": <int32>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/out/quote/{amt}'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "swap_fee_sat": <string>, 
    "prepay_amt_sat": <string>, 
    "htlc_sweep_fee_sat": <string>, 
    "swap_payment_dest": <byte>, 
    "cltv_delta": <int32>, 
    "conf_target": <int32>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/loop/out/quote/{amt}',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "swap_fee_sat": <string>, 
//      "prepay_amt_sat": <string>, 
//      "htlc_sweep_fee_sat": <string>, 
//      "swap_payment_dest": <byte>, 
//      "cltv_delta": <int32>, 
//      "conf_target": <int32>, 
//  }

GET /v1/loop/out/quote/{amt}

loop: quote LoopOutQuote returns a quote for a loop out swap with the provided parameters.

Field Type Placement Description
amt string path The amount to swap in satoshis.
conf_target int32 query The confirmation target that should be used either for the sweep of the on-chain HTLC broadcast by the swap server in the case of a Loop Out, or for the confirmation of the on-chain HTLC broadcast by the swap client in the case of a Loop In.
external_htlc boolean query If external_htlc is true, we expect the htlc to be published by an external actor.
swap_publication_deadline string query 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. This only has an effect on loop out quotes.
loop_in_last_hop string query Optionally the client can specify the last hop pubkey when requesting a loop-in quote. This is useful to get better off-chain routing fee from the server.
private boolean query Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

Response

Field Type Description
swap_fee_sat string The fee that the swap server is charging for the swap.
prepay_amt_sat string The part of the swap fee that is requested as a prepayment.
htlc_sweep_fee_sat string An estimate of the on-chain fee that needs to be paid to sweep the HTLC for a loop out.
swap_payment_dest byte The node pubkey where the swap payment needs to be paid to. This can be used to test connectivity before initiating the swap.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used for the sweep of the on-chain HTLC.

/v1/loop/out/terms

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/out/terms
{ 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
    "min_cltv_delta": <int32>, 
    "max_cltv_delta": <int32>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/out/terms'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
    "min_cltv_delta": <int32>, 
    "max_cltv_delta": <int32>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/loop/out/terms',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "min_swap_amount": <string>, 
//      "max_swap_amount": <string>, 
//      "min_cltv_delta": <int32>, 
//      "max_cltv_delta": <int32>, 
//  }

GET /v1/loop/out/terms

loop: terms LoopOutTerms returns the terms that the server enforces for a loop out swap.

This request has no parameters.

Response

Field Type Description
min_swap_amount string Minimum swap amount (sat)
max_swap_amount string Maximum swap amount (sat)
min_cltv_delta int32 The minimally accepted cltv delta of the on-chain htlc.
max_cltv_delta int32 The maximally accepted cltv delta of the on-chain htlc.

/v1/loop/swap

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/swap/{id}
{ 
    "amt": <string>, 
    "id": <string>, 
    "id_bytes": <byte>, 
    "type": <looprpcSwapType>, 
    "state": <looprpcSwapState>, 
    "failure_reason": <looprpcFailureReason>, 
    "initiation_time": <string>, 
    "last_update_time": <string>, 
    "htlc_address": <string>, 
    "htlc_address_p2wsh": <string>, 
    "htlc_address_np2wsh": <string>, 
    "htlc_address_p2tr": <string>, 
    "cost_server": <string>, 
    "cost_onchain": <string>, 
    "cost_offchain": <string>, 
    "last_hop": <byte>, 
    "outgoing_chan_set": <array string>, 
    "label": <string>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/swap/{id}'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "amt": <string>, 
    "id": <string>, 
    "id_bytes": <byte>, 
    "type": <looprpcSwapType>, 
    "state": <looprpcSwapState>, 
    "failure_reason": <looprpcFailureReason>, 
    "initiation_time": <string>, 
    "last_update_time": <string>, 
    "htlc_address": <string>, 
    "htlc_address_p2wsh": <string>, 
    "htlc_address_np2wsh": <string>, 
    "htlc_address_p2tr": <string>, 
    "cost_server": <string>, 
    "cost_onchain": <string>, 
    "cost_offchain": <string>, 
    "last_hop": <byte>, 
    "outgoing_chan_set": <array string>, 
    "label": <string>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/loop/swap/{id}',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "amt": <string>, 
//      "id": <string>, 
//      "id_bytes": <byte>, 
//      "type": <looprpcSwapType>, 
//      "state": <looprpcSwapState>, 
//      "failure_reason": <looprpcFailureReason>, 
//      "initiation_time": <string>, 
//      "last_update_time": <string>, 
//      "htlc_address": <string>, 
//      "htlc_address_p2wsh": <string>, 
//      "htlc_address_np2wsh": <string>, 
//      "htlc_address_p2tr": <string>, 
//      "cost_server": <string>, 
//      "cost_onchain": <string>, 
//      "cost_offchain": <string>, 
//      "last_hop": <byte>, 
//      "outgoing_chan_set": <array string>, 
//      "label": <string>, 
//  }

GET /v1/loop/swap/{id}

loop: swapinfo SwapInfo returns all known details about a single swap.

Field Type Placement Description
id string path The swap identifier which currently is the hash that locks the HTLCs. When using REST, this field must be encoded as URL safe base64.

Response

Field Type Description
amt string Requested swap amount in sat. This does not include the swap and miner fee.
id string 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.
id_bytes byte 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.
type looprpcSwapType The type of the swap.
state looprpcSwapState State the swap is currently in, see State enum.
failure_reason looprpcFailureReason A failure reason for the swap, only set if the swap has failed.
initiation_time string Initiation time of the swap.
last_update_time string Initiation time of the swap.
htlc_address string 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 external loop-in htlc_address contains the nested segwit (NP2WSH) address. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_p2wsh string HTLC address (native segwit), used in loop-in and loop-out swaps.
htlc_address_np2wsh string HTLC address (nested segwit), used in loop-in swaps only.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
cost_server string Swap server cost
cost_onchain string On-chain transaction cost
cost_offchain string Off-chain routing fees
last_hop byte Optional last hop if provided in the loop in request.
outgoing_chan_set array string Optional outgoing channel set if provided in the loop out request.
label string An optional label given to the swap on creation.

/v1/loop/swaps

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/loop/swaps
{ 
    "swaps": <array looprpcSwapStatus>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/loop/swaps'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "swaps": <array looprpcSwapStatus>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/loop/swaps',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "swaps": <array looprpcSwapStatus>, 
//  }

GET /v1/loop/swaps

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

This request has no parameters.

Response

Field Type Description
swaps array looprpcSwapStatus The list of all currently known swaps and their status.

/v1/lsat/tokens

$ MACAROON_HEADER="Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $LOOP_DIR/regtest/loop.macaroon)"
$ curl -X GET --cacert $LOOP_DIR/tls.cert --header "$MACAROON_HEADER" https:://localhost:8081/v1/lsat/tokens
{ 
    "tokens": <array looprpcLsatToken>, 
}

>>> import base64, json, requests
>>> url = 'https://localhost:8081/v1/lsat/tokens'
>>> cert_path = 'LOOP_DIR/tls.cert'
>>> macaroon = codecs.encode(open('LOOP_DIR/regtest/loop.macaroon', 'rb').read(), 'hex')
>>> headers = {'Grpc-Metadata-macaroon': macaroon}
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "tokens": <array looprpcLsatToken>, 
}

const fs = require('fs');
const request = require('request');
const macaroon = fs.readFileSync('LOOP_DIR/regtest/loop.macaroon').toString('hex');
let options = {
  url: 'https://localhost:8081/v1/lsat/tokens',
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': macaroon
  },
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "tokens": <array looprpcLsatToken>, 
//  }

GET /v1/lsat/tokens

loop: listauth GetLsatTokens returns all LSAT tokens the daemon ever paid for.

This request has no parameters.

Response

Field Type Description
tokens array looprpcLsatToken List of all tokens the daemon knows of, including old/expired tokens.

REST Messages

looprpcDisqualified

Field Type Description
channel_id string The short channel ID of the channel that was excluded from our suggestions.
pubkey byte The public key of the peer that was excluded from our suggestions.
reason looprpcAutoReason The reason that we excluded the channel from the our suggestions.

looprpcHopHint

Field Type Description
node_id string The public key of the node at the start of the channel.
chan_id string The unique identifier of the channel.
fee_base_msat int64 The base fee of the channel denominated in millisatoshis.
fee_proportional_millionths int64 The fee rate of the channel for sending one satoshi across it denominated in millionths of a satoshi.
cltv_expiry_delta int64 The time-lock delta of the channel.

looprpcInQuoteResponse

Field Type Description
swap_fee_sat string The fee that the swap server is charging for the swap.
htlc_publish_fee_sat string An estimate of the on-chain fee that needs to be paid to publish the HTLC If a miner fee of 0 is returned, it means the external_htlc flag was set for a loop in and the fee estimation was skipped. If a miner fee of -1 is returned, it means lnd's wallet tried to estimate the fee but was unable to create a sample estimation transaction because not enough funds are available. An information message should be shown to the user in this case.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used to publish the on-chain HTLC.

looprpcInTermsResponse

Field Type Description
min_swap_amount string Minimum swap amount (sat)
max_swap_amount string Maximum swap amount (sat)

looprpcLiquidityParameters

Field Type Description
rules array looprpcLiquidityRule A set of liquidity rules that describe the desired liquidity balance.
fee_ppm string The parts per million of swap amount that is allowed to be allocated to swap fees. This value is applied across swap categories and may not be set in conjunction with sweep fee rate, swap fee ppm, routing fee ppm, prepay routing, max prepay and max miner fee.
sweep_fee_rate_sat_per_vbyte string The limit we place on our estimated sweep cost for a swap in sat/vByte. If the estimated fee for our sweep transaction within the specified confirmation target is above this value, we will not suggest any swaps.
max_swap_fee_ppm string The maximum fee paid to the server for facilitating the swap, expressed as parts per million of the swap volume.
max_routing_fee_ppm string The maximum fee paid to route the swap invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_routing_fee_ppm string The maximum fee paid to route the prepay invoice off chain, expressed as parts per million of the volume being routed.
max_prepay_sat string The maximum no-show penalty in satoshis paid for a swap.
max_miner_fee_sat string The maximum miner fee we will pay to sweep the swap on chain. Note that we will not suggest a swap if the estimate is above the sweep limit set by these parameters, and we use the current fee estimate to sweep on chain so this value is only a cap placed on the amount we spend on fees in the case where the swap needs to be claimed on chain, but fees have suddenly spiked.
sweep_conf_target int32 The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
failure_backoff_sec string The amount of time we require pass since a channel was part of a failed swap due to off chain payment failure until it will be considered for swap suggestions again, expressed in seconds.
autoloop boolean Set to true to enable automatic dispatch of swaps. All swaps will be limited to the fee categories set by these parameters, and total expenditure will be limited to the autoloop budget.
autoloop_budget_sat string The total budget for automatically dispatched swaps since the budget start time, expressed in satoshis.
autoloop_budget_start_sec string The start time for autoloop budget, expressed as a unix timestamp in seconds. If this value is 0, the budget will be applied for all automatically dispatched swaps. Swaps that were completed before this date will not be included in budget calculations.
auto_max_in_flight string The maximum number of automatically dispatched swaps that we allow to be in flight at any point in time.
min_swap_amount string The minimum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
max_swap_amount string The maximum amount, expressed in satoshis, that the autoloop client will dispatch a swap for. This value is subject to the server-side limits specified by the LoopOutTerms endpoint.
htlc_conf_target int32 The confirmation target for loop in on-chain htlcs.

looprpcLiquidityRule

Field Type Description
channel_id string The short channel ID of the channel that this rule should be applied to. This field may not be set when the pubkey field is set.
swap_type looprpcSwapType The type of swap that will be dispatched for this rule.
pubkey byte The public key of the peer that this rule should be applied to. This field may not be set when the channel id field is set.
type looprpcLiquidityRuleType Type indicates the type of rule that this message rule represents. Setting this value will determine which fields are used in the message. The comments on each field in this message will be prefixed with the LiquidityRuleType they belong to.
incoming_threshold int64 THRESHOLD: The percentage of total capacity that incoming capacity should not drop beneath.
outgoing_threshold int64 THRESHOLD: The percentage of total capacity that outgoing capacity should not drop beneath.

looprpcListSwapsResponse

Field Type Description
swaps array looprpcSwapStatus The list of all currently known swaps and their status.

looprpcLoopInRequest

Field Type Description
amt string Requested swap amount in sat. This does not include the swap and miner fee.
max_swap_fee string 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.
max_miner_fee string 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.
last_hop byte 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.
external_htlc boolean If external_htlc is true, we expect the htlc to be published by an external actor.
htlc_conf_target int32 The number of blocks that the on chain htlc should confirm within.
label string 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.
initiator string 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).
route_hints array looprpcRouteHint Optional route hints to reach the destination through private channels.
private boolean Private indicates whether the destination node should be considered private. In which case, loop will generate hophints to assist with probing and payment.

looprpcLoopOutRequest

Field Type Description
amt string Requested swap amount in sat. This does not include the swap and miner fee.
dest string Base58 encoded destination address for the swap.
max_swap_routing_fee string 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.
max_prepay_routing_fee string 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.
max_swap_fee string 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.
max_prepay_amt string Maximum amount of the swap fee that may be charged as a prepayment.
max_miner_fee string 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.
loop_out_channel string 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.
outgoing_chan_set array string 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.
sweep_conf_target int32 The number of blocks from the on-chain HTLC's confirmation height that it should be swept within.
htlc_confirmations int32 The number of confirmations that we require for the on chain htlc that will be published by the server before we reveal the preimage.
swap_publication_deadline string 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.
label string 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.
initiator string 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).

looprpcLsatToken

Field Type Description
base_macaroon byte The base macaroon that was baked by the auth server.
payment_hash byte The payment hash of the payment that was paid to obtain the token.
payment_preimage byte The preimage of the payment hash, knowledge of this is proof that the payment has been paid. If the preimage is set to all zeros, this means the payment is still pending and the token is not yet fully valid.
amount_paid_msat string The amount of millisatoshis that was paid to get the token.
routing_fee_paid_msat string The amount of millisatoshis paid in routing fee to pay for the token.
time_created string The creation time of the token as UNIX timestamp in seconds.
expired boolean Indicates whether the token is expired or still valid.
storage_name string Identifying attribute of this token in the store. Currently represents the file name of the token where it's stored on the file system.

looprpcOutQuoteResponse

Field Type Description
swap_fee_sat string The fee that the swap server is charging for the swap.
prepay_amt_sat string The part of the swap fee that is requested as a prepayment.
htlc_sweep_fee_sat string An estimate of the on-chain fee that needs to be paid to sweep the HTLC for a loop out.
swap_payment_dest byte The node pubkey where the swap payment needs to be paid to. This can be used to test connectivity before initiating the swap.
cltv_delta int32 On-chain cltv expiry delta
conf_target int32 The confirmation target to be used for the sweep of the on-chain HTLC.

looprpcOutTermsResponse

Field Type Description
min_swap_amount string Minimum swap amount (sat)
max_swap_amount string Maximum swap amount (sat)
min_cltv_delta int32 The minimally accepted cltv delta of the on-chain htlc.
max_cltv_delta int32 The maximally accepted cltv delta of the on-chain htlc.

looprpcProbeResponse

This property has no parameters.

looprpcRouteHint

Field Type Description
hop_hints array looprpcHopHint A list of hop hints that when chained together can assist in reaching a specific destination.

looprpcSetLiquidityParamsRequest

Field Type Description
parameters looprpcLiquidityParameters Parameters is the desired new set of parameters for the liquidity management subsystem. Note that the current set of parameters will be completely overwritten by the parameters provided (if they are valid), so the full set of parameters should be provided for each call.

looprpcSetLiquidityParamsResponse

This property has no parameters.

looprpcSuggestSwapsResponse

Field Type Description
loop_out array looprpcLoopOutRequest The set of recommended loop outs.
loop_in array looprpcLoopInRequest The set of recommended loop in swaps
disqualified array looprpcDisqualified Disqualified contains the set of channels that swaps are not recommended for.

looprpcSwapResponse

Field Type Description
id string 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.
id_bytes byte 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.
htlc_address string 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 external loop-in htlc_address contains the address of the nested segwit (NP2WSH) htlc. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_np2wsh string The nested segwit address of the on-chain htlc. This field remains empty for loop-out.
htlc_address_p2wsh string The native segwit address of the on-chain htlc. Used for both loop-in and loop-out.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
server_message string A human-readable message received from the loop server.

looprpcSwapStatus

Field Type Description
amt string Requested swap amount in sat. This does not include the swap and miner fee.
id string 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.
id_bytes byte 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.
type looprpcSwapType The type of the swap.
state looprpcSwapState State the swap is currently in, see State enum.
failure_reason looprpcFailureReason A failure reason for the swap, only set if the swap has failed.
initiation_time string Initiation time of the swap.
last_update_time string Initiation time of the swap.
htlc_address string 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 external loop-in htlc_address contains the nested segwit (NP2WSH) address. - For loop-out htlc_address always contains the native segwit (P2WSH) htlc address.
htlc_address_p2wsh string HTLC address (native segwit), used in loop-in and loop-out swaps.
htlc_address_np2wsh string HTLC address (nested segwit), used in loop-in swaps only.
htlc_address_p2tr string The address of the v3 (taproot) htlc. Used for both loop-in and loop-out.
cost_server string Swap server cost
cost_onchain string On-chain transaction cost
cost_offchain string Off-chain routing fees
last_hop byte Optional last hop if provided in the loop in request.
outgoing_chan_set array string Optional outgoing channel set if provided in the loop out request.
label string An optional label given to the swap on creation.

looprpcTokensResponse

Field Type Description
tokens array looprpcLsatToken List of all tokens the daemon knows of, including old/expired tokens.

protobufAny

Field Type Description
type_url string
value byte

rpcStatus

Field Type Description
code int32
message string
details array protobufAny

REST Enums

looprpcAutoReason

Name Value Description
AUTO_REASON_UNKNOWN 0
AUTO_REASON_BUDGET_NOT_STARTED 1
AUTO_REASON_SWEEP_FEES 2
AUTO_REASON_BUDGET_ELAPSED 3
AUTO_REASON_IN_FLIGHT 4
AUTO_REASON_SWAP_FEE 5
AUTO_REASON_MINER_FEE 6
AUTO_REASON_PREPAY 7
AUTO_REASON_FAILURE_BACKOFF 8
AUTO_REASON_LOOP_OUT 9
AUTO_REASON_LOOP_IN 10
AUTO_REASON_LIQUIDITY_OK 11
AUTO_REASON_BUDGET_INSUFFICIENT 12
AUTO_REASON_FEE_INSUFFICIENT 13

looprpcFailureReason

Name Value Description
FAILURE_REASON_NONE 0
FAILURE_REASON_OFFCHAIN 1
FAILURE_REASON_TIMEOUT 2
FAILURE_REASON_SWEEP_TIMEOUT 3
FAILURE_REASON_INSUFFICIENT_VALUE 4
FAILURE_REASON_TEMPORARY 5
FAILURE_REASON_INCORRECT_AMOUNT 6

looprpcLiquidityRuleType

Name Value Description
UNKNOWN 0
THRESHOLD 1

looprpcSwapState

Name Value Description
INITIATED 0
PREIMAGE_REVEALED 1
HTLC_PUBLISHED 2
SUCCESS 3
FAILED 4
INVOICE_SETTLED 5

looprpcSwapType

Name Value Description
LOOP_OUT 0
LOOP_IN 1

Other API References

This is the gRPC and REST API reference for the loopd daemon. There are separate API reference documents for the following daemons:




shell python javascript