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:

• Acquiring inbound channel liquidity from arbitrary nodes on the Lightning network
• Depositing funds to a Bitcoin on-chain address without closing active channels
• Paying to on-chain fallback addresses in the case of insufficient route liquidity
• Refilling depleted channels with funds from cold-wallets or exchange withdrawals
• Servicing off-chain Lightning withdrawals using on-chain payments, with no funds in channels required
• As a failsafe payment method that can be used when channel liquidity along a route is insufficient

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. Currently, this communication is unauthenticated, so exposing this service to the internet is not recommended.

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

• looprpc/client.proto
• looprpc/debug.proto

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 490fb352ffe9a558785b3c35e2d09e0d454e5412.

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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> stub = debugstub.DebugStub(channel)
>>> request = looprpc.ForceAutoLoopRequest()
>>> response = stub.ForceAutoLoop(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}

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 debug = new looprpc.Debug('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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 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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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 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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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 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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.TokensRequest()
>>> response = stub.GetLsatTokens(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "tokens": <array LsatToken>,
}

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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.ListSwapsRequest()
>>> response = stub.ListSwaps(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "swaps": <array SwapStatus>,
}

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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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>,
    "server_message": <string>,
}

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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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>,
//      "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.
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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>,
    "server_message": <string>,
}

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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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>,
//      "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.
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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 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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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 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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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>,
    "cost_server": <int64>,
    "cost_onchain": <int64>,
    "cost_offchain": <int64>,
    "last_hop": <bytes>,
    "outgoing_chan_set": <array uint64>,
    "label": <string>,
}

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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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>,
//      "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.
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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 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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> stub = clientstub.SwapClientStub(channel)
>>> request = looprpc.SetLiquidityParamsRequest(
        parameters=<LiquidityParameters>,
    )
>>> response = stub.SetLiquidityParams(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}

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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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 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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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
>>> channel = grpc.insecure_channel('localhost:11010')
>>> 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>,
    "cost_server": <int64>,
    "cost_onchain": <int64>,
    "cost_offchain": <int64>,
    "last_hop": <bytes>,
    "outgoing_chan_set": <array uint64>,
    "label": <string>,
}

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 swapClient = new looprpc.SwapClient('localhost:11010', grpc.credentials.createInsecure());
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>,
//      "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.
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.ForceAutoLoopRequest

This message has no parameters.

looprpc.ForceAutoLoopResponse

This message has no parameters.

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

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:

• Acquiring inbound channel liquidity from arbitrary nodes on the Lightning network
• Depositing funds to a Bitcoin on-chain address without closing active channels
• Paying to on-chain fallback addresses in the case of insufficient route liquidity
• Refilling depleted channels with funds from cold-wallets or exchange withdrawals
• Servicing off-chain Lightning withdrawals using on-chain payments, with no funds in channels required
• As a failsafe payment method that can be used when channel liquidity along a route is insufficient

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. Currently, this communication is unauthenticated, so exposing this service to the internet is not recommended.

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

• looprpc/client.swagger.json

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 490fb352ffe9a558785b3c35e2d09e0d454e5412.

/v1/auto/suggest

$ curl -X GET http://localhost:8081/v1/auto/suggest
{ 
    "loop_out": <array looprpcLoopOutRequest>, 
    "loop_in": <array looprpcLoopInRequest>, 
    "disqualified": <array looprpcDisqualified>, 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/auto/suggest'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "loop_out": <array looprpcLoopOutRequest>, 
    "loop_in": <array looprpcLoopInRequest>, 
    "disqualified": <array looprpcDisqualified>, 
}

const request = require('request');
let options = {
  url: 'http://localhost:8081/v1/auto/suggest',
  json: true
};
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

$ curl -X GET http://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 = 'http://localhost:8081/v1/liquidity/params'
>>> 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 request = require('request');
let options = {
  url: 'http://localhost:8081/v1/liquidity/params',
  json: true
};
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.

$ curl -X POST http://localhost:8081/v1/liquidity/params -d '{ \
    "parameters":<looprpcLiquidityParameters>, \
}'
{ 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/liquidity/params'
>>> data = { 
        'parameters': <looprpcLiquidityParameters>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
}

const request = require('request');
let requestBody = { 
  parameters: <looprpcLiquidityParameters>,
};
let options = {
  url: 'http://localhost:8081/v1/liquidity/params',
  json: true,
  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

$ curl -X POST http://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>, 
    "server_message": <string>, 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/loop/in'
>>> 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>, 
    "server_message": <string>, 
}

const request = require('request');
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: 'http://localhost:8081/v1/loop/in',
  json: true,
  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>, 
//      "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.
server_message	string	A human-readable message received from the loop server.

/v1/loop/in/probe

$ curl -X GET http://localhost:8081/v1/loop/in/probe/{amt}
{ 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/loop/in/probe/{amt}'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
}

const request = require('request');
let options = {
  url: 'http://localhost:8081/v1/loop/in/probe/{amt}',
  json: true
};
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

$ curl -X GET http://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 = 'http://localhost:8081/v1/loop/in/quote/{amt}'
>>> 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 request = require('request');
let options = {
  url: 'http://localhost:8081/v1/loop/in/quote/{amt}',
  json: true
};
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

$ curl -X GET http://localhost:8081/v1/loop/in/terms
{ 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/loop/in/terms'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "min_swap_amount": <string>, 
    "max_swap_amount": <string>, 
}

const request = require('request');
let options = {
  url: 'http://localhost:8081/v1/loop/in/terms',
  json: true
};
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

$ curl -X POST http://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>, 
    "server_message": <string>, 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/loop/out'
>>> 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>, 
    "server_message": <string>, 
}

const request = require('request');
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: 'http://localhost:8081/v1/loop/out',
  json: true,
  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>, 
//      "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.
server_message	string	A human-readable message received from the loop server.

/v1/loop/out/quote

$ curl -X GET http://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 = 'http://localhost:8081/v1/loop/out/quote/{amt}'
>>> 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 request = require('request');
let options = {
  url: 'http://localhost:8081/v1/loop/out/quote/{amt}',
  json: true
};
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

$ curl -X GET http://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 = 'http://localhost:8081/v1/loop/out/terms'
>>> 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 request = require('request');
let options = {
  url: 'http://localhost:8081/v1/loop/out/terms',
  json: true
};
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

$ curl -X GET http://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>, 
    "cost_server": <string>, 
    "cost_onchain": <string>, 
    "cost_offchain": <string>, 
    "last_hop": <byte>, 
    "outgoing_chan_set": <array string>, 
    "label": <string>, 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/loop/swap/{id}'
>>> 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>, 
    "cost_server": <string>, 
    "cost_onchain": <string>, 
    "cost_offchain": <string>, 
    "last_hop": <byte>, 
    "outgoing_chan_set": <array string>, 
    "label": <string>, 
}

const request = require('request');
let options = {
  url: 'http://localhost:8081/v1/loop/swap/{id}',
  json: true
};
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>, 
//      "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.
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

$ curl -X GET http://localhost:8081/v1/loop/swaps
{ 
    "swaps": <array looprpcSwapStatus>, 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/loop/swaps'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "swaps": <array looprpcSwapStatus>, 
}

const request = require('request');
let options = {
  url: 'http://localhost:8081/v1/loop/swaps',
  json: true
};
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

$ curl -X GET http://localhost:8081/v1/lsat/tokens
{ 
    "tokens": <array looprpcLsatToken>, 
}

>>> import base64, json, requests
>>> url = 'http://localhost:8081/v1/lsat/tokens'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "tokens": <array looprpcLsatToken>, 
}

const request = require('request');
let options = {
  url: 'http://localhost:8081/v1/lsat/tokens',
  json: true
};
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.
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.
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:

• LND API Reference
• Faraday API Reference
• Lightning Pool API Reference