NAV Navbar
shell python javascript

Pool gRPC API Reference

Welcome to the gRPC API reference documentation for Lightning Pool.

Lightning Pool is a non-custodial batched uniform clearing-price auction for Lightning Channel Lease (LCL). A LCL packages up inbound (or outbound!) channel liquidity (ability to send/receive funds) as a fixed incoming asset (earning interest over time) with a maturity date expressed in blocks. The maturity date of each of the channels is enforced by Bitcoin contracts, ensuring that the funds of the maker (the party that sold the channel) can't be swept until the maturity height. All cleared orders (purchased channels) are cleared in a single batched on-chain transaction.

This repository is home to the Pool client and depends on the Lightning Network daemon lnd. All of lnd’s supported chain backends are fully supported when using the Pool client: Neutrino, Bitcoin Core, and btcd.

The service can be used in various situations:

This site features the documentation for pool (CLI), and the API documentation for Python and JavaScript clients in order to communicate with a local poold 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:

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

Service HashMail

HashMail.DelCipherBox

Unary RPC

DelCipherBox attempts to tear down an existing cipher box pipe. The same authentication mechanism used to initially create the stream MUST be specified.


>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
>>> request = poolrpc.CipherBoxAuth(
        desc=<CipherBoxDesc>,
        acct_auth=<PoolAccountAuth>,
        sidecar_auth=<SidecarAuth>,
    )
>>> response = stub.DelCipherBox(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const hashMail = new poolrpc.HashMail('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  desc: <CipherBoxDesc>, 
  acct_auth: <PoolAccountAuth>, 
  sidecar_auth: <SidecarAuth>, 
};
hashMail.delCipherBox(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: poolrpc.CipherBoxAuth

Parameter Type Description
desc CipherBoxDesc A description of the stream one is attempting to initialize.
acct_auth PoolAccountAuth
sidecar_auth SidecarAuth

gRPC Response: poolrpc.DelCipherBoxResp

This response has no parameters.

HashMail.NewCipherBox

Unary RPC

NewCipherBox creates a new cipher box pipe/stream given a valid authentication mechanism. If the authentication mechanism has been revoked, or needs to be changed, then a CipherChallenge message is returned. Otherwise the method will either be accepted or rejected.


>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
>>> request = poolrpc.CipherBoxAuth(
        desc=<CipherBoxDesc>,
        acct_auth=<PoolAccountAuth>,
        sidecar_auth=<SidecarAuth>,
    )
>>> response = stub.NewCipherBox(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "success": <CipherSuccess>,
    "challenge": <CipherChallenge>,
    "error": <CipherError>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const hashMail = new poolrpc.HashMail('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  desc: <CipherBoxDesc>, 
  acct_auth: <PoolAccountAuth>, 
  sidecar_auth: <SidecarAuth>, 
};
hashMail.newCipherBox(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "success": <CipherSuccess>,
//      "challenge": <CipherChallenge>,
//      "error": <CipherError>,
//  }

gRPC Request: poolrpc.CipherBoxAuth

Parameter Type Description
desc CipherBoxDesc A description of the stream one is attempting to initialize.
acct_auth PoolAccountAuth
sidecar_auth SidecarAuth

gRPC Response: poolrpc.CipherInitResp

Parameter Type Description
success CipherSuccess CipherSuccess is returned if the initialization of the cipher box was successful.
challenge CipherChallenge CipherChallenge is returned if the authentication mechanism was revoked or needs to be refreshed.
error CipherError CipherError is returned if the authentication mechanism failed to validate.

HashMail.RecvStream

Server-streaming RPC

RecvStream opens up the read side of the passed CipherBox pipe. This method will block until a full message has been read as this is a message based pipe/stream abstraction.


>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
>>> request = poolrpc.CipherBoxDesc(
        stream_id=<bytes>,
    )
>>> for response in stub.RecvStream(request, metadata=[('macaroon', macaroon)]):
        print(response)
{ 
    "desc": <CipherBoxDesc>,
    "msg": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const hashMail = new poolrpc.HashMail('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  stream_id: <bytes>, 
};
let call = hashMail.recvStream(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:
//  { 
//      "desc": <CipherBoxDesc>,
//      "msg": <bytes>,
//  }

gRPC Request: poolrpc.CipherBoxDesc

Parameter Type Description
stream_id bytes

gRPC Response: poolrpc.CipherBox (Streaming)

Parameter Type Description
desc CipherBoxDesc
msg bytes

HashMail.SendStream

Client-streaming RPC

SendStream opens up the write side of the passed CipherBox pipe. Writes will be non-blocking up to the buffer size of the pipe. Beyond that writes will block until completed.


>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /auctioneerrpc/hashmail.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import auctioneerrpc/hashmail_pb2 as poolrpc, auctioneerrpc/hashmail_pb2_grpc as auctioneerrpc/hashmailstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = auctioneerrpc/hashmailstub.HashMailStub(channel)
# Define a generator that returns an Iterable of poolrpc.CipherBox objects.
>>> def request_generator():
        # Initialization code here.
        while True:
            # Parameters here can be set as arguments to the generator.
            request = poolrpc.CipherBox(
                desc=<CipherBoxDesc>,
                msg=<bytes>,
            )
            yield request
            # Do things between iterations here.
>>> request_iterable = request_generator()
>>> response = stub.SendStream(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "stream_id": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('auctioneerrpc/hashmail.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const hashMail = new poolrpc.HashMail('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  desc: <CipherBoxDesc>, 
  msg: <bytes>, 
};
let call = hashMail.sendStream({});
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.
});
call.write(request);
// Console output:
//  { 
//      "stream_id": <bytes>,
//  }

gRPC Request: poolrpc.CipherBox (Streaming)

Parameter Type Description
desc CipherBoxDesc
msg bytes

gRPC Response: poolrpc.CipherBoxDesc

Parameter Type Description
stream_id bytes

Service Trader

Trader.AuctionFee

Unary RPC

AuctionFee returns the current auction order execution fee specified by the auction server.


# Returns the current auction execution fee. The fee is paid for
# each order matched and scales with the size of the order.

$ pool auction fee [arguments...]

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.AuctionFeeRequest()
>>> response = stub.AuctionFee(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "execution_fee": <ExecutionFee>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = {}
trader.auctionFee(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "execution_fee": <ExecutionFee>,
//  }

gRPC Request: poolrpc.AuctionFeeRequest

This request has no parameters.

gRPC Response: poolrpc.AuctionFeeResponse

Parameter Type Description
execution_fee ExecutionFee The execution fee charged per matched order.

Trader.BatchSnapshot

Unary RPC

BatchSnapshot returns the snapshot of a past batch identified by its ID. If no ID is provided, the snapshot of the last finalized batch is returned. Deprecated, use BatchSnapshots instead.


# Returns information about a prior batch or batches such as the
# clearing price and the set of orders included in the batch. The
# prev_batch_id field can be used to explore prior batches in the
# sequence, similar to a block chain.

$ pool auction snapshot [command options] batch_id

# --batch_id value     the target batch ID to obtain a snapshot for, if left blank, information about the latest batch is returned
# --num_batches value  the number of batches to show, starting at the batch_id and going back through the history of finalized batches (default: 1)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.BatchSnapshotRequest(
        batch_id=<bytes>,
    )
>>> response = stub.BatchSnapshot(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "version": <uint32>,
    "batch_id": <bytes>,
    "prev_batch_id": <bytes>,
    "clearing_price_rate": <uint32>,
    "matched_orders": <array MatchedOrderSnapshot>,
    "batch_tx_id": <string>,
    "batch_tx": <bytes>,
    "batch_tx_fee_rate_sat_per_kw": <uint64>,
    "creation_timestamp_ns": <uint64>,
    "matched_markets": <array MatchedMarketsEntry>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  batch_id: <bytes>, 
};
trader.batchSnapshot(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "version": <uint32>,
//      "batch_id": <bytes>,
//      "prev_batch_id": <bytes>,
//      "clearing_price_rate": <uint32>,
//      "matched_orders": <array MatchedOrderSnapshot>,
//      "batch_tx_id": <string>,
//      "batch_tx": <bytes>,
//      "batch_tx_fee_rate_sat_per_kw": <uint64>,
//      "creation_timestamp_ns": <uint64>,
//      "matched_markets": <array MatchedMarketsEntry>,
//  }

gRPC Request: poolrpc.BatchSnapshotRequest

Parameter Type Description
batch_id bytes The unique identifier of the batch encoded as a compressed pubkey.

gRPC Response: poolrpc.BatchSnapshotResponse

Parameter Type Description
version uint32 The version of the batch.
batch_id bytes The unique identifier of the batch.
prev_batch_id bytes The unique identifier of the prior batch.
clearing_price_rate uint32 Deprecated, use matched_markets.
matched_orders array MatchedOrderSnapshot Deprecated, use matched_markets.
batch_tx_id string The txid of the batch transaction.
batch_tx bytes The batch transaction including all witness data.
batch_tx_fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kiloweight, of the batch transaction.
creation_timestamp_ns uint64 The unix timestamp in nanoseconds the batch was made.
matched_markets array MatchedMarketsEntry Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.

Trader.BatchSnapshots

Unary RPC

BatchSnapshots returns a list of batch snapshots starting at the start batch ID and going back through the history of batches, returning at most the number of specified batches. A maximum of 100 snapshots can be queried in one call. If no start batch ID is provided, the most recent finalized batch is used as the starting point to go back from.


# Returns information about a prior batch or batches such as the
# clearing price and the set of orders included in the batch. The
# prev_batch_id field can be used to explore prior batches in the
# sequence, similar to a block chain.

$ pool auction snapshot [command options] batch_id

# --batch_id value     the target batch ID to obtain a snapshot for, if left blank, information about the latest batch is returned
# --num_batches value  the number of batches to show, starting at the batch_id and going back through the history of finalized batches (default: 1)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.BatchSnapshotsRequest(
        start_batch_id=<bytes>,
        num_batches_back=<uint32>,
    )
>>> response = stub.BatchSnapshots(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "batches": <array BatchSnapshotResponse>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  start_batch_id: <bytes>, 
  num_batches_back: <uint32>, 
};
trader.batchSnapshots(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "batches": <array BatchSnapshotResponse>,
//  }

gRPC Request: poolrpc.BatchSnapshotsRequest

Parameter Type Description
start_batch_id bytes The unique identifier of the first batch to return, encoded as a compressed pubkey. This represents the newest/most current batch to fetch. If this is empty or a zero batch ID, the most recent finalized batch is used as the starting point to go back from.
num_batches_back uint32 The number of batches to return at most, including the start batch.

gRPC Response: poolrpc.BatchSnapshotsResponse

Parameter Type Description
batches array BatchSnapshotResponse The list of batches requested.

Trader.BumpAccountFee

Unary RPC

BumpAccountFee attempts to bump the fee of an account's transaction through child-pays-for-parent (CPFP). Since the CPFP is performed through the backing lnd node, the account transaction must contain an output under its control for a successful bump. If a CPFP has already been performed for an account, and this RPC is invoked again, then a replacing transaction (RBF) of the child will be broadcast.


# This command allows users to bump the fee of an account's unconfirmed
# transaction through child-pays-for-parent (CPFP). Since the CPFP is
# performed through the backing lnd node, the account transaction must
# contain an output under its control for a successful bump. If a CPFP has
# already been performed for an account, and this RPC is invoked again,
# then a replacing transaction (RBF) of the child will be broadcast.

$ pool accounts bumpfee [command options] trader_key sat_per_vbyte

# --trader_key value     the trader key associated with the account to bump the fee of
# --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the CPFP (default: 0)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.BumpAccountFeeRequest(
        trader_key=<bytes>,
        fee_rate_sat_per_kw=<uint64>,
    )
>>> response = stub.BumpAccountFee(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  trader_key: <bytes>, 
  fee_rate_sat_per_kw: <uint64>, 
};
trader.bumpAccountFee(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: poolrpc.BumpAccountFeeRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that will have its fee bumped.
fee_rate_sat_per_kw uint64 The new fee rate, in satoshis per kw, to use for the child of the account transaction.

gRPC Response: poolrpc.BumpAccountFeeResponse

This response has no parameters.

Trader.CancelOrder

Unary RPC

CancelOrder cancels an active order with the auction server to remove it from future matching.


# Remove a pending offer from the order book.

$ pool orders cancel [command options] order_nonce

# --order_nonce value  the order nonce of the order to cancel
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.CancelOrderRequest(
        order_nonce=<bytes>,
    )
>>> response = stub.CancelOrder(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  order_nonce: <bytes>, 
};
trader.cancelOrder(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: poolrpc.CancelOrderRequest

Parameter Type Description
order_nonce bytes

gRPC Response: poolrpc.CancelOrderResponse

This response has no parameters.

Trader.CloseAccount

Unary RPC

CloseAccount closes an account and returns the funds locked in that account to the connected lnd node's wallet.


# Close an existing account. An optional address can be provided which the
# funds of the account to close will be sent to, otherwise they are sent
# to an address under control of the connected lnd node.

$ pool accounts close [command options] trader_key sat_per_vbyte

# --trader_key value     the trader key associated with the account to close
# --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the closing transaction (default: 0)
# --addr value           an optional address which the funds of the account to close will be sent to
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.CloseAccountRequest(
        trader_key=<bytes>,
        output_with_fee=<OutputWithFee>,
        outputs=<OutputsWithImplicitFee>,
    )
>>> response = stub.CloseAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "close_txid": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  trader_key: <bytes>, 
  output_with_fee: <OutputWithFee>, 
  outputs: <OutputsWithImplicitFee>, 
};
trader.closeAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "close_txid": <bytes>,
//  }

gRPC Request: poolrpc.CloseAccountRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that will be closed.
output_with_fee OutputWithFee A single output/address to which the remaining funds of the account will be sent to at the specified fee. If an address is not specified, then the funds are sent to an address the backing lnd node controls.
outputs OutputsWithImplicitFee The outputs to which the remaining funds of the account will be sent to. This should only be used when wanting to create two or more outputs, otherwise OutputWithFee should be used instead. The fee of the account's closing transaction is implicitly defined by the combined value of all outputs.

gRPC Response: poolrpc.CloseAccountResponse

Parameter Type Description
close_txid bytes The hash of the closing transaction.

Trader.DepositAccount

Unary RPC

DepositAccount adds more funds from the connected lnd node's wallet to an account.


# Deposit funds into an existing account.

$ pool accounts deposit [command options] trader_key amt sat_per_vbyte

# --trader_key value     the hex-encoded trader key of the account to deposit funds into
# --amt value            the amount to deposit into the account (default: 0)
# --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the deposit (default: 0)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.DepositAccountRequest(
        trader_key=<bytes>,
        amount_sat=<uint64>,
        fee_rate_sat_per_kw=<uint64>,
    )
>>> response = stub.DepositAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "account": <Account>,
    "deposit_txid": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  trader_key: <bytes>, 
  amount_sat: <uint64>, 
  fee_rate_sat_per_kw: <uint64>, 
};
trader.depositAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "account": <Account>,
//      "deposit_txid": <bytes>,
//  }

gRPC Request: poolrpc.DepositAccountRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that funds will be deposited into.
amount_sat uint64 The amount in satoshis to deposit into the account.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kw, to use for the deposit transaction.

gRPC Response: poolrpc.DepositAccountResponse

Parameter Type Description
account Account The state of the account after processing the deposit.
deposit_txid bytes The transaction used to deposit funds into the account.

Trader.ExpectSidecarChannel

Unary RPC

ExpectSidecarChannel is step 4/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the recipient once the provider has submitted the bid order for the sidecar channel. From this point onwards the Pool trader daemon of both the provider as well as the recipient need to be online to receive and react to match making events from the server.


# Connect to the auctioneer and wait for a sidecar order to be matched and
# a channel being opened to us.

$ pool sidecar expectchannel ticket

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.ExpectSidecarChannelRequest(
        ticket=<string>,
    )
>>> response = stub.ExpectSidecarChannel(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  ticket: <string>, 
};
trader.expectSidecarChannel(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: poolrpc.ExpectSidecarChannelRequest

Parameter Type Description
ticket string The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered".

gRPC Response: poolrpc.ExpectSidecarChannelResponse

This response has no parameters.

Trader.GetInfo

Unary RPC

GetInfo returns general information about the state of the Pool trader daemon.


# Displays basic info about the current state of the Pool trader daemon

$ pool getinfo [arguments...]

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.GetInfoRequest()
>>> response = stub.GetInfo(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "version": <string>,
    "accounts_total": <uint32>,
    "accounts_active": <uint32>,
    "accounts_active_expired": <uint32>,
    "accounts_archived": <uint32>,
    "orders_total": <uint32>,
    "orders_active": <uint32>,
    "orders_archived": <uint32>,
    "current_block_height": <uint32>,
    "batches_involved": <uint32>,
    "node_rating": <NodeRating>,
    "lsat_tokens": <uint32>,
    "subscribed_to_auctioneer": <bool>,
    "new_nodes_only": <bool>,
    "market_info": <array MarketInfoEntry>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = {}
trader.getInfo(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "version": <string>,
//      "accounts_total": <uint32>,
//      "accounts_active": <uint32>,
//      "accounts_active_expired": <uint32>,
//      "accounts_archived": <uint32>,
//      "orders_total": <uint32>,
//      "orders_active": <uint32>,
//      "orders_archived": <uint32>,
//      "current_block_height": <uint32>,
//      "batches_involved": <uint32>,
//      "node_rating": <NodeRating>,
//      "lsat_tokens": <uint32>,
//      "subscribed_to_auctioneer": <bool>,
//      "new_nodes_only": <bool>,
//      "market_info": <array MarketInfoEntry>,
//  }

gRPC Request: poolrpc.GetInfoRequest

This request has no parameters.

gRPC Response: poolrpc.GetInfoResponse

Parameter Type Description
version string The version of the Pool daemon that is running.
accounts_total uint32 The total number of accounts in the local database.
accounts_active uint32 The total number of accounts that are in an active, non-archived state, including expired accounts.
accounts_active_expired uint32 The total number of accounts that are active but have expired.
accounts_archived uint32 The total number of accounts that are in an archived/closed state.
orders_total uint32 The total number of orders in the local database.
orders_active uint32 The total number of active/pending orders that are still waiting for execution.
orders_archived uint32 The total number of orders that have been archived.
current_block_height uint32 The current block height as seen by the connected lnd node.
batches_involved uint32 The number of batches an account of this node was ever involved in.
node_rating NodeRating Our lnd node's rating as judged by the auctioneer server.
lsat_tokens uint32 The number of available LSAT tokens.
subscribed_to_auctioneer bool Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server.
new_nodes_only bool Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon.
market_info array MarketInfoEntry A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest.

Trader.GetLsatTokens

Unary RPC

GetLsatTokens returns all LSAT tokens the daemon ever paid for.


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

$ pool listauth [arguments...]

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.TokensRequest()
>>> response = stub.GetLsatTokens(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "tokens": <array LsatToken>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = {}
trader.getLsatTokens(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "tokens": <array LsatToken>,
//  }

gRPC Request: poolrpc.TokensRequest

This request has no parameters.

gRPC Response: poolrpc.TokensResponse

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

Trader.InitAccount

Unary RPC

InitAccount creates a new account with the requested size and expiration, funding it from the wallet of the connected lnd node.


# Send the amount in satoshis specified by the amt argument to a
# new account.

$ pool accounts new [command options] amt [--expiry_height | --expiry_blocks]

# --amt value            the amount in satoshis to create account for (default: 0)
# --expiry_height value  the block height at which this account should expire at (default: 0)
# --expiry_blocks value  the relative height (from the current chain height) that the account should expire at (default of 30 days equivalent in blocks) (default: 4320)
# --conf_target value    the target number of blocks the on-chain account funding transaction should confirm within (default: 6)
# --force                skip account fee confirmation
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.InitAccountRequest(
        account_value=<uint64>,
        absolute_height=<uint32>,
        relative_height=<uint32>,
        conf_target=<uint32>,
        initiator=<string>,
    )
>>> response = stub.InitAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "trader_key": <bytes>,
    "outpoint": <OutPoint>,
    "value": <uint64>,
    "available_balance": <uint64>,
    "expiration_height": <uint32>,
    "state": <AccountState>,
    "latest_txid": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  account_value: <uint64>, 
  absolute_height: <uint32>, 
  relative_height: <uint32>, 
  conf_target: <uint32>, 
  initiator: <string>, 
};
trader.initAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "trader_key": <bytes>,
//      "outpoint": <OutPoint>,
//      "value": <uint64>,
//      "available_balance": <uint64>,
//      "expiration_height": <uint32>,
//      "state": <AccountState>,
//      "latest_txid": <bytes>,
//  }

gRPC Request: poolrpc.InitAccountRequest

Parameter Type Description
account_value uint64
absolute_height uint32
relative_height uint32
conf_target uint32 The target number of blocks that the transaction should be confirmed in.
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI).

gRPC Response: poolrpc.Account

Parameter Type Description
trader_key bytes The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer.
outpoint OutPoint The current outpoint associated with the account. This will change every time the account has been updated.
value uint64 The current total amount of satoshis in the account.
available_balance uint64 The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders.
expiration_height uint32 The height at which the account will expire.
state AccountState The current state of the account.
latest_txid bytes The hash of the account's latest transaction.

Trader.LeaseDurations

Unary RPC

LeaseDurations returns the current set of valid lease duration in the market as is, and also information w.r.t if the market is currently active.


# - returns the current active set of accepted lease durations for orders

$ pool auction leasedurations [arguments...]

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.LeaseDurationRequest()
>>> response = stub.LeaseDurations(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "lease_durations": <array LeaseDurationsEntry>,
    "lease_duration_buckets": <array LeaseDurationBucketsEntry>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = {}
trader.leaseDurations(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "lease_durations": <array LeaseDurationsEntry>,
//      "lease_duration_buckets": <array LeaseDurationBucketsEntry>,
//  }

gRPC Request: poolrpc.LeaseDurationRequest

This request has no parameters.

gRPC Response: poolrpc.LeaseDurationResponse

Parameter Type Description
lease_durations array LeaseDurationsEntry Deprecated, use lease_duration_buckets.
lease_duration_buckets array LeaseDurationBucketsEntry The set of lease durations the market is currently accepting and the state the duration buckets currently are in.

Trader.Leases

Unary RPC

Leases returns the list of channels that were either purchased or sold by the trader within the auction.


# Returns the list of leases (i.e., channels) that were either purchased
# or sold by the trader within the auction. An optional list of batch IDs
# and accounts can be specified to filter the leases returned.

$ pool auction leases [command options] [arguments...]

# --batch_ids value  the target batch IDs to obtain leases for, if left blank, leases from all batches are returned
# --accounts value   the target accounts to obtain leases for, if left blank, leases from all accounts are returned
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.LeasesRequest(
        batch_ids=<array bytes>,
        accounts=<array bytes>,
    )
>>> response = stub.Leases(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "leases": <array Lease>,
    "total_amt_earned_sat": <uint64>,
    "total_amt_paid_sat": <uint64>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  batch_ids: <array bytes>, 
  accounts: <array bytes>, 
};
trader.leases(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "leases": <array Lease>,
//      "total_amt_earned_sat": <uint64>,
//      "total_amt_paid_sat": <uint64>,
//  }

gRPC Request: poolrpc.LeasesRequest

Parameter Type Description
batch_ids array bytes An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned.
accounts array bytes An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned.

gRPC Response: poolrpc.LeasesResponse

Parameter Type Description
leases array Lease The relevant list of leases purchased or sold within the auction.
total_amt_earned_sat uint64 The total amount of satoshis earned from the leases returned.
total_amt_paid_sat uint64 The total amount of satoshis paid for the leases returned.

Trader.ListAccounts

Unary RPC

ListAccounts returns a list of all accounts known to the trader daemon and their current state.


# List all existing accounts.

$ pool accounts list [command options] [arguments...]

# --show_archived  include accounts that are no longer active
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.ListAccountsRequest(
        active_only=<bool>,
    )
>>> response = stub.ListAccounts(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "accounts": <array Account>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  active_only: <bool>, 
};
trader.listAccounts(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "accounts": <array Account>,
//  }

gRPC Request: poolrpc.ListAccountsRequest

Parameter Type Description
active_only bool Only list accounts that are still active.

gRPC Response: poolrpc.ListAccountsResponse

Parameter Type Description
accounts array Account

Trader.ListOrders

Unary RPC

ListOrders returns a list of all active and archived orders that are currently known to the trader daemon.


# List all orders that are stored in the local order database

$ pool orders list [command options] [arguments...]

# --verbose        show verbose output including events
# --show_archived  include orders no longer active
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.ListOrdersRequest(
        verbose=<bool>,
        active_only=<bool>,
    )
>>> response = stub.ListOrders(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "asks": <array Ask>,
    "bids": <array Bid>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  verbose: <bool>, 
  active_only: <bool>, 
};
trader.listOrders(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "asks": <array Ask>,
//      "bids": <array Bid>,
//  }

gRPC Request: poolrpc.ListOrdersRequest

Parameter Type Description
verbose bool Can be set to true to list the orders including all events, which can be very verbose.
active_only bool Only list orders that are still active.

gRPC Response: poolrpc.ListOrdersResponse

Parameter Type Description
asks array Ask
bids array Bid

Trader.NextBatchInfo

Unary RPC

NextBatchInfo returns information about the next batch the auctioneer will perform.


# - returns information about the next batch the auctioneer will attempt to clear

$ pool auction nextbatchinfo [arguments...]

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.NextBatchInfoRequest()
>>> response = stub.NextBatchInfo(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "conf_target": <uint32>,
    "fee_rate_sat_per_kw": <uint64>,
    "clear_timestamp": <uint64>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = {}
trader.nextBatchInfo(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "conf_target": <uint32>,
//      "fee_rate_sat_per_kw": <uint64>,
//      "clear_timestamp": <uint64>,
//  }

gRPC Request: poolrpc.NextBatchInfoRequest

This request has no parameters.

gRPC Response: poolrpc.NextBatchInfoResponse

Parameter Type Description
conf_target uint32 The confirmation target the auctioneer will use for fee estimation of the next batch.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch.
clear_timestamp uint64 The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch.

Trader.NodeRatings

Unary RPC

Returns the Node Tier information for this target Lightning node, and other related ranking information.


# Returns the current Node Tier of a node, along with other
# information.

$ pool auction ratings [command options] [arguments...]

# --node_key value  the node key to look up the rating for
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.NodeRatingRequest(
        node_pubkeys=<array bytes>,
    )
>>> response = stub.NodeRatings(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "node_ratings": <array NodeRating>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  node_pubkeys: <array bytes>, 
};
trader.nodeRatings(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "node_ratings": <array NodeRating>,
//  }

gRPC Request: poolrpc.NodeRatingRequest

Parameter Type Description
node_pubkeys array bytes The target node to obtain ratings information for.

gRPC Response: poolrpc.NodeRatingResponse

Parameter Type Description
node_ratings array NodeRating A series of node ratings for each of the queried nodes.

Trader.OfferSidecar

Unary RPC

OfferSidecar is step 1/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the provider. The result is a sidecar ticket with an offer to lease a sidecar channel for the recipient. The offer will be signed with the provider's lnd node public key. The ticket returned by this call will have the state "offered".


# Creates an offer for providing a sidecar channel to another node.
# If the auto flag is specified, then all bid information needs to be
# specified as normal. If the auto flag isn't specified, then only
# capacity, self_chan_balance, lease_duration_blocks, and acct_key
# need to set.

$ pool sidecar offer [command options] [<full bid args> --auto] | capacity self_chan_balance lease_duration_blocks acct_key

# --interest_rate_percent value  the total percent one is willing to pay or accept as yield for the specified interval (default: 0)
# --amt value                    the amount of inbound liquidity in satoshis to request (default: 0)
# --acct_key value               the account key to use to pay the order fees with
# --lease_duration_blocks value  the number of blocks that the liquidity should be provided for (default: 2016)
# --min_node_tier value          the min node tier this bid should be matched with, tier 1 nodes are considered 'good', if set to tier 0, then all nodes will be considered regardless of 'quality' (default: 0)
# --min_chan_amt value           the minimum amount of satoshis that a resulting channel from this order must have (default: 0)
# --force                        skip order placement confirmation
# --self_chan_balance value      give the channel leased by this bid order an initial balance by adding additional funds from our account into the channel; can be used to create up to 50/50 balanced channels (default: 0)
# --max_batch_fee_rate value     the maximum fee rate (sat/vByte) to use to for the batch transaction (default: 100)
# --auto                         if true, then the full bid information needs to be specified as automated negotiation will be attempted
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.OfferSidecarRequest(
        auto_negotiate=<bool>,
        bid=<Bid>,
    )
>>> response = stub.OfferSidecar(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "ticket": <string>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  auto_negotiate: <bool>, 
  bid: <Bid>, 
};
trader.offerSidecar(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "ticket": <string>,
//  }

gRPC Request: poolrpc.OfferSidecarRequest

Parameter Type Description
auto_negotiate bool If false, then only the trader_key, unit, self_chan_balance, and lease_duration_blocks need to be set in the bid below. Otherwise, the fields as they're set when submitting a bid need to be filled in.
bid Bid The bid template that will be used to populate the initial sidecar ticket as well as auto negotiate the remainig steps of the sidecar channel if needed.

gRPC Response: poolrpc.SidecarTicket

Parameter Type Description
ticket string The complete sidecar ticket in its string encoded form which is base64 URL encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.

Trader.QuoteAccount

Unary RPC

QuoteAccount gets a fee quote to fund an account of the given size with the given confirmation target. If the connected lnd wallet doesn't have enough balance to fund an account of the requested size, an error is returned.


>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.QuoteAccountRequest(
        account_value=<uint64>,
        conf_target=<uint32>,
    )
>>> response = stub.QuoteAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "miner_fee_rate_sat_per_kw": <uint64>,
    "miner_fee_total": <uint64>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  account_value: <uint64>, 
  conf_target: <uint32>, 
};
trader.quoteAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "miner_fee_rate_sat_per_kw": <uint64>,
//      "miner_fee_total": <uint64>,
//  }

gRPC Request: poolrpc.QuoteAccountRequest

Parameter Type Description
account_value uint64
conf_target uint32 The target number of blocks that the transaction should be confirmed in.

gRPC Response: poolrpc.QuoteAccountResponse

Parameter Type Description
miner_fee_rate_sat_per_kw uint64
miner_fee_total uint64

Trader.QuoteOrder

Unary RPC

QuoteOrder calculates the premium, execution fees and max batch fee rate for an order based on the given order parameters.


>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.QuoteOrderRequest(
        amt=<uint64>,
        rate_fixed=<uint32>,
        lease_duration_blocks=<uint32>,
        max_batch_fee_rate_sat_per_kw=<uint64>,
        min_units_match=<uint32>,
    )
>>> response = stub.QuoteOrder(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "total_premium_sat": <uint64>,
    "rate_per_block": <double>,
    "rate_percent": <double>,
    "total_execution_fee_sat": <uint64>,
    "worst_case_chain_fee_sat": <uint64>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  amt: <uint64>, 
  rate_fixed: <uint32>, 
  lease_duration_blocks: <uint32>, 
  max_batch_fee_rate_sat_per_kw: <uint64>, 
  min_units_match: <uint32>, 
};
trader.quoteOrder(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "total_premium_sat": <uint64>,
//      "rate_per_block": <double>,
//      "rate_percent": <double>,
//      "total_execution_fee_sat": <uint64>,
//      "worst_case_chain_fee_sat": <uint64>,
//  }

gRPC Request: poolrpc.QuoteOrderRequest

Parameter Type Description
amt uint64 Order amount in satoshis.
rate_fixed uint32 Fixed order rate in parts per billion.
lease_duration_blocks uint32 Required number of blocks that a channel opened as a result of this bid should be kept open.
max_batch_fee_rate_sat_per_kw uint64 Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
min_units_match uint32 The minimum number of order units that must be matched per order pair.

gRPC Response: poolrpc.QuoteOrderResponse

Parameter Type Description
total_premium_sat uint64 The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees.
rate_per_block double The fixed order rate expressed as a fraction instead of parts per billion.
rate_percent double The fixed order rate expressed as a percentage instead of parts per billion.
total_execution_fee_sat uint64 The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order.
worst_case_chain_fee_sat uint64 The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation).

Trader.RecoverAccounts

Unary RPC

RecoverAccounts queries the auction server for this trader daemon's accounts in case we lost our local account database.


# In case the data directory of the trader was corrupted or lost, this
# command can be used to ask the auction server to send back its view of
# the trader's accounts. This is possible as long as the connected lnd
# node is running with the same seed as when the accounts to recover were
# first created.
# NOTE: This command should only be used after data loss as it will fail
# if there already are open accounts in the trader's database.
# All open or pending orders of any recovered account will be canceled on
# the auctioneer's side and won't be restored in the trader's database.

$ pool accounts recover [arguments...]

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.RecoverAccountsRequest()
>>> response = stub.RecoverAccounts(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "num_recovered_accounts": <uint32>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = {}
trader.recoverAccounts(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "num_recovered_accounts": <uint32>,
//  }

gRPC Request: poolrpc.RecoverAccountsRequest

This request has no parameters.

gRPC Response: poolrpc.RecoverAccountsResponse

Parameter Type Description
num_recovered_accounts uint32 The number of accounts that were recovered.

Trader.RegisterSidecar

Unary RPC

RegisterSidecarRequest is step 2/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the recipient. The result is a sidecar ticket with the recipient's node information and channel funding multisig pubkey filled in. The ticket returned by this call will have the state "registered".


# Registers a sidecar ticket for an incoming sidecar channel with the node
# and adds its recipient information to it, resulting in an updated ticket
# that needs to be handed back to the provider.

$ pool sidecar register ticket

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.RegisterSidecarRequest(
        ticket=<string>,
        auto_negotiate=<bool>,
    )
>>> response = stub.RegisterSidecar(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "ticket": <string>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  ticket: <string>, 
  auto_negotiate: <bool>, 
};
trader.registerSidecar(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "ticket": <string>,
//  }

gRPC Request: poolrpc.RegisterSidecarRequest

Parameter Type Description
ticket string The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered".
auto_negotiate bool If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down.

gRPC Response: poolrpc.SidecarTicket

Parameter Type Description
ticket string The complete sidecar ticket in its string encoded form which is base64 URL encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.

Trader.RenewAccount

Unary RPC

RenewAccount renews the expiration of an account.


# Renews the expiration of an account. This will broadcast a chain
# transaction as the expiry is enforced within the account output script.
# The fee rate of said transaction must be specified.

$ pool accounts renew [command options] trader_key sat_per_vbyte [--expiry_height | --expiry_blocks]

# --trader_key value     the hex-encoded trader key of the account to renew
# --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the renewal transaction (default: 0)
# --expiry_height value  the new block height at which this account should expire at (default: 0)
# --expiry_blocks value  the new relative height (from the current chain height) that the account should expire at (default of 30 days equivalent in blocks) (default: 4320)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.RenewAccountRequest(
        account_key=<bytes>,
        absolute_expiry=<uint32>,
        relative_expiry=<uint32>,
        fee_rate_sat_per_kw=<uint64>,
    )
>>> response = stub.RenewAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "account": <Account>,
    "renewal_txid": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  account_key: <bytes>, 
  absolute_expiry: <uint32>, 
  relative_expiry: <uint32>, 
  fee_rate_sat_per_kw: <uint64>, 
};
trader.renewAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "account": <Account>,
//      "renewal_txid": <bytes>,
//  }

gRPC Request: poolrpc.RenewAccountRequest

Parameter Type Description
account_key bytes The key associated with the account to renew.
absolute_expiry uint32 The new absolute expiration height of the account.
relative_expiry uint32 The new relative expiration height of the account.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kw, to use for the renewal transaction.

gRPC Response: poolrpc.RenewAccountResponse

Parameter Type Description
account Account The state of the account after processing the renewal.
renewal_txid bytes The transaction used to renew the expiration of the account.

Trader.StopDaemon

Unary RPC

Stop gracefully shuts down the Pool trader daemon.


# Sends the stop command to the Pool trader daemon to initiate a graceful shutdown

$ pool stop [arguments...]

>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.StopDaemonRequest()
>>> response = stub.StopDaemon(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = {}
trader.stopDaemon(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//  }

gRPC Request: poolrpc.StopDaemonRequest

This request has no parameters.

gRPC Response: poolrpc.StopDaemonResponse

This response has no parameters.

Trader.SubmitOrder

Unary RPC

SubmitOrder creates a new ask or bid order and submits for the given account and submits it to the auction server for matching.


# - submit an order

$ bid  obtain channel liquidity

# --help, -h  show help
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.SubmitOrderRequest(
        ask=<Ask>,
        bid=<Bid>,
        initiator=<string>,
    )
>>> response = stub.SubmitOrder(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "invalid_order": <InvalidOrder>,
    "accepted_order_nonce": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  ask: <Ask>, 
  bid: <Bid>, 
  initiator: <string>, 
};
trader.submitOrder(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "invalid_order": <InvalidOrder>,
//      "accepted_order_nonce": <bytes>,
//  }

gRPC Request: poolrpc.SubmitOrderRequest

Parameter Type Description
ask Ask
bid Bid
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI).

gRPC Response: poolrpc.SubmitOrderResponse

Parameter Type Description
invalid_order InvalidOrder Order failed with the given reason.
accepted_order_nonce bytes The order nonce of the accepted order.

Trader.WithdrawAccount

Unary RPC

WithdrawAccount splits off parts of the account balance into the specified outputs while recreating the account with a reduced balance.


# Withdraw funds from an existing account to a supported address.

$ pool accounts withdraw [command options] trader_key amt addr sat_per_vbyte

# --trader_key value     the hex-encoded trader key of the account to withdraw funds from
# --addr value           the address the withdrawn funds should go to
# --amt value            the amount that will be sent to the address and withdrawn from the account (default: 0)
# --sat_per_vbyte value  the fee rate expressed in sat/vbyte that should be used for the withdrawal (default: 0)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the /poolrpc/trader.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import trader_pb2 as poolrpc, trader_pb2_grpc as traderstub
>>> channel = grpc.insecure_channel('localhost:12010')
>>> stub = traderstub.TraderStub(channel)
>>> request = poolrpc.WithdrawAccountRequest(
        trader_key=<bytes>,
        outputs=<array Output>,
        fee_rate_sat_per_kw=<uint64>,
    )
>>> response = stub.WithdrawAccount(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{ 
    "account": <Account>,
    "withdraw_txid": <bytes>,
}
const grpc = require('grpc');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
};
const packageDefinition = protoLoader.loadSync('poolrpc/trader.proto', loaderOptions);
const poolrpc = grpc.loadPackageDefinition(packageDefinition).poolrpc;
const trader = new poolrpc.Trader('localhost:12010', grpc.credentials.createInsecure());
let request = { 
  trader_key: <bytes>, 
  outputs: <array Output>, 
  fee_rate_sat_per_kw: <uint64>, 
};
trader.withdrawAccount(request, function(err, response) {
  console.log(response);
});
// Console output:
//  { 
//      "account": <Account>,
//      "withdraw_txid": <bytes>,
//  }

gRPC Request: poolrpc.WithdrawAccountRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that funds will be withdrawed from.
outputs array Output The outputs we'll withdraw funds from the account into.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kw, to use for the withdrawal transaction.

gRPC Response: poolrpc.WithdrawAccountResponse

Parameter Type Description
account Account The state of the account after processing the withdrawal.
withdraw_txid bytes The transaction used to withdraw funds from the account.

gRPC Messages

poolrpc.AccountCommitment

Parameter Type Description
commit_hash bytes The SHA256 hash of the trader's account key and a 32 byte random nonce. commit_hash = SHA256(accountPubKey
batch_version uint32 The batch verification protocol version the client is using. Clients that don't use the latest version will be declined to connect and participate in an auction. The user should then be informed that a software update is required.

poolrpc.AccountDiff

Parameter Type Description
ending_balance uint64 The final balance of the account after the executed batch.
ending_state AccountState Depending on the amount of the final balance of the account, the remainder is either sent to a new on-chain output, extended off-chain or fully consumed by the batch and its fees.
outpoint_index int32 If the account was re-created on-chain then the new account's index in the transaction is set here. If the account was fully spent or the remainder was extended off-chain then no new account outpoint is created and -1 is returned here.
trader_key bytes The trader's account key this diff is referring to.

poolrpc.AccountRecovery

Parameter Type Description
trader_key bytes The trader's account key of the account to recover.

poolrpc.AccountSubscription

Parameter Type Description
trader_key bytes The trader's account key of the account to subscribe to.
commit_nonce bytes The random 32 byte nonce the trader used to create the commitment hash.
auth_sig bytes The signature over the auth_hash which is the hash of the commitment and challenge. The signature is created with the trader's account key they committed to. auth_hash = SHA256(SHA256(accountPubKey

poolrpc.AskSnapshot

Parameter Type Description
version uint32 The version of the order.
lease_duration_blocks uint32 The period of time the channel will survive for.
rate_fixed uint32 The true bid price of the order in parts per billion.
chan_type uint32 The channel type to be created.

poolrpc.AuctionAccount

Parameter Type Description
value uint64 The value of the account in satoshis. Must match the amount of the account_point output.
expiry uint32 The block height at which the account should expire.
trader_key bytes The trader's account key.
auctioneer_key bytes The long term auctioneer's account key.
batch_key bytes The current batch key used to create the account output.
state AuctionAccountState The current state of the account as the auctioneer sees it.
height_hint uint32 The block height of the last change to the account's output. Can be used to scan the chain for the output's spend state more efficiently.
outpoint OutPoint Transaction output of the account. Depending on the state of the account, this output might have been spent.
latest_tx bytes The latest transaction of an account. This is only known by the auctioneer after the account has met its initial funding confirmation.

poolrpc.BatchSnapshotRequest

Parameter Type Description
batch_id bytes The unique identifier of the batch encoded as a compressed pubkey.

poolrpc.BatchSnapshotResponse

Parameter Type Description
version uint32 The version of the batch.
batch_id bytes The unique identifier of the batch.
prev_batch_id bytes The unique identifier of the prior batch.
clearing_price_rate uint32 Deprecated, use matched_markets.
matched_orders array MatchedOrderSnapshot Deprecated, use matched_markets.
batch_tx_id string The txid of the batch transaction.
batch_tx bytes The batch transaction including all witness data.
batch_tx_fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kiloweight, of the batch transaction.
creation_timestamp_ns uint64 The unix timestamp in nanoseconds the batch was made.
matched_markets array MatchedMarketsEntry Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.

poolrpc.BatchSnapshotResponse.MatchedMarketsEntry

Parameter Type Description
key uint32
value MatchedMarketSnapshot

poolrpc.BatchSnapshotsRequest

Parameter Type Description
start_batch_id bytes The unique identifier of the first batch to return, encoded as a compressed pubkey. This represents the newest/most current batch to fetch. If this is empty or a zero batch ID, the most recent finalized batch is used as the starting point to go back from.
num_batches_back uint32 The number of batches to return at most, including the start batch.

poolrpc.BatchSnapshotsResponse

Parameter Type Description
batches array BatchSnapshotResponse The list of batches requested.

poolrpc.BidSnapshot

Parameter Type Description
version uint32 The version of the order.
lease_duration_blocks uint32 The period of time the matched channel should be allocated for.
rate_fixed uint32 The true bid price of the order in parts per billion.
chan_type uint32 The channel type to be created.

poolrpc.CancelOrder

Parameter Type Description
order_nonce bytes

poolrpc.ChannelInfo

Parameter Type Description
type ChannelType The identifying type of the channel.
local_node_key bytes The node's identifying public key.
remote_node_key bytes The remote node's identifying public key.
local_payment_base_point bytes The node's base public key used within the non-delayed pay-to-self output on the commitment transaction.
remote_payment_base_point bytes RemotePaymentBasePoint is the remote node's base public key used within the non-delayed pay-to-self output on the commitment transaction.

poolrpc.ClientAuctionMessage

Parameter Type Description
commit AccountCommitment Signal the intent to receive updates about a certain account and start by sending the commitment part of the authentication handshake. This is step 1 of the 3-way handshake.
subscribe AccountSubscription Subscribe to update and interactive order execution events for account given and all its orders. Contains the final signature and is step 3 of the 3-way authentication handshake.
accept OrderMatchAccept Accept the orders to be matched.
reject OrderMatchReject Reject a whole batch.
sign OrderMatchSign The channel funding negotiations with the matched peer were successful and the inputs to spend from the accounts are now signed.
recover AccountRecovery The trader has lost its database and is trying to recover their accounts. This message can be sent after the successful completion of the 3-way authentication handshake where it will be established if the account exists on the auctioneer's side. This message must only be sent if the auctioneer knows of the account, otherwise it will regard it as a critical error and terminate the connection.

poolrpc.ExecutionFee

Parameter Type Description
base_fee uint64 The base fee in satoshis charged per order, regardless of the matched size.
fee_rate uint64 The fee rate in parts per million.

poolrpc.InvalidOrder

Parameter Type Description
order_nonce bytes
fail_reason FailReason
fail_string string

poolrpc.MarketInfo

Parameter Type Description
num_asks array TierValue The number of open/pending ask orders per node tier.
num_bids array TierValue The number of open/pending bid orders per node tier.
ask_open_interest_units array TierValue The total number of open/unmatched units in open/pending ask orders per node tier.
bid_open_interest_units array TierValue The total number of open/unmatched units in open/pending bid orders per node tier.

poolrpc.MarketInfo.TierValue

Parameter Type Description
tier NodeTier
value uint32

poolrpc.MarketInfoRequest

This message has no parameters.

poolrpc.MarketInfoResponse

Parameter Type Description
markets array MarketsEntry A map of all markets identified by their lease duration and the current set of statistics.

poolrpc.MarketInfoResponse.MarketsEntry

Parameter Type Description
key uint32
value MarketInfo

poolrpc.MatchedAsk

Parameter Type Description
ask ServerAsk The ask order that was matched against.
units_filled uint32 The number of units that were filled from/by this matched order.

poolrpc.MatchedBid

Parameter Type Description
bid ServerBid The ask order that was matched against.
units_filled uint32 The number of units that were filled from/by this matched order.

poolrpc.MatchedMarket

Parameter Type Description
matched_orders array MatchedOrdersEntry Maps a user's own order_nonce to the opposite order type they were matched with. The order_nonce is a 32 byte hex encoded string because bytes is not allowed as a map key data type in protobuf.
clearing_price_rate uint32 The uniform clearing price rate in parts per billion that was used for this batch.

poolrpc.MatchedMarket.MatchedOrdersEntry

Parameter Type Description
key string
value MatchedOrder

poolrpc.MatchedMarketSnapshot

Parameter Type Description
matched_orders array MatchedOrderSnapshot The set of all orders matched in the batch.
clearing_price_rate uint32 The uniform clearing price rate in parts per billion that was used for this batch.

poolrpc.MatchedOrder

Parameter Type Description
matched_bids array MatchedBid The bids the trader's own order was matched against. This list is empty if the trader's order was a bid order itself.
matched_asks array MatchedAsk The asks the trader's own order was matched against. This list is empty if the trader's order was an ask order itself.

poolrpc.MatchedOrderSnapshot

Parameter Type Description
ask AskSnapshot The full ask order that was matched.
bid BidSnapshot The full bid order that was matched.
matching_rate uint32 The fixed rate premium that was matched, expressed in parts-ber-billion.
total_sats_cleared uint64 The total number of satoshis that were bought.
units_matched uint32 The total number of units that were matched.

poolrpc.NodeAddress

Parameter Type Description
network string
addr string

poolrpc.NodeRating

Parameter Type Description
node_pubkey bytes The pubkey for the node these ratings belong to.
node_tier NodeTier The tier of the target node.

poolrpc.OrderMatchAccept

Parameter Type Description
batch_id bytes The batch ID this acceptance message refers to. Must be set to avoid out-of- order responses from disrupting the batching process.

poolrpc.OrderMatchFinalize

Parameter Type Description
batch_id bytes The unique identifier of the finalized batch.
batch_txid bytes The final transaction ID of the published batch transaction.
height_hint uint32 The current block height at the time the batch transaction was published to the network.

poolrpc.OrderMatchPrepare

Parameter Type Description
matched_orders array MatchedOrdersEntry Deprecated, use matched_markets.
clearing_price_rate uint32 Deprecated, use matched_markets.
charged_accounts array AccountDiff A list of the user's own accounts that are being spent by the matched orders. The list contains the differences that would be applied by the server when executing the orders.
execution_fee ExecutionFee The fee parameters used to calculate the execution fees.
batch_transaction bytes The batch transaction with all non-witness data.
fee_rate_sat_per_kw uint64 Fee rate of the batch transaction, expressed in satoshis per 1000 weight units (sat/kW).
fee_rebate_sat uint64 Fee rebate in satoshis, offered if another batch participant wants to pay more fees for a faster confirmation.
batch_id bytes The 32 byte unique identifier of this batch.
batch_version uint32 The batch verification protocol version the server is using. Clients that don't support this version MUST return an OrderMatchAccept message with an empty list of orders so the batch can continue. The user should then be informed that a software update is required.
matched_markets array MatchedMarketsEntry Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.

poolrpc.OrderMatchPrepare.MatchedMarketsEntry

Parameter Type Description
key uint32
value MatchedMarket

poolrpc.OrderMatchPrepare.MatchedOrdersEntry

Parameter Type Description
key string
value MatchedOrder

poolrpc.OrderMatchReject

Parameter Type Description
batch_id bytes The ID of the batch to reject.
reason string The reason/error string for the rejection.
reason_code RejectReason The reason as a code.
rejected_orders array RejectedOrdersEntry The map of order nonces the trader was matched with but doesn't accept. The map contains the other trader's order nonces and the reason for rejecting them. This can be a subset of the whole list of orders presented as matches if the trader only wants to reject some of them. This map is only considered by the auctioneer if the main reason_code is set to PARTIAL_REJECT. Otherwise it is assumed that the whole batch was faulty for some reason and that the trader rejects all orders contained. The auctioneer will only accept a certain number of these partial rejects before a trader's account is removed completely from the current batch. Abusing this functionality can also lead to a ban of the trader. The order nonces are hex encoded strings because the protobuf map doesn't allow raw bytes to be the map key type.

poolrpc.OrderMatchReject.RejectedOrdersEntry

Parameter Type Description
key string
value OrderReject

poolrpc.OrderMatchSign

Parameter Type Description
batch_id bytes The ID of the batch that the signatures are meant for.
account_sigs array AccountSigsEntry A map with the signatures to spend the accounts being spent in a batch transaction. The map key corresponds to the trader's account key of the account in the batch transaction. The account key/ID has to be hex encoded into a string because protobuf doesn't allow bytes as a map key data type.
channel_infos array ChannelInfosEntry The information for each channel created as part of a batch that's submitted to the auctioneer to ensure they can properly enforce a channel's service lifetime. Entries are indexed by the string representation of a channel's outpoint.

poolrpc.OrderMatchSign.AccountSigsEntry

Parameter Type Description
key string
value bytes

poolrpc.OrderMatchSign.ChannelInfosEntry

Parameter Type Description
key string
value ChannelInfo

poolrpc.OrderMatchSignBegin

Parameter Type Description
batch_id bytes The 32 byte unique identifier of this batch.

poolrpc.OrderReject

Parameter Type Description
reason string The reason/error string for the rejection.
reason_code OrderRejectReason The reason as a code.

poolrpc.OutPoint

Parameter Type Description
txid bytes Raw bytes representing the transaction id.
output_index uint32 The index of the output on the transaction.

poolrpc.RelevantBatch

Parameter Type Description
version uint32 The version of the batch.
id bytes The unique identifier of the batch.
charged_accounts array AccountDiff The set of modifications that should be applied to the requested accounts as a result of this batch.
matched_orders array MatchedOrdersEntry Deprecated, use matched_markets.
clearing_price_rate uint32 Deprecated, use matched_markets.
execution_fee ExecutionFee The fee parameters used to calculate the execution fees.
transaction bytes The batch transaction including all witness data.
fee_rate_sat_per_kw uint64 Fee rate of the batch transaction, expressed in satoshis per 1000 weight units (sat/kW).
creation_timestamp_ns uint64 The unix timestamp in nanoseconds the batch was made.
matched_markets array MatchedMarketsEntry Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.

poolrpc.RelevantBatch.MatchedMarketsEntry

Parameter Type Description
key uint32
value MatchedMarket

poolrpc.RelevantBatch.MatchedOrdersEntry

Parameter Type Description
key string
value MatchedOrder

poolrpc.RelevantBatchRequest

Parameter Type Description
id bytes The unique identifier of the batch.
accounts array bytes The set of accounts the trader is interested in retrieving information for within the batch. Each account is identified by its trader key.

poolrpc.ReserveAccountRequest

Parameter Type Description
account_value uint64 The desired value of the account in satoshis.
account_expiry uint32 The block height at which the account should expire.
trader_key bytes The trader's account key.

poolrpc.ReserveAccountResponse

Parameter Type Description
auctioneer_key bytes The base key of the auctioneer. This key should be tweaked with the trader's per-batch tweaked key to obtain the corresponding per-batch tweaked auctioneer key.
initial_batch_key bytes The initial per-batch key to be used for the account. For every cleared batch that the account participates in, this key will be incremented by the base point of its curve, resulting in a new key for both the trader and auctioneer in every batch.

poolrpc.ServerAsk

Parameter Type Description
details ServerOrder The common fields shared between both ask and bid order types.
lease_duration_blocks uint32 The number of blocks the liquidity provider is willing to provide the channel funds for.
version uint32 The version of the order format that is used. Will be increased once new features are added.

poolrpc.ServerAuctionMessage

Parameter Type Description
challenge ServerChallenge Step 2 of the 3-way authentication handshake. Contains the authentication challenge. Subscriptions sent by the trader must sign the message SHA256(SHA256(accountPubKey
success SubscribeSuccess The trader has subscribed to account updates successfully, the 3-way authentication handshake completed normally.
error SubscribeError An error occurred during any part of the communication. The trader should inspect the error code and act accordingly.
prepare OrderMatchPrepare The auctioneer has matched a set of orders into a batch and now instructs the traders to validate the batch and prepare for order execution. Because traders have the possibility of backing out of a batch, multiple of these messages with the SAME batch_id can be sent.
sign OrderMatchSignBegin This message is sent after all traders send back an OrderMatchAccept method. It signals that the traders should execute their local funding protocol, then send signatures for their account inputs.
finalize OrderMatchFinalize All traders have accepted and signed the batch and the final transaction was broadcast.
account AuctionAccount The answer to a trader's request for account recovery. This message contains all information that is needed to restore the account to working order on the trader side.

poolrpc.ServerBid

Parameter Type Description
details ServerOrder The common fields shared between both ask and bid order types.
lease_duration_blocks uint32 Required number of blocks that a channel opened as a result of this bid should be kept open.
version uint32 The version of the order format that is used. Will be increased once new features are added.
min_node_tier NodeTier The minimum node tier this order should be matched with. Only asks backed by a node this tier or higher will be eligible for matching with this bid.
self_chan_balance uint64 Give the incoming channel that results from this bid being matched an initial outbound balance by adding additional funds from the taker's account into the channel. As a simplification for the execution protocol and the channel reserve calculations, the self_chan_balance can be at most the same as the order amount and the min_chan_amt must be set to the full order amount.
is_sidecar_channel bool If this bid order is meant to lease a channel for another node (which is dubbed a "sidecar channel") then this boolean needs to be set to true. The multi_sig_key, node_pub and node_addr fields of the order details must then correspond to the recipient node's details.

poolrpc.ServerCancelOrderRequest

Parameter Type Description
order_nonce_preimage bytes The preimage to the order's unique nonce.

poolrpc.ServerCancelOrderResponse

This message has no parameters.

poolrpc.ServerChallenge

Parameter Type Description
challenge bytes The unique challenge for each stream that has to be signed with the trader's account key for each account subscription.
commit_hash bytes The commit hash the challenge was created for.

poolrpc.ServerInitAccountRequest

Parameter Type Description
account_point OutPoint Transaction output of the account. Has to be unspent and be a P2WSH of the account script below. The amount must also exactly correspond to the account value below.
account_script bytes The script used to create the account point.
account_value uint64 The value of the account in satoshis. Must match the amount of the account_point output.
account_expiry uint32 The block height at which the account should expire.
trader_key bytes The trader's account key.
user_agent string The user agent string that identifies the software running on the user's side. This can be changed in the user's client software but it SHOULD conform to the following pattern and use less than 256 characters: Agent-Name/semver-version(/additional-info) Examples: poold/v0.4.2-beta/commit=3b635821,initiator=pool-cli litd/v0.4.0-alpha/commit=326d754,initiator=lit-ui

poolrpc.ServerInitAccountResponse

This message has no parameters.

poolrpc.ServerInput

Parameter Type Description
outpoint OutPoint The outpoint that the input corresponds to.
sig_script bytes The signature script required by the input. This only applies to NP2WKH inputs.

poolrpc.ServerModifyAccountRequest

Parameter Type Description
trader_key bytes The trader's account key of the account to be modified.
new_inputs array ServerInput An additional set of inputs that can be included in the spending transaction of an account. These can be used to deposit more funds into an account. These must be under control of the backing lnd node's wallet.
new_outputs array ServerOutput An additional set of outputs that can be included in the spending transaction of an account. These can be used to withdraw funds from an account.
new_params NewAccountParameters The new parameters to apply for the account.

poolrpc.ServerModifyAccountRequest.NewAccountParameters

Parameter Type Description
value uint64 The new value of the account.
expiry uint32 The new expiry of the account as an absolute height.

poolrpc.ServerModifyAccountResponse

Parameter Type Description
account_sig bytes The auctioneer's signature that allows a trader to broadcast a transaction spending from an account output.

poolrpc.ServerNodeRatingRequest

Parameter Type Description
node_pubkeys array bytes The target node to obtain ratings information for.

poolrpc.ServerNodeRatingResponse

Parameter Type Description
node_ratings array NodeRating A series of node ratings for each of the queried nodes.

poolrpc.ServerOrder

Parameter Type Description
trader_key bytes The trader's account key of the account to use for the order.
rate_fixed uint32 Fixed order rate in parts per billion.
amt uint64 Order amount in satoshis.
min_chan_amt uint64
order_nonce bytes Order nonce of 32 byte length, acts as unique order identifier.
order_sig bytes Signature of the order's digest, signed with the user's account key. The signature must be fixed-size LN wire format encoded. Version 0 includes the fields version, rate_fixed, amt, max_batch_fee_rate_sat_per_kw and lease_duration_blocks in the order digest.
multi_sig_key bytes The multi signature key of the node creating the order, will be used for the target channel's funding TX 2-of-2 multi signature output.
node_pub bytes The pubkey of the node creating the order.
node_addr array NodeAddress The network addresses of the node creating the order.
chan_type uint32 The type of the channel that should be opened.
max_batch_fee_rate_sat_per_kw uint64 Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/kW).

poolrpc.ServerOrderStateRequest

Parameter Type Description
order_nonce bytes

poolrpc.ServerOrderStateResponse

Parameter Type Description
state OrderState The state the order currently is in.
units_unfulfilled uint32 The number of currently unfilled units of this order. This will be equal to the total amount of units until the order has reached the state PARTIAL_FILL or EXECUTED.

poolrpc.ServerOutput

Parameter Type Description
value uint64 The value, in satoshis, of the output.
script bytes The script of the output to send the value to.

poolrpc.ServerSubmitOrderRequest

Parameter Type Description
ask ServerAsk Submit an ask order.
bid ServerBid Submit a bid order.
user_agent string The user agent string that identifies the software running on the user's side. This can be changed in the user's client software but it SHOULD conform to the following pattern and use less than 256 characters: Agent-Name/semver-version(/additional-info) Examples: poold/v0.4.2-beta/commit=3b635821,initiator=pool-cli litd/v0.4.0-alpha/commit=326d754,initiator=lit-ui

poolrpc.ServerSubmitOrderResponse

Parameter Type Description
invalid_order InvalidOrder Order failed with the given reason.
accepted bool Order was accepted.

poolrpc.SubscribeError

Parameter Type Description
error string The string representation of the subscription error.
error_code Error The error code of the subscription error.
trader_key bytes The trader's account key this error is referring to. This is not set if the error code is SERVER_SHUTDOWN as that error is only sent once per connection and not per individual subscription.
account_reservation AuctionAccount The auctioneer's partial account information as it was stored when creating the reservation. This is only set if the error code is INCOMPLETE_ACCOUNT_RESERVATION. Only the fields value, expiry, trader_key, auctioneer_key, batch_key and height_hint will be set in that case.

poolrpc.SubscribeSuccess

Parameter Type Description
trader_key bytes The trader's account key this message is referring to.

poolrpc.TermsRequest

This message has no parameters.

poolrpc.TermsResponse

Parameter Type Description
max_account_value uint64 The maximum account size in satoshis currently allowed by the auctioneer.
max_order_duration_blocks uint32 Deprecated, use explicit order duration from lease_duration_buckets.
execution_fee ExecutionFee The execution fee charged per matched order.
lease_durations array LeaseDurationsEntry Deprecated, use lease_duration_buckets.
next_batch_conf_target uint32 The confirmation target to use for fee estimation of the next batch.
next_batch_fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kiloweight, estimated to use for the next batch.
next_batch_clear_timestamp uint64 The absolute unix timestamp at which the auctioneer will attempt to clear the next batch.
lease_duration_buckets array LeaseDurationBucketsEntry The set of lease durations the market is currently accepting and the state the duration buckets currently are in.

poolrpc.TermsResponse.LeaseDurationBucketsEntry

Parameter Type Description
key uint32
value DurationBucketState

poolrpc.TermsResponse.LeaseDurationsEntry

Parameter Type Description
key uint32
value bool

poolrpc.CipherBox

Parameter Type Description
desc CipherBoxDesc
msg bytes

poolrpc.CipherBoxAuth

Parameter Type Description
desc CipherBoxDesc A description of the stream one is attempting to initialize.
acct_auth PoolAccountAuth
sidecar_auth SidecarAuth

poolrpc.CipherBoxDesc

Parameter Type Description
stream_id bytes

poolrpc.CipherChallenge

This message has no parameters.

poolrpc.CipherError

This message has no parameters.

poolrpc.CipherInitResp

Parameter Type Description
success CipherSuccess CipherSuccess is returned if the initialization of the cipher box was successful.
challenge CipherChallenge CipherChallenge is returned if the authentication mechanism was revoked or needs to be refreshed.
error CipherError CipherError is returned if the authentication mechanism failed to validate.

poolrpc.CipherSuccess

Parameter Type Description
desc CipherBoxDesc

poolrpc.DelCipherBoxResp

This message has no parameters.

poolrpc.PoolAccountAuth

Parameter Type Description
acct_key bytes The account key being used to authenticate.
stream_sig bytes A valid signature over the stream ID being used.

poolrpc.SidecarAuth

Parameter Type Description
ticket string A valid sidecar ticket that has been signed (offered) by a Pool account in the active state.

poolrpc.Account

Parameter Type Description
trader_key bytes The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer.
outpoint OutPoint The current outpoint associated with the account. This will change every time the account has been updated.
value uint64 The current total amount of satoshis in the account.
available_balance uint64 The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders.
expiration_height uint32 The height at which the account will expire.
state AccountState The current state of the account.
latest_txid bytes The hash of the account's latest transaction.

poolrpc.Ask

Parameter Type Description
details Order The common fields shared between both ask and bid order types.
lease_duration_blocks uint32 The number of blocks the liquidity provider is willing to provide the channel funds for.
version uint32 The version of the order format that is used. Will be increased once new features are added.

poolrpc.AuctionFeeRequest

This message has no parameters.

poolrpc.AuctionFeeResponse

Parameter Type Description
execution_fee ExecutionFee The execution fee charged per matched order.

poolrpc.Bid

Parameter Type Description
details Order The common fields shared between both ask and bid order types.
lease_duration_blocks uint32 Required number of blocks that a channel opened as a result of this bid should be kept open.
version uint32 The version of the order format that is used. Will be increased once new features are added.
min_node_tier NodeTier The minimum node tier this order should be matched with. Only asks backed by a node this tier or higher will be eligible for matching with this bid.
self_chan_balance uint64 Give the incoming channel that results from this bid being matched an initial outbound balance by adding additional funds from the taker's account into the channel. As a simplification for the execution protocol and the channel reserve calculations, the self_chan_balance can be at most the same as the order amount and the min_chan_amt must be set to the full order amount.
sidecar_ticket string If this bid order is meant to lease a channel for another node (which is dubbed a "sidecar channel") then this ticket contains all information required for setting up that sidecar channel. The ticket is expected to be the base64 encoded ticket, including the prefix and the checksum.

poolrpc.BumpAccountFeeRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that will have its fee bumped.
fee_rate_sat_per_kw uint64 The new fee rate, in satoshis per kw, to use for the child of the account transaction.

poolrpc.BumpAccountFeeResponse

This message has no parameters.

poolrpc.CancelOrderRequest

Parameter Type Description
order_nonce bytes

poolrpc.CancelOrderResponse

This message has no parameters.

poolrpc.CloseAccountRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that will be closed.
output_with_fee OutputWithFee A single output/address to which the remaining funds of the account will be sent to at the specified fee. If an address is not specified, then the funds are sent to an address the backing lnd node controls.
outputs OutputsWithImplicitFee The outputs to which the remaining funds of the account will be sent to. This should only be used when wanting to create two or more outputs, otherwise OutputWithFee should be used instead. The fee of the account's closing transaction is implicitly defined by the combined value of all outputs.

poolrpc.CloseAccountResponse

Parameter Type Description
close_txid bytes The hash of the closing transaction.

poolrpc.DepositAccountRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that funds will be deposited into.
amount_sat uint64 The amount in satoshis to deposit into the account.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kw, to use for the deposit transaction.

poolrpc.DepositAccountResponse

Parameter Type Description
account Account The state of the account after processing the deposit.
deposit_txid bytes The transaction used to deposit funds into the account.

poolrpc.ExpectSidecarChannelRequest

Parameter Type Description
ticket string The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered".

poolrpc.ExpectSidecarChannelResponse

This message has no parameters.

poolrpc.GetInfoRequest

This message has no parameters.

poolrpc.GetInfoResponse

Parameter Type Description
version string The version of the Pool daemon that is running.
accounts_total uint32 The total number of accounts in the local database.
accounts_active uint32 The total number of accounts that are in an active, non-archived state, including expired accounts.
accounts_active_expired uint32 The total number of accounts that are active but have expired.
accounts_archived uint32 The total number of accounts that are in an archived/closed state.
orders_total uint32 The total number of orders in the local database.
orders_active uint32 The total number of active/pending orders that are still waiting for execution.
orders_archived uint32 The total number of orders that have been archived.
current_block_height uint32 The current block height as seen by the connected lnd node.
batches_involved uint32 The number of batches an account of this node was ever involved in.
node_rating NodeRating Our lnd node's rating as judged by the auctioneer server.
lsat_tokens uint32 The number of available LSAT tokens.
subscribed_to_auctioneer bool Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server.
new_nodes_only bool Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon.
market_info array MarketInfoEntry A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest.

poolrpc.GetInfoResponse.MarketInfoEntry

Parameter Type Description
key uint32
value MarketInfo

poolrpc.InitAccountRequest

Parameter Type Description
account_value uint64
absolute_height uint32
relative_height uint32
conf_target uint32 The target number of blocks that the transaction should be confirmed in.
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI).

poolrpc.Lease

Parameter Type Description
channel_point OutPoint The outpoint of the channel created.
channel_amt_sat uint64 The amount, in satoshis, of the channel created.
channel_duration_blocks uint32 The intended duration, in blocks, of the channel created.
channel_lease_expiry uint32 The absolute height that this channel lease expires.
premium_sat uint64 The premium, in satoshis, either paid or received for the offered liquidity.
execution_fee_sat uint64 The execution fee, in satoshis, charged by the auctioneer for the channel created.
chain_fee_sat uint64 The fee, in satoshis, charged by the auctioneer for the batch execution transaction that created this lease.
clearing_rate_price uint64 The actual fixed rate expressed in parts per billionth this lease was bought/sold at.
order_fixed_rate uint64 The actual fixed rate of the bid/ask, this should always be 'better' than the clearing_rate_price.
order_nonce bytes The order executed that resulted in the channel created.
matched_order_nonce bytes The unique identifier for the order that was matched with that resulted in the channel created.
purchased bool Whether this channel was purchased from another trader or not.
channel_remote_node_key bytes The pubkey of the node that this channel was bought/sold from.
channel_node_tier NodeTier The tier of the node that this channel was bought/sold from.
self_chan_balance uint64 The self channel balance that was pushed to the recipient.
sidecar_channel bool Whether the channel was leased as a sidecar channel (bid orders only).

poolrpc.LeaseDurationRequest

This message has no parameters.

poolrpc.LeaseDurationResponse

Parameter Type Description
lease_durations array LeaseDurationsEntry Deprecated, use lease_duration_buckets.
lease_duration_buckets array LeaseDurationBucketsEntry The set of lease durations the market is currently accepting and the state the duration buckets currently are in.

poolrpc.LeaseDurationResponse.LeaseDurationBucketsEntry

Parameter Type Description
key uint32
value DurationBucketState

poolrpc.LeaseDurationResponse.LeaseDurationsEntry

Parameter Type Description
key uint32
value bool

poolrpc.LeasesRequest

Parameter Type Description
batch_ids array bytes An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned.
accounts array bytes An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned.

poolrpc.LeasesResponse

Parameter Type Description
leases array Lease The relevant list of leases purchased or sold within the auction.
total_amt_earned_sat uint64 The total amount of satoshis earned from the leases returned.
total_amt_paid_sat uint64 The total amount of satoshis paid for the leases returned.

poolrpc.ListAccountsRequest

Parameter Type Description
active_only bool Only list accounts that are still active.

poolrpc.ListAccountsResponse

Parameter Type Description
accounts array Account

poolrpc.ListOrdersRequest

Parameter Type Description
verbose bool Can be set to true to list the orders including all events, which can be very verbose.
active_only bool Only list orders that are still active.

poolrpc.ListOrdersResponse

Parameter Type Description
asks array Ask
bids array Bid

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

poolrpc.MatchEvent

Parameter Type Description
match_state MatchState The state of the match making process the order went through.
units_filled uint32 The number of units that would be (or were) filled with this match.
matched_order bytes The nonce of the order we were matched to.
reject_reason MatchRejectReason The reason why the trader daemon rejected the order. Is only set if match_state is set to REJECTED.

poolrpc.NextBatchInfoRequest

This message has no parameters.

poolrpc.NextBatchInfoResponse

Parameter Type Description
conf_target uint32 The confirmation target the auctioneer will use for fee estimation of the next batch.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch.
clear_timestamp uint64 The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch.

poolrpc.NodeRatingRequest

Parameter Type Description
node_pubkeys array bytes The target node to obtain ratings information for.

poolrpc.NodeRatingResponse

Parameter Type Description
node_ratings array NodeRating A series of node ratings for each of the queried nodes.

poolrpc.OfferSidecarRequest

Parameter Type Description
auto_negotiate bool If false, then only the trader_key, unit, self_chan_balance, and lease_duration_blocks need to be set in the bid below. Otherwise, the fields as they're set when submitting a bid need to be filled in.
bid Bid The bid template that will be used to populate the initial sidecar ticket as well as auto negotiate the remainig steps of the sidecar channel if needed.

poolrpc.Order

Parameter Type Description
trader_key bytes The trader's account key of the account that is used for the order.
rate_fixed uint32 Fixed order rate in parts per billion.
amt uint64 Order amount in satoshis.
max_batch_fee_rate_sat_per_kw uint64 Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
order_nonce bytes Order nonce, acts as unique order identifier.
state OrderState The state the order currently is in.
units uint32 The number of order units the amount corresponds to.
units_unfulfilled uint32 The number of currently unfilled units of this order. This will be equal to the total amount of units until the order has reached the state PARTIAL_FILL or EXECUTED.
reserved_value_sat uint64 The value reserved from the account by this order to ensure the account can pay execution and chain fees in case it gets matched.
creation_timestamp_ns uint64 The unix timestamp in nanoseconds the order was first created/submitted.
events array OrderEvent A list of events that were emitted for this order. This field is only set when the verbose flag is set to true in the request.
min_units_match uint32 The minimum number of order units that must be matched per order pair.

poolrpc.OrderEvent

Parameter Type Description
timestamp_ns int64 The unix timestamp in nanoseconds the event was emitted at. This is the primary key of the event and is unique across the database.
event_str string The human readable representation of the event.
state_change UpdatedEvent The order was updated in the database.
matched MatchEvent The order was involved in a match making attempt.

poolrpc.Output

Parameter Type Description
value_sat uint64 The value, in satoshis, of the output.
address string The address corresponding to the output.

poolrpc.OutputWithFee

Parameter Type Description
address string The address corresponding to the output.
conf_target uint32 The target number of blocks that the transaction should be confirmed in.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kw, to use for the withdrawal transaction.

poolrpc.OutputsWithImplicitFee

Parameter Type Description
outputs array Output

poolrpc.QuoteAccountRequest

Parameter Type Description
account_value uint64
conf_target uint32 The target number of blocks that the transaction should be confirmed in.

poolrpc.QuoteAccountResponse

Parameter Type Description
miner_fee_rate_sat_per_kw uint64
miner_fee_total uint64

poolrpc.QuoteOrderRequest

Parameter Type Description
amt uint64 Order amount in satoshis.
rate_fixed uint32 Fixed order rate in parts per billion.
lease_duration_blocks uint32 Required number of blocks that a channel opened as a result of this bid should be kept open.
max_batch_fee_rate_sat_per_kw uint64 Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
min_units_match uint32 The minimum number of order units that must be matched per order pair.

poolrpc.QuoteOrderResponse

Parameter Type Description
total_premium_sat uint64 The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees.
rate_per_block double The fixed order rate expressed as a fraction instead of parts per billion.
rate_percent double The fixed order rate expressed as a percentage instead of parts per billion.
total_execution_fee_sat uint64 The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order.
worst_case_chain_fee_sat uint64 The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation).

poolrpc.RecoverAccountsRequest

This message has no parameters.

poolrpc.RecoverAccountsResponse

Parameter Type Description
num_recovered_accounts uint32 The number of accounts that were recovered.

poolrpc.RegisterSidecarRequest

Parameter Type Description
ticket string The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered".
auto_negotiate bool If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down.

poolrpc.RenewAccountRequest

Parameter Type Description
account_key bytes The key associated with the account to renew.
absolute_expiry uint32 The new absolute expiration height of the account.
relative_expiry uint32 The new relative expiration height of the account.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kw, to use for the renewal transaction.

poolrpc.RenewAccountResponse

Parameter Type Description
account Account The state of the account after processing the renewal.
renewal_txid bytes The transaction used to renew the expiration of the account.

poolrpc.SidecarTicket

Parameter Type Description
ticket string The complete sidecar ticket in its string encoded form which is base64 URL encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.

poolrpc.StopDaemonRequest

This message has no parameters.

poolrpc.StopDaemonResponse

This message has no parameters.

poolrpc.SubmitOrderRequest

Parameter Type Description
ask Ask
bid Bid
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI).

poolrpc.SubmitOrderResponse

Parameter Type Description
invalid_order InvalidOrder Order failed with the given reason.
accepted_order_nonce bytes The order nonce of the accepted order.

poolrpc.TokensRequest

This message has no parameters.

poolrpc.TokensResponse

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

poolrpc.UpdatedEvent

Parameter Type Description
previous_state OrderState The state of the order previous to the change. This is what the state changed from.
new_state OrderState The new state of the order after the change. This is what the state changed to.
units_filled uint32 The units that were filled at the time of the event.

poolrpc.WithdrawAccountRequest

Parameter Type Description
trader_key bytes The trader key associated with the account that funds will be withdrawed from.
outputs array Output The outputs we'll withdraw funds from the account into.
fee_rate_sat_per_kw uint64 The fee rate, in satoshis per kw, to use for the withdrawal transaction.

poolrpc.WithdrawAccountResponse

Parameter Type Description
account Account The state of the account after processing the withdrawal.
withdraw_txid bytes The transaction used to withdraw funds from the account.

gRPC Enums

AccountState

Name Value Description
PENDING_OPEN 0 The state of an account when it is pending its confirmation on-chain.
PENDING_UPDATE 1 The state of an account when it has undergone an update on-chain either as part of a matched order or a trader modification and it is pending its confirmation on-chain.
OPEN 2 The state of an account once it has confirmed on-chain.
EXPIRED 3 The state of an account once its expiration has been reached and its closing transaction has confirmed.
PENDING_CLOSED 4 The state of an account when we're waiting for the closing transaction of an account to confirm that required cooperation with the auctioneer.
CLOSED 5 The state of an account once its closing transaction has confirmed.
RECOVERY_FAILED 6 The state of an account that indicates that the account was attempted to be recovered but failed because the opening transaction wasn't found by lnd. This could be because it was never published or it never confirmed. Then the funds are SAFU and the account can be considered to never have been opened in the first place.
PENDING_BATCH 7 The account has recently participated in a batch and is not yet confirmed.

AuctionAccountState

Name Value Description
STATE_PENDING_OPEN 0 The account's funding transaction is not yet confirmed on-chain.
STATE_OPEN 1 The account is fully open and confirmed on-chain.
STATE_EXPIRED 2 The account is still open but the CLTV expiry has passed and the trader can close it without the auctioneer's key. Orders for accounts in this state won't be accepted.
STATE_PENDING_UPDATE 3 The account was modified by a deposit or withdrawal and is currently waiting for the modifying transaction to confirm.
STATE_CLOSED 4 The account is closed. The auctioneer doesn't track whether the closing transaction is already confirmed on-chain or not.
STATE_PENDING_BATCH 5 The account has recently participated in a batch and is not yet confirmed.

ChannelType

Name Value Description
TWEAKLESS 0 The channel supports static to_remote keys.
ANCHORS 1 The channel uses an anchor-based commitment.

DurationBucketState

Name Value Description
NO_MARKET 0 NO_MARKET indicates that this bucket doesn't actually exist, in that no market is present for this market.
MARKET_CLOSED 1 MARKET_CLOSED indicates that this market exists, but that it isn't currently running.
ACCEPTING_ORDERS 2 ACCEPTING_ORDERS indicates that we're accepting orders for this bucket, but not yet clearing for this duration.
MARKET_OPEN 3 MARKET_OPEN indicates that we're accepting orders, and fully clearing the market for this duration.

FailReason

Name Value Description
INVALID_AMT 0

NodeTier

Name Value Description
TIER_DEFAULT 0 The default node tier. This value will be determined at run-time by the current order version.
TIER_0 1 Tier 0, bid with this tier are opting out of the smaller "higher quality" pool of nodes to match their bids. Nodes in this tier are considered to have "no rating".
TIER_1 2 Tier 1, the "base" node tier. Nodes in this tier are shown to have a higher degree of up time and route-ability compared to the rest of the nodes in the network. This is the current default node tier when submitting bid orders.

RejectReason

Name Value Description
UNKNOWN 0 The reason cannot be mapped to a specific code.
SERVER_MISBEHAVIOR 1 The client didn't come up with the same result as the server and is rejecting the batch because of that.
BATCH_VERSION_MISMATCH 2 The client doesn't support the current batch verification version the server is using.
PARTIAL_REJECT 3 The client rejects some of the orders, not the full batch. When this code is set, the rejected_orders map must be set.

OrderRejectReason

Name Value Description
DUPLICATE_PEER 0 The trader's client has a preference to only match orders with peers it doesn't already have channels with. The order that is rejected with this reason type comes from a peer that the trader already has channels with.
CHANNEL_FUNDING_FAILED 1 The trader's client couldn't connect to the remote node of the matched order or the channel funding could not be initialized for another reason. This could also be the rejecting node's fault if their connection is not stable. Using this code can have a negative impact on the reputation score of both nodes, depending on the number of errors recorded.

OrderState

Name Value Description
ORDER_SUBMITTED 0
ORDER_CLEARED 1
ORDER_PARTIALLY_FILLED 2
ORDER_EXECUTED 3
ORDER_CANCELED 4
ORDER_EXPIRED 5
ORDER_FAILED 6

Error

Name Value Description
UNKNOWN 0 The error cannot be mapped to a specific code.
SERVER_SHUTDOWN 1 The server is shutting down for maintenance. Traders should close the long-lived stream/connection and try to connect again after some time.
ACCOUNT_DOES_NOT_EXIST 2 The account the trader tried to subscribe to does not exist in the auctioneer's database.
INCOMPLETE_ACCOUNT_RESERVATION 3 The account the trader tried to subscribe to was never completed and a reservation for it is still pending.

MatchRejectReason

Name Value Description
NONE 0 No reject occurred, this is the default value.
SERVER_MISBEHAVIOR 1 The client didn't come up with the same result as the server and is rejecting the batch because of that.
BATCH_VERSION_MISMATCH 2 The client doesn't support the current batch verification version the server is using.
PARTIAL_REJECT_COLLATERAL 3 The client rejects some of the orders, not the full batch. This reason is set on matches for orders that were in the same batch as partial reject ones but were not themselves rejected.
PARTIAL_REJECT_DUPLICATE_PEER 4 The trader's client has a preference to only match orders with peers it doesn't already have channels with. The order that is rejected with this reason type comes from a peer that the trader already has channels with.
PARTIAL_REJECT_CHANNEL_FUNDING_FAILED 5 The trader's client couldn't connect to the remote node of the matched order or the channel funding could not be initialized for another reason. This could also be the rejecting node's fault if their connection is not stable. Using this code can have a negative impact on the reputation score of both nodes, depending on the number of errors recorded.

MatchState

Name Value Description
PREPARE 0 The OrderMatchPrepare message from the auctioneer was received initially.
ACCEPTED 1 The OrderMatchPrepare message from the auctioneer was processed successfully and the batch was accepted.
REJECTED 2 The order was rejected by the trader daemon, either as an answer to a OrderMatchSignBegin or OrderMatchFinalize message from the auctioneer.
SIGNED 3 The OrderMatchSignBegin message from the auctioneer was processed successfully.
FINALIZED 4 The OrderMatchFinalize message from the auctioneer was processed successfully.

Pool REST API Reference

Welcome to the REST API reference documentation for Lightning Pool.

Lightning Pool is a non-custodial batched uniform clearing-price auction for Lightning Channel Lease (LCL). A LCL packages up inbound (or outbound!) channel liquidity (ability to send/receive funds) as a fixed incoming asset (earning interest over time) with a maturity date expressed in blocks. The maturity date of each of the channels is enforced by Bitcoin contracts, ensuring that the funds of the maker (the party that sold the channel) can't be swept until the maturity height. All cleared orders (purchased channels) are cleared in a single batched on-chain transaction.

This repository is home to the Pool client and depends on the Lightning Network daemon lnd. All of lnd’s supported chain backends are fully supported when using the Pool client: Neutrino, Bitcoin Core, and btcd.

The service can be used in various situations:

This site features the API documentation for shell script (CLI), Python and JavaScript clients in order to communicate with a local poold 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:

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

/v1/pool/accounts

$ curl -X GET http://localhost:8281/v1/pool/accounts
{ 
    "accounts": <array poolrpcAccount>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "accounts": <array poolrpcAccount>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/accounts',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "accounts": <array poolrpcAccount>, 
//  }

GET /v1/pool/accounts

pool: accounts list ListAccounts returns a list of all accounts known to the trader daemon and their current state.

Field Type Placement Description
active_only boolean query Only list accounts that are still active.

Response

Field Type Description
accounts array poolrpcAccount
$ curl -X DELETE http://localhost:8281/v1/pool/accounts
{ 
    "close_txid": <byte>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts'
>>> r = requests.delete(url, verify=cert_path)
>>> print(r.json())
{ 
    "close_txid": <byte>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/accounts',
  json: true
};
request.delete(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "close_txid": <byte>, 
//  }

DELETE /v1/pool/accounts

pool: accounts close CloseAccount closes an account and returns the funds locked in that account to the connected lnd node's wallet.

Field Type Placement Description
trader_key string query The trader key associated with the account that will be closed.
output_with_fee.address string query The address corresponding to the output.
output_with_fee.conf_target int64 query The target number of blocks that the transaction should be confirmed in.
output_with_fee.fee_rate_sat_per_kw string query The fee rate, in satoshis per kw, to use for the withdrawal transaction.

Response

Field Type Description
close_txid byte The hash of the closing transaction.
$ curl -X POST http://localhost:8281/v1/pool/accounts -d '{ \
    "account_value":<string>, \
    "absolute_height":<int64>, \
    "relative_height":<int64>, \
    "conf_target":<int64>, \
    "initiator":<string>, \
}'
{ 
    "trader_key": <byte>, 
    "outpoint": <poolrpcOutPoint>, 
    "value": <string>, 
    "available_balance": <string>, 
    "expiration_height": <int64>, 
    "state": <poolrpcAccountState>, 
    "latest_txid": <byte>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts'
>>> data = { 
        'account_value': <string>, 
        'absolute_height': <int64>, 
        'relative_height': <int64>, 
        'conf_target': <int64>, 
        'initiator': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "trader_key": <byte>, 
    "outpoint": <poolrpcOutPoint>, 
    "value": <string>, 
    "available_balance": <string>, 
    "expiration_height": <int64>, 
    "state": <poolrpcAccountState>, 
    "latest_txid": <byte>, 
}
const request = require('request');
let requestBody = { 
  account_value: <string>,
  absolute_height: <int64>,
  relative_height: <int64>,
  conf_target: <int64>,
  initiator: <string>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/accounts',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "trader_key": <byte>, 
//      "outpoint": <poolrpcOutPoint>, 
//      "value": <string>, 
//      "available_balance": <string>, 
//      "expiration_height": <int64>, 
//      "state": <poolrpcAccountState>, 
//      "latest_txid": <byte>, 
//  }

POST /v1/pool/accounts

pool: accounts new InitAccount creates a new account with the requested size and expiration, funding it from the wallet of the connected lnd node.

Field Type Placement Description
account_value string body
absolute_height int64 body
relative_height int64 body
conf_target int64 body The target number of blocks that the transaction should be confirmed in.
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI).

Response

Field Type Description
trader_key byte The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer.
outpoint poolrpcOutPoint The current outpoint associated with the account. This will change every time the account has been updated.
value string The current total amount of satoshis in the account.
available_balance string The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders.
expiration_height int64 The height at which the account will expire.
state poolrpcAccountState The current state of the account.
latest_txid byte The hash of the account's latest transaction.

/v1/pool/accounts/bump

$ curl -X POST http://localhost:8281/v1/pool/accounts/bump -d '{ \
    "trader_key":<byte>, \
    "fee_rate_sat_per_kw":<string>, \
}'
{ 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts/bump'
>>> data = { 
        'trader_key': base64.b64encode(<byte>).decode(), 
        'fee_rate_sat_per_kw': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
}
const request = require('request');
let requestBody = { 
  trader_key: <byte>,
  fee_rate_sat_per_kw: <string>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/accounts/bump',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//  }

POST /v1/pool/accounts/bump

pool: accounts bumpfee BumpAccountFee attempts to bump the fee of an account's transaction through child-pays-for-parent (CPFP). Since the CPFP is performed through the backing lnd node, the account transaction must contain an output under its control for a successful bump. If a CPFP has already been performed for an account, and this RPC is invoked again, then a replacing transaction (RBF) of the child will be broadcast.

Field Type Placement Description
trader_key byte body The trader key associated with the account that will have its fee bumped.
fee_rate_sat_per_kw string body The new fee rate, in satoshis per kw, to use for the child of the account transaction.

Response

This response has no parameters.

/v1/pool/accounts/deposit

$ curl -X POST http://localhost:8281/v1/pool/accounts/deposit -d '{ \
    "trader_key":<byte>, \
    "amount_sat":<string>, \
    "fee_rate_sat_per_kw":<string>, \
}'
{ 
    "account": <poolrpcAccount>, 
    "deposit_txid": <byte>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts/deposit'
>>> data = { 
        'trader_key': base64.b64encode(<byte>).decode(), 
        'amount_sat': <string>, 
        'fee_rate_sat_per_kw': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "account": <poolrpcAccount>, 
    "deposit_txid": <byte>, 
}
const request = require('request');
let requestBody = { 
  trader_key: <byte>,
  amount_sat: <string>,
  fee_rate_sat_per_kw: <string>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/accounts/deposit',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "account": <poolrpcAccount>, 
//      "deposit_txid": <byte>, 
//  }

POST /v1/pool/accounts/deposit

pool: accounts deposit DepositAccount adds more funds from the connected lnd node's wallet to an account.

Field Type Placement Description
trader_key byte body The trader key associated with the account that funds will be deposited into.
amount_sat string body The amount in satoshis to deposit into the account.
fee_rate_sat_per_kw string body The fee rate, in satoshis per kw, to use for the deposit transaction.

Response

Field Type Description
account poolrpcAccount The state of the account after processing the deposit.
deposit_txid byte The transaction used to deposit funds into the account.

/v1/pool/accounts/quote

$ curl -X POST http://localhost:8281/v1/pool/accounts/quote -d '{ \
    "account_value":<string>, \
    "conf_target":<int64>, \
}'
{ 
    "miner_fee_rate_sat_per_kw": <string>, 
    "miner_fee_total": <string>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts/quote'
>>> data = { 
        'account_value': <string>, 
        'conf_target': <int64>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "miner_fee_rate_sat_per_kw": <string>, 
    "miner_fee_total": <string>, 
}
const request = require('request');
let requestBody = { 
  account_value: <string>,
  conf_target: <int64>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/accounts/quote',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "miner_fee_rate_sat_per_kw": <string>, 
//      "miner_fee_total": <string>, 
//  }

POST /v1/pool/accounts/quote

QuoteAccount gets a fee quote to fund an account of the given size with the given confirmation target. If the connected lnd wallet doesn't have enough balance to fund an account of the requested size, an error is returned.

Field Type Placement Description
account_value string body
conf_target int64 body The target number of blocks that the transaction should be confirmed in.

Response

Field Type Description
miner_fee_rate_sat_per_kw string
miner_fee_total string

/v1/pool/accounts/recover

$ curl -X POST http://localhost:8281/v1/pool/accounts/recover -d '{ \
}'
{ 
    "num_recovered_accounts": <int64>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts/recover'
>>> data = { 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "num_recovered_accounts": <int64>, 
}
const request = require('request');
let requestBody = { 
};
let options = {
  url: 'http://localhost:8281/v1/pool/accounts/recover',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "num_recovered_accounts": <int64>, 
//  }

POST /v1/pool/accounts/recover

pool: accounts recover RecoverAccounts queries the auction server for this trader daemon's accounts in case we lost our local account database.

This request has no parameters.

Response

Field Type Description
num_recovered_accounts int64 The number of accounts that were recovered.

/v1/pool/accounts/renew

$ curl -X POST http://localhost:8281/v1/pool/accounts/renew -d '{ \
    "account_key":<byte>, \
    "absolute_expiry":<int64>, \
    "relative_expiry":<int64>, \
    "fee_rate_sat_per_kw":<string>, \
}'
{ 
    "account": <poolrpcAccount>, 
    "renewal_txid": <byte>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts/renew'
>>> data = { 
        'account_key': base64.b64encode(<byte>).decode(), 
        'absolute_expiry': <int64>, 
        'relative_expiry': <int64>, 
        'fee_rate_sat_per_kw': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "account": <poolrpcAccount>, 
    "renewal_txid": <byte>, 
}
const request = require('request');
let requestBody = { 
  account_key: <byte>,
  absolute_expiry: <int64>,
  relative_expiry: <int64>,
  fee_rate_sat_per_kw: <string>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/accounts/renew',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "account": <poolrpcAccount>, 
//      "renewal_txid": <byte>, 
//  }

POST /v1/pool/accounts/renew

pool: accounts renew RenewAccount renews the expiration of an account.

Field Type Placement Description
account_key byte body The key associated with the account to renew.
absolute_expiry int64 body The new absolute expiration height of the account.
relative_expiry int64 body The new relative expiration height of the account.
fee_rate_sat_per_kw string body The fee rate, in satoshis per kw, to use for the renewal transaction.

Response

Field Type Description
account poolrpcAccount The state of the account after processing the renewal.
renewal_txid byte The transaction used to renew the expiration of the account.

/v1/pool/accounts/withdraw

$ curl -X POST http://localhost:8281/v1/pool/accounts/withdraw -d '{ \
    "trader_key":<byte>, \
    "outputs":<array poolrpcOutput>, \
    "fee_rate_sat_per_kw":<string>, \
}'
{ 
    "account": <poolrpcAccount>, 
    "withdraw_txid": <byte>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/accounts/withdraw'
>>> data = { 
        'trader_key': base64.b64encode(<byte>).decode(), 
        'outputs': <array poolrpcOutput>, 
        'fee_rate_sat_per_kw': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "account": <poolrpcAccount>, 
    "withdraw_txid": <byte>, 
}
const request = require('request');
let requestBody = { 
  trader_key: <byte>,
  outputs: <array poolrpcOutput>,
  fee_rate_sat_per_kw: <string>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/accounts/withdraw',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "account": <poolrpcAccount>, 
//      "withdraw_txid": <byte>, 
//  }

POST /v1/pool/accounts/withdraw

pool: accounts withdraw WithdrawAccount splits off parts of the account balance into the specified outputs while recreating the account with a reduced balance.

Field Type Placement Description
trader_key byte body The trader key associated with the account that funds will be withdrawed from.
outputs array poolrpcOutput body The outputs we'll withdraw funds from the account into.
fee_rate_sat_per_kw string body The fee rate, in satoshis per kw, to use for the withdrawal transaction.

Response

Field Type Description
account poolrpcAccount The state of the account after processing the withdrawal.
withdraw_txid byte The transaction used to withdraw funds from the account.

/v1/pool/batch/next

$ curl -X GET http://localhost:8281/v1/pool/batch/next
{ 
    "conf_target": <int64>, 
    "fee_rate_sat_per_kw": <string>, 
    "clear_timestamp": <string>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/batch/next'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "conf_target": <int64>, 
    "fee_rate_sat_per_kw": <string>, 
    "clear_timestamp": <string>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/batch/next',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "conf_target": <int64>, 
//      "fee_rate_sat_per_kw": <string>, 
//      "clear_timestamp": <string>, 
//  }

GET /v1/pool/batch/next

pool: auction nextbatchinfo NextBatchInfo returns information about the next batch the auctioneer will perform.

This request has no parameters.

Response

Field Type Description
conf_target int64 The confirmation target the auctioneer will use for fee estimation of the next batch.
fee_rate_sat_per_kw string The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch.
clear_timestamp string The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch.

/v1/pool/batch/snapshot

$ curl -X GET http://localhost:8281/v1/pool/batch/snapshot
{ 
    "version": <int64>, 
    "batch_id": <byte>, 
    "prev_batch_id": <byte>, 
    "clearing_price_rate": <int64>, 
    "matched_orders": <array poolrpcMatchedOrderSnapshot>, 
    "batch_tx_id": <string>, 
    "batch_tx": <byte>, 
    "batch_tx_fee_rate_sat_per_kw": <string>, 
    "creation_timestamp_ns": <string>, 
    "matched_markets": <object>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/batch/snapshot'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "version": <int64>, 
    "batch_id": <byte>, 
    "prev_batch_id": <byte>, 
    "clearing_price_rate": <int64>, 
    "matched_orders": <array poolrpcMatchedOrderSnapshot>, 
    "batch_tx_id": <string>, 
    "batch_tx": <byte>, 
    "batch_tx_fee_rate_sat_per_kw": <string>, 
    "creation_timestamp_ns": <string>, 
    "matched_markets": <object>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/batch/snapshot',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "version": <int64>, 
//      "batch_id": <byte>, 
//      "prev_batch_id": <byte>, 
//      "clearing_price_rate": <int64>, 
//      "matched_orders": <array poolrpcMatchedOrderSnapshot>, 
//      "batch_tx_id": <string>, 
//      "batch_tx": <byte>, 
//      "batch_tx_fee_rate_sat_per_kw": <string>, 
//      "creation_timestamp_ns": <string>, 
//      "matched_markets": <object>, 
//  }

GET /v1/pool/batch/snapshot

pool: auction snapshot BatchSnapshot returns the snapshot of a past batch identified by its ID. If no ID is provided, the snapshot of the last finalized batch is returned. Deprecated, use BatchSnapshots instead.

Field Type Placement Description
batch_id string query The unique identifier of the batch encoded as a compressed pubkey.

Response

Field Type Description
version int64 The version of the batch.
batch_id byte The unique identifier of the batch.
prev_batch_id byte The unique identifier of the prior batch.
clearing_price_rate int64 Deprecated, use matched_markets.
matched_orders array poolrpcMatchedOrderSnapshot Deprecated, use matched_markets.
batch_tx_id string The txid of the batch transaction.
batch_tx byte The batch transaction including all witness data.
batch_tx_fee_rate_sat_per_kw string The fee rate, in satoshis per kiloweight, of the batch transaction.
creation_timestamp_ns string The unix timestamp in nanoseconds the batch was made.
matched_markets object Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.

/v1/pool/batch/snapshots

$ curl -X GET http://localhost:8281/v1/pool/batch/snapshots
{ 
    "batches": <array poolrpcBatchSnapshotResponse>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/batch/snapshots'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "batches": <array poolrpcBatchSnapshotResponse>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/batch/snapshots',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "batches": <array poolrpcBatchSnapshotResponse>, 
//  }

GET /v1/pool/batch/snapshots

pool: auction snapshot BatchSnapshots returns a list of batch snapshots starting at the start batch ID and going back through the history of batches, returning at most the number of specified batches. A maximum of 100 snapshots can be queried in one call. If no start batch ID is provided, the most recent finalized batch is used as the starting point to go back from.

Field Type Placement Description
start_batch_id string query The unique identifier of the first batch to return, encoded as a compressed pubkey. This represents the newest/most current batch to fetch. If this is empty or a zero batch ID, the most recent finalized batch is used as the starting point to go back from.
num_batches_back int64 query The number of batches to return at most, including the start batch.

Response

Field Type Description
batches array poolrpcBatchSnapshotResponse The list of batches requested.
$ curl -X GET http://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}
{ 
    "batches": <array poolrpcBatchSnapshotResponse>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "batches": <array poolrpcBatchSnapshotResponse>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "batches": <array poolrpcBatchSnapshotResponse>, 
//  }

GET /v1/pool/batch/snapshots/{start_batch_id}

pool: auction snapshot BatchSnapshots returns a list of batch snapshots starting at the start batch ID and going back through the history of batches, returning at most the number of specified batches. A maximum of 100 snapshots can be queried in one call. If no start batch ID is provided, the most recent finalized batch is used as the starting point to go back from.

Field Type Placement Description
start_batch_id string path The unique identifier of the first batch to return, encoded as a compressed pubkey. This represents the newest/most current batch to fetch. If this is empty or a zero batch ID, the most recent finalized batch is used as the starting point to go back from.
num_batches_back int64 query The number of batches to return at most, including the start batch.

Response

Field Type Description
batches array poolrpcBatchSnapshotResponse The list of batches requested.
$ curl -X GET http://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}
{ 
    "batches": <array poolrpcBatchSnapshotResponse>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "batches": <array poolrpcBatchSnapshotResponse>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "batches": <array poolrpcBatchSnapshotResponse>, 
//  }

GET /v1/pool/batch/snapshots/{start_batch_id}/{num_batches_back}

pool: auction snapshot BatchSnapshots returns a list of batch snapshots starting at the start batch ID and going back through the history of batches, returning at most the number of specified batches. A maximum of 100 snapshots can be queried in one call. If no start batch ID is provided, the most recent finalized batch is used as the starting point to go back from.

Field Type Placement Description
start_batch_id string path The unique identifier of the first batch to return, encoded as a compressed pubkey. This represents the newest/most current batch to fetch. If this is empty or a zero batch ID, the most recent finalized batch is used as the starting point to go back from.
num_batches_back int64 path The number of batches to return at most, including the start batch.

Response

Field Type Description
batches array poolrpcBatchSnapshotResponse The list of batches requested.

/v1/pool/fee

$ curl -X GET http://localhost:8281/v1/pool/fee
{ 
    "execution_fee": <poolrpcExecutionFee>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/fee'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "execution_fee": <poolrpcExecutionFee>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/fee',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "execution_fee": <poolrpcExecutionFee>, 
//  }

GET /v1/pool/fee

pool: auction fee AuctionFee returns the current auction order execution fee specified by the auction server.

This request has no parameters.

Response

Field Type Description
execution_fee poolrpcExecutionFee The execution fee charged per matched order.

/v1/pool/info

$ curl -X GET http://localhost:8281/v1/pool/info
{ 
    "version": <string>, 
    "accounts_total": <int64>, 
    "accounts_active": <int64>, 
    "accounts_active_expired": <int64>, 
    "accounts_archived": <int64>, 
    "orders_total": <int64>, 
    "orders_active": <int64>, 
    "orders_archived": <int64>, 
    "current_block_height": <int64>, 
    "batches_involved": <int64>, 
    "node_rating": <poolrpcNodeRating>, 
    "lsat_tokens": <int64>, 
    "subscribed_to_auctioneer": <boolean>, 
    "new_nodes_only": <boolean>, 
    "market_info": <object>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/info'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "version": <string>, 
    "accounts_total": <int64>, 
    "accounts_active": <int64>, 
    "accounts_active_expired": <int64>, 
    "accounts_archived": <int64>, 
    "orders_total": <int64>, 
    "orders_active": <int64>, 
    "orders_archived": <int64>, 
    "current_block_height": <int64>, 
    "batches_involved": <int64>, 
    "node_rating": <poolrpcNodeRating>, 
    "lsat_tokens": <int64>, 
    "subscribed_to_auctioneer": <boolean>, 
    "new_nodes_only": <boolean>, 
    "market_info": <object>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/info',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "version": <string>, 
//      "accounts_total": <int64>, 
//      "accounts_active": <int64>, 
//      "accounts_active_expired": <int64>, 
//      "accounts_archived": <int64>, 
//      "orders_total": <int64>, 
//      "orders_active": <int64>, 
//      "orders_archived": <int64>, 
//      "current_block_height": <int64>, 
//      "batches_involved": <int64>, 
//      "node_rating": <poolrpcNodeRating>, 
//      "lsat_tokens": <int64>, 
//      "subscribed_to_auctioneer": <boolean>, 
//      "new_nodes_only": <boolean>, 
//      "market_info": <object>, 
//  }

GET /v1/pool/info

pool: getinfo GetInfo returns general information about the state of the Pool trader daemon.

This request has no parameters.

Response

Field Type Description
version string The version of the Pool daemon that is running.
accounts_total int64 The total number of accounts in the local database.
accounts_active int64 The total number of accounts that are in an active, non-archived state, including expired accounts.
accounts_active_expired int64 The total number of accounts that are active but have expired.
accounts_archived int64 The total number of accounts that are in an archived/closed state.
orders_total int64 The total number of orders in the local database.
orders_active int64 The total number of active/pending orders that are still waiting for execution.
orders_archived int64 The total number of orders that have been archived.
current_block_height int64 The current block height as seen by the connected lnd node.
batches_involved int64 The number of batches an account of this node was ever involved in.
node_rating poolrpcNodeRating Our lnd node's rating as judged by the auctioneer server.
lsat_tokens int64 The number of available LSAT tokens.
subscribed_to_auctioneer boolean Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server.
new_nodes_only boolean Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon.
market_info object A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest.

/v1/pool/lease_durations

$ curl -X GET http://localhost:8281/v1/pool/lease_durations
{ 
    "lease_durations": <object>, 
    "lease_duration_buckets": <object>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/lease_durations'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "lease_durations": <object>, 
    "lease_duration_buckets": <object>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/lease_durations',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "lease_durations": <object>, 
//      "lease_duration_buckets": <object>, 
//  }

GET /v1/pool/lease_durations

pool: auction leasedurations LeaseDurations returns the current set of valid lease duration in the market as is, and also information w.r.t if the market is currently active.

This request has no parameters.

Response

Field Type Description
lease_durations object Deprecated, use lease_duration_buckets.
lease_duration_buckets object The set of lease durations the market is currently accepting and the state the duration buckets currently are in.

/v1/pool/leases

$ curl -X GET http://localhost:8281/v1/pool/leases
{ 
    "leases": <array poolrpcLease>, 
    "total_amt_earned_sat": <string>, 
    "total_amt_paid_sat": <string>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/leases'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "leases": <array poolrpcLease>, 
    "total_amt_earned_sat": <string>, 
    "total_amt_paid_sat": <string>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/leases',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "leases": <array poolrpcLease>, 
//      "total_amt_earned_sat": <string>, 
//      "total_amt_paid_sat": <string>, 
//  }

GET /v1/pool/leases

pool: auction leases Leases returns the list of channels that were either purchased or sold by the trader within the auction.

Field Type Placement Description
batch_ids array query An optional list of batches to retrieve the leases of. If empty, leases throughout all batches are returned.
accounts array query An optional list of accounts to retrieve the leases of. If empty, leases for all accounts are returned.

Response

Field Type Description
leases array poolrpcLease The relevant list of leases purchased or sold within the auction.
total_amt_earned_sat string The total amount of satoshis earned from the leases returned.
total_amt_paid_sat string The total amount of satoshis paid for the leases returned.

/v1/pool/lsat/tokens

$ curl -X GET http://localhost:8281/v1/pool/lsat/tokens
{ 
    "tokens": <array poolrpcLsatToken>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/lsat/tokens'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "tokens": <array poolrpcLsatToken>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/lsat/tokens',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "tokens": <array poolrpcLsatToken>, 
//  }

GET /v1/pool/lsat/tokens

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

This request has no parameters.

Response

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

/v1/pool/node_ratings

$ curl -X GET http://localhost:8281/v1/pool/node_ratings
{ 
    "node_ratings": <array poolrpcNodeRating>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/node_ratings'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "node_ratings": <array poolrpcNodeRating>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/node_ratings',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "node_ratings": <array poolrpcNodeRating>, 
//  }

GET /v1/pool/node_ratings

pool: auction ratings Returns the Node Tier information for this target Lightning node, and other related ranking information.

Field Type Placement Description
node_pubkeys array query The target node to obtain ratings information for.

Response

Field Type Description
node_ratings array poolrpcNodeRating A series of node ratings for each of the queried nodes.

/v1/pool/orders

$ curl -X GET http://localhost:8281/v1/pool/orders
{ 
    "asks": <array poolrpcAsk>, 
    "bids": <array poolrpcBid>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/orders'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{ 
    "asks": <array poolrpcAsk>, 
    "bids": <array poolrpcBid>, 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/orders',
  json: true
};
request.get(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "asks": <array poolrpcAsk>, 
//      "bids": <array poolrpcBid>, 
//  }

GET /v1/pool/orders

pool: orders list ListOrders returns a list of all active and archived orders that are currently known to the trader daemon.

Field Type Placement Description
verbose boolean query Can be set to true to list the orders including all events, which can be very verbose.
active_only boolean query Only list orders that are still active.

Response

Field Type Description
asks array poolrpcAsk
bids array poolrpcBid
$ curl -X POST http://localhost:8281/v1/pool/orders -d '{ \
    "ask":<poolrpcAsk>, \
    "bid":<poolrpcBid>, \
    "initiator":<string>, \
}'
{ 
    "invalid_order": <poolrpcInvalidOrder>, 
    "accepted_order_nonce": <byte>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/orders'
>>> data = { 
        'ask': <poolrpcAsk>, 
        'bid': <poolrpcBid>, 
        'initiator': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "invalid_order": <poolrpcInvalidOrder>, 
    "accepted_order_nonce": <byte>, 
}
const request = require('request');
let requestBody = { 
  ask: <poolrpcAsk>,
  bid: <poolrpcBid>,
  initiator: <string>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/orders',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "invalid_order": <poolrpcInvalidOrder>, 
//      "accepted_order_nonce": <byte>, 
//  }

POST /v1/pool/orders

pool: orders submit SubmitOrder creates a new ask or bid order and submits for the given account and submits it to the auction server for matching.

Field Type Placement Description
ask poolrpcAsk body
bid poolrpcBid body
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI).

Response

Field Type Description
invalid_order poolrpcInvalidOrder Order failed with the given reason.
accepted_order_nonce byte The order nonce of the accepted order.
$ curl -X DELETE http://localhost:8281/v1/pool/orders/{order_nonce}
{ 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/orders/{order_nonce}'
>>> r = requests.delete(url, verify=cert_path)
>>> print(r.json())
{ 
}
const request = require('request');
let options = {
  url: 'http://localhost:8281/v1/pool/orders/{order_nonce}',
  json: true
};
request.delete(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//  }

DELETE /v1/pool/orders/{order_nonce}

pool: orders cancel CancelOrder cancels an active order with the auction server to remove it from future matching.

Field Type Placement Description
order_nonce string path

Response

This response has no parameters.

/v1/pool/orders/quote

$ curl -X POST http://localhost:8281/v1/pool/orders/quote -d '{ \
    "amt":<string>, \
    "rate_fixed":<int64>, \
    "lease_duration_blocks":<int64>, \
    "max_batch_fee_rate_sat_per_kw":<string>, \
    "min_units_match":<int64>, \
}'
{ 
    "total_premium_sat": <string>, 
    "rate_per_block": <double>, 
    "rate_percent": <double>, 
    "total_execution_fee_sat": <string>, 
    "worst_case_chain_fee_sat": <string>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/orders/quote'
>>> data = { 
        'amt': <string>, 
        'rate_fixed': <int64>, 
        'lease_duration_blocks': <int64>, 
        'max_batch_fee_rate_sat_per_kw': <string>, 
        'min_units_match': <int64>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "total_premium_sat": <string>, 
    "rate_per_block": <double>, 
    "rate_percent": <double>, 
    "total_execution_fee_sat": <string>, 
    "worst_case_chain_fee_sat": <string>, 
}
const request = require('request');
let requestBody = { 
  amt: <string>,
  rate_fixed: <int64>,
  lease_duration_blocks: <int64>,
  max_batch_fee_rate_sat_per_kw: <string>,
  min_units_match: <int64>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/orders/quote',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "total_premium_sat": <string>, 
//      "rate_per_block": <double>, 
//      "rate_percent": <double>, 
//      "total_execution_fee_sat": <string>, 
//      "worst_case_chain_fee_sat": <string>, 
//  }

POST /v1/pool/orders/quote

QuoteOrder calculates the premium, execution fees and max batch fee rate for an order based on the given order parameters.

Field Type Placement Description
amt string body Order amount in satoshis.
rate_fixed int64 body Fixed order rate in parts per billion.
lease_duration_blocks int64 body Required number of blocks that a channel opened as a result of this bid should be kept open.
max_batch_fee_rate_sat_per_kw string body Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
min_units_match int64 body The minimum number of order units that must be matched per order pair.

Response

Field Type Description
total_premium_sat string The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees.
rate_per_block double The fixed order rate expressed as a fraction instead of parts per billion.
rate_percent double The fixed order rate expressed as a percentage instead of parts per billion.
total_execution_fee_sat string The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order.
worst_case_chain_fee_sat string The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation).

/v1/pool/sidecar/expect

$ curl -X POST http://localhost:8281/v1/pool/sidecar/expect -d '{ \
    "ticket":<string>, \
}'
{ 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/sidecar/expect'
>>> data = { 
        'ticket': <string>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
}
const request = require('request');
let requestBody = { 
  ticket: <string>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/sidecar/expect',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//  }

POST /v1/pool/sidecar/expect

pool: sidecar expectchannel ExpectSidecarChannel is step 4/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the recipient once the provider has submitted the bid order for the sidecar channel. From this point onwards the Pool trader daemon of both the provider as well as the recipient need to be online to receive and react to match making events from the server.

Field Type Placement Description
ticket string body The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered".

Response

This response has no parameters.

/v1/pool/sidecar/offer

$ curl -X POST http://localhost:8281/v1/pool/sidecar/offer -d '{ \
    "auto_negotiate":<boolean>, \
    "bid":<poolrpcBid>, \
}'
{ 
    "ticket": <string>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/sidecar/offer'
>>> data = { 
        'auto_negotiate': <boolean>, 
        'bid': <poolrpcBid>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "ticket": <string>, 
}
const request = require('request');
let requestBody = { 
  auto_negotiate: <boolean>,
  bid: <poolrpcBid>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/sidecar/offer',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "ticket": <string>, 
//  }

POST /v1/pool/sidecar/offer

pool: sidecar offer OfferSidecar is step 1/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the provider. The result is a sidecar ticket with an offer to lease a sidecar channel for the recipient. The offer will be signed with the provider's lnd node public key. The ticket returned by this call will have the state "offered".

Field Type Placement Description
auto_negotiate boolean body If false, then only the trader_key, unit, self_chan_balance, and lease_duration_blocks need to be set in the bid below. Otherwise, the fields as they're set when submitting a bid need to be filled in.
bid poolrpcBid body The bid template that will be used to populate the initial sidecar ticket as well as auto negotiate the remainig steps of the sidecar channel if needed.

Response

Field Type Description
ticket string The complete sidecar ticket in its string encoded form which is base64 URL encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.

/v1/pool/sidecar/register

$ curl -X POST http://localhost:8281/v1/pool/sidecar/register -d '{ \
    "ticket":<string>, \
    "auto_negotiate":<boolean>, \
}'
{ 
    "ticket": <string>, 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/sidecar/register'
>>> data = { 
        'ticket': <string>, 
        'auto_negotiate': <boolean>, 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
    "ticket": <string>, 
}
const request = require('request');
let requestBody = { 
  ticket: <string>,
  auto_negotiate: <boolean>,
};
let options = {
  url: 'http://localhost:8281/v1/pool/sidecar/register',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//      "ticket": <string>, 
//  }

POST /v1/pool/sidecar/register

pool: sidecar register RegisterSidecarRequest is step 2/4 of the sidecar negotiation between the provider (the trader submitting the bid order) and the recipient (the trader receiving the sidecar channel). This step must be run by the recipient. The result is a sidecar ticket with the recipient's node information and channel funding multisig pubkey filled in. The ticket returned by this call will have the state "registered".

Field Type Placement Description
ticket string body The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered".
auto_negotiate boolean body If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down.

Response

Field Type Description
ticket string The complete sidecar ticket in its string encoded form which is base64 URL encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.

/v1/pool/stop

$ curl -X POST http://localhost:8281/v1/pool/stop -d '{ \
}'
{ 
}
>>> import base64, json, requests
>>> url = 'http://localhost:8281/v1/pool/stop'
>>> data = { 
    }
>>> r = requests.post(url, verify=cert_path, data=json.dumps(data))
>>> print(r.json())
{ 
}
const request = require('request');
let requestBody = { 
};
let options = {
  url: 'http://localhost:8281/v1/pool/stop',
  json: true,
  form: JSON.stringify(requestBody)
};
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  { 
//  }

POST /v1/pool/stop

pool: stop Stop gracefully shuts down the Pool trader daemon.

This request has no parameters.

Response

This response has no parameters.

REST Messages

MarketInfoTierValue

Field Type Description
tier poolrpcNodeTier
value int64

gatewayruntimeError

Field Type Description
error string
code int32
message string
details array protobufAny

poolrpcAccount

Field Type Description
trader_key byte The identifying component of an account. This is the key used for the trader in the 2-of-2 multi-sig construction of an account with an auctioneer.
outpoint poolrpcOutPoint The current outpoint associated with the account. This will change every time the account has been updated.
value string The current total amount of satoshis in the account.
available_balance string The amount of satoshis in the account that is available, meaning not allocated to any oustanding orders.
expiration_height int64 The height at which the account will expire.
state poolrpcAccountState The current state of the account.
latest_txid byte The hash of the account's latest transaction.

poolrpcAsk

Field Type Description
details poolrpcOrder The common fields shared between both ask and bid order types.
lease_duration_blocks int64 The number of blocks the liquidity provider is willing to provide the channel funds for.
version int64 The version of the order format that is used. Will be increased once new features are added.

poolrpcAskSnapshot

Field Type Description
version int64 The version of the order.
lease_duration_blocks int64 The period of time the channel will survive for.
rate_fixed int64 The true bid price of the order in parts per billion.
chan_type int64 The channel type to be created.

poolrpcAuctionFeeResponse

Field Type Description
execution_fee poolrpcExecutionFee The execution fee charged per matched order.

poolrpcBatchSnapshotResponse

Field Type Description
version int64 The version of the batch.
batch_id byte The unique identifier of the batch.
prev_batch_id byte The unique identifier of the prior batch.
clearing_price_rate int64 Deprecated, use matched_markets.
matched_orders array poolrpcMatchedOrderSnapshot Deprecated, use matched_markets.
batch_tx_id string The txid of the batch transaction.
batch_tx byte The batch transaction including all witness data.
batch_tx_fee_rate_sat_per_kw string The fee rate, in satoshis per kiloweight, of the batch transaction.
creation_timestamp_ns string The unix timestamp in nanoseconds the batch was made.
matched_markets object Maps the distinct lease duration markets to the orders that were matched within and the discovered market clearing price.

poolrpcBatchSnapshotsResponse

Field Type Description
batches array poolrpcBatchSnapshotResponse The list of batches requested.

poolrpcBid

Field Type Description
details poolrpcOrder The common fields shared between both ask and bid order types.
lease_duration_blocks int64 Required number of blocks that a channel opened as a result of this bid should be kept open.
version int64 The version of the order format that is used. Will be increased once new features are added.
min_node_tier poolrpcNodeTier The minimum node tier this order should be matched with. Only asks backed by a node this tier or higher will be eligible for matching with this bid.
self_chan_balance string Give the incoming channel that results from this bid being matched an initial outbound balance by adding additional funds from the taker's account into the channel. As a simplification for the execution protocol and the channel reserve calculations, the self_chan_balance can be at most the same as the order amount and the min_chan_amt must be set to the full order amount.
sidecar_ticket string If this bid order is meant to lease a channel for another node (which is dubbed a "sidecar channel") then this ticket contains all information required for setting up that sidecar channel. The ticket is expected to be the base64 encoded ticket, including the prefix and the checksum.

poolrpcBidSnapshot

Field Type Description
version int64 The version of the order.
lease_duration_blocks int64 The period of time the matched channel should be allocated for.
rate_fixed int64 The true bid price of the order in parts per billion.
chan_type int64 The channel type to be created.

poolrpcBumpAccountFeeRequest

Field Type Description
trader_key byte The trader key associated with the account that will have its fee bumped.
fee_rate_sat_per_kw string The new fee rate, in satoshis per kw, to use for the child of the account transaction.

poolrpcBumpAccountFeeResponse

This property has no parameters.

poolrpcCancelOrderResponse

This property has no parameters.

poolrpcCloseAccountResponse

Field Type Description
close_txid byte The hash of the closing transaction.

poolrpcDepositAccountRequest

Field Type Description
trader_key byte The trader key associated with the account that funds will be deposited into.
amount_sat string The amount in satoshis to deposit into the account.
fee_rate_sat_per_kw string The fee rate, in satoshis per kw, to use for the deposit transaction.

poolrpcDepositAccountResponse

Field Type Description
account poolrpcAccount The state of the account after processing the deposit.
deposit_txid byte The transaction used to deposit funds into the account.

poolrpcExecutionFee

Field Type Description
base_fee string The base fee in satoshis charged per order, regardless of the matched size.
fee_rate string The fee rate in parts per million.

poolrpcExpectSidecarChannelRequest

Field Type Description
ticket string The sidecar ticket to expect an incoming channel for. The ticket must be in the state "ordered".

poolrpcExpectSidecarChannelResponse

This property has no parameters.

poolrpcGetInfoResponse

Field Type Description
version string The version of the Pool daemon that is running.
accounts_total int64 The total number of accounts in the local database.
accounts_active int64 The total number of accounts that are in an active, non-archived state, including expired accounts.
accounts_active_expired int64 The total number of accounts that are active but have expired.
accounts_archived int64 The total number of accounts that are in an archived/closed state.
orders_total int64 The total number of orders in the local database.
orders_active int64 The total number of active/pending orders that are still waiting for execution.
orders_archived int64 The total number of orders that have been archived.
current_block_height int64 The current block height as seen by the connected lnd node.
batches_involved int64 The number of batches an account of this node was ever involved in.
node_rating poolrpcNodeRating Our lnd node's rating as judged by the auctioneer server.
lsat_tokens int64 The number of available LSAT tokens.
subscribed_to_auctioneer boolean Indicates whether there is an active subscription connection to the auctioneer. This will never be true if there is no active account. If there are active accounts, this value represents the network connection status to the auctioneer server.
new_nodes_only boolean Indicates whether the global --newnodesonly command line flag or newnodesonly=true configuration parameter was set on the Pool trader daemon.
market_info object A map of all markets identified by their lease duration and the current set of statistics such as number of open orders and total units of open interest.

poolrpcInitAccountRequest

Field Type Description
account_value string
absolute_height int64
relative_height int64
conf_target int64 The target number of blocks that the transaction should be confirmed in.
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for opening the account (pool CLI, LiT UI, other 3rd party UI).

poolrpcInvalidOrder

Field Type Description
order_nonce byte
fail_reason InvalidOrderFailReason
fail_string string

poolrpcLease

Field Type Description
channel_point poolrpcOutPoint The outpoint of the channel created.
channel_amt_sat string The amount, in satoshis, of the channel created.
channel_duration_blocks int64 The intended duration, in blocks, of the channel created.
channel_lease_expiry int64 The absolute height that this channel lease expires.
premium_sat string The premium, in satoshis, either paid or received for the offered liquidity.
execution_fee_sat string The execution fee, in satoshis, charged by the auctioneer for the channel created.
chain_fee_sat string The fee, in satoshis, charged by the auctioneer for the batch execution transaction that created this lease.
clearing_rate_price string The actual fixed rate expressed in parts per billionth this lease was bought/sold at.
order_fixed_rate string The actual fixed rate of the bid/ask, this should always be 'better' than the clearing_rate_price.
order_nonce byte The order executed that resulted in the channel created.
matched_order_nonce byte The unique identifier for the order that was matched with that resulted in the channel created.
purchased boolean Whether this channel was purchased from another trader or not.
channel_remote_node_key byte The pubkey of the node that this channel was bought/sold from.
channel_node_tier poolrpcNodeTier The tier of the node that this channel was bought/sold from.
self_chan_balance string The self channel balance that was pushed to the recipient.
sidecar_channel boolean Whether the channel was leased as a sidecar channel (bid orders only).

poolrpcLeaseDurationResponse

Field Type Description
lease_durations object Deprecated, use lease_duration_buckets.
lease_duration_buckets object The set of lease durations the market is currently accepting and the state the duration buckets currently are in.

poolrpcLeasesResponse

Field Type Description
leases array poolrpcLease The relevant list of leases purchased or sold within the auction.
total_amt_earned_sat string The total amount of satoshis earned from the leases returned.
total_amt_paid_sat string The total amount of satoshis paid for the leases returned.

poolrpcListAccountsResponse

Field Type Description
accounts array poolrpcAccount

poolrpcListOrdersResponse

Field Type Description
asks array poolrpcAsk
bids array poolrpcBid

poolrpcLsatToken

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.

poolrpcMarketInfo

Field Type Description
num_asks array MarketInfoTierValue The number of open/pending ask orders per node tier.
num_bids array MarketInfoTierValue The number of open/pending bid orders per node tier.
ask_open_interest_units array MarketInfoTierValue The total number of open/unmatched units in open/pending ask orders per node tier.
bid_open_interest_units array MarketInfoTierValue The total number of open/unmatched units in open/pending bid orders per node tier.

poolrpcMatchEvent

Field Type Description
match_state poolrpcMatchState The state of the match making process the order went through.
units_filled int64 The number of units that would be (or were) filled with this match.
matched_order byte The nonce of the order we were matched to.
reject_reason poolrpcMatchRejectReason The reason why the trader daemon rejected the order. Is only set if match_state is set to REJECTED.

poolrpcMatchedMarketSnapshot

Field Type Description
matched_orders array poolrpcMatchedOrderSnapshot The set of all orders matched in the batch.
clearing_price_rate int64 The uniform clearing price rate in parts per billion that was used for this batch.

poolrpcMatchedOrderSnapshot

Field Type Description
ask poolrpcAskSnapshot The full ask order that was matched.
bid poolrpcBidSnapshot The full bid order that was matched.
matching_rate int64 The fixed rate premium that was matched, expressed in parts-ber-billion.
total_sats_cleared string The total number of satoshis that were bought.
units_matched int64 The total number of units that were matched.

poolrpcNextBatchInfoResponse

Field Type Description
conf_target int64 The confirmation target the auctioneer will use for fee estimation of the next batch.
fee_rate_sat_per_kw string The fee rate, in satoshis per kiloweight, estimated by the auctioneer to use for the next batch.
clear_timestamp string The absolute unix timestamp in seconds at which the auctioneer will attempt to clear the next batch.

poolrpcNodeRating

Field Type Description
node_pubkey byte The pubkey for the node these ratings belong to.
node_tier poolrpcNodeTier The tier of the target node.

poolrpcNodeRatingResponse

Field Type Description
node_ratings array poolrpcNodeRating A series of node ratings for each of the queried nodes.

poolrpcOfferSidecarRequest

Field Type Description
auto_negotiate boolean If false, then only the trader_key, unit, self_chan_balance, and lease_duration_blocks need to be set in the bid below. Otherwise, the fields as they're set when submitting a bid need to be filled in.
bid poolrpcBid The bid template that will be used to populate the initial sidecar ticket as well as auto negotiate the remainig steps of the sidecar channel if needed.

poolrpcOrder

Field Type Description
trader_key byte The trader's account key of the account that is used for the order.
rate_fixed int64 Fixed order rate in parts per billion.
amt string Order amount in satoshis.
max_batch_fee_rate_sat_per_kw string Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
order_nonce byte Order nonce, acts as unique order identifier.
state poolrpcOrderState The state the order currently is in.
units int64 The number of order units the amount corresponds to.
units_unfulfilled int64 The number of currently unfilled units of this order. This will be equal to the total amount of units until the order has reached the state PARTIAL_FILL or EXECUTED.
reserved_value_sat string The value reserved from the account by this order to ensure the account can pay execution and chain fees in case it gets matched.
creation_timestamp_ns string The unix timestamp in nanoseconds the order was first created/submitted.
events array poolrpcOrderEvent A list of events that were emitted for this order. This field is only set when the verbose flag is set to true in the request.
min_units_match int64 The minimum number of order units that must be matched per order pair.

poolrpcOrderEvent

Field Type Description
timestamp_ns string The unix timestamp in nanoseconds the event was emitted at. This is the primary key of the event and is unique across the database.
event_str string The human readable representation of the event.
state_change poolrpcUpdatedEvent The order was updated in the database.
matched poolrpcMatchEvent The order was involved in a match making attempt.

poolrpcOutPoint

Field Type Description
txid byte Raw bytes representing the transaction id.
output_index int64 The index of the output on the transaction.

poolrpcOutput

Field Type Description
value_sat string The value, in satoshis, of the output.
address string The address corresponding to the output.

poolrpcOutputWithFee

Field Type Description
address string The address corresponding to the output.
conf_target int64 The target number of blocks that the transaction should be confirmed in.
fee_rate_sat_per_kw string The fee rate, in satoshis per kw, to use for the withdrawal transaction.

poolrpcOutputsWithImplicitFee

Field Type Description
outputs array poolrpcOutput

poolrpcQuoteAccountRequest

Field Type Description
account_value string
conf_target int64 The target number of blocks that the transaction should be confirmed in.

poolrpcQuoteAccountResponse

Field Type Description
miner_fee_rate_sat_per_kw string
miner_fee_total string

poolrpcQuoteOrderRequest

Field Type Description
amt string Order amount in satoshis.
rate_fixed int64 Fixed order rate in parts per billion.
lease_duration_blocks int64 Required number of blocks that a channel opened as a result of this bid should be kept open.
max_batch_fee_rate_sat_per_kw string Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).
min_units_match int64 The minimum number of order units that must be matched per order pair.

poolrpcQuoteOrderResponse

Field Type Description
total_premium_sat string The total order premium in satoshis for filling the entire order. This represents the interest amount paid to the maker by the taker excluding any execution or chain fees.
rate_per_block double The fixed order rate expressed as a fraction instead of parts per billion.
rate_percent double The fixed order rate expressed as a percentage instead of parts per billion.
total_execution_fee_sat string The total execution fee in satoshis that needs to be paid to the auctioneer for executing the entire order.
worst_case_chain_fee_sat string The worst case chain fees that need to be paid if fee rates spike up to the max_batch_fee_rate_sat_per_kw value specified in the request. This value is highly dependent on the min_units_match parameter as well since the calculation assumes chain fees for the chain footprint of opening amt/min_units_match channels (hence worst case calculation).

poolrpcRecoverAccountsRequest

This property has no parameters.

poolrpcRecoverAccountsResponse

Field Type Description
num_recovered_accounts int64 The number of accounts that were recovered.

poolrpcRegisterSidecarRequest

Field Type Description
ticket string The sidecar ticket to register and add the node and channel funding information to. The ticket must be in the state "offered".
auto_negotiate boolean If this value is True, then the daemon will attempt to finish negotiating the details of the sidecar channel automatically in the background. The progress of the ticket can be monitored using the SidecarState RPC. In addition, if this flag is set, then this method will block until the sidecar negotiation either finishes or breaks down.

poolrpcRenewAccountRequest

Field Type Description
account_key byte The key associated with the account to renew.
absolute_expiry int64 The new absolute expiration height of the account.
relative_expiry int64 The new relative expiration height of the account.
fee_rate_sat_per_kw string The fee rate, in satoshis per kw, to use for the renewal transaction.

poolrpcRenewAccountResponse

Field Type Description
account poolrpcAccount The state of the account after processing the renewal.
renewal_txid byte The transaction used to renew the expiration of the account.

poolrpcSidecarTicket

Field Type Description
ticket string The complete sidecar ticket in its string encoded form which is base64 URL encoded, has a human readable prefix ('sidecar...') and a checksum built in. The string encoded version will only be used on the trader side of the API. All requests to the auctioneer expect the ticket to be in its raw, tlv encoded byte form.

poolrpcStopDaemonRequest

This property has no parameters.

poolrpcStopDaemonResponse

This property has no parameters.

poolrpcSubmitOrderRequest

Field Type Description
ask poolrpcAsk
bid poolrpcBid
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 pool. This initiator part is meant for user interfaces to add their name to give the full picture of the binary used (poold, LiT) and the method used for submitting the order (pool CLI, LiT UI, other 3rd party UI).

poolrpcSubmitOrderResponse

Field Type Description
invalid_order poolrpcInvalidOrder Order failed with the given reason.
accepted_order_nonce byte The order nonce of the accepted order.

poolrpcTokensResponse

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

poolrpcUpdatedEvent

Field Type Description
previous_state poolrpcOrderState The state of the order previous to the change. This is what the state changed from.
new_state poolrpcOrderState The new state of the order after the change. This is what the state changed to.
units_filled int64 The units that were filled at the time of the event.

poolrpcWithdrawAccountRequest

Field Type Description
trader_key byte The trader key associated with the account that funds will be withdrawed from.
outputs array poolrpcOutput The outputs we'll withdraw funds from the account into.
fee_rate_sat_per_kw string The fee rate, in satoshis per kw, to use for the withdrawal transaction.

poolrpcWithdrawAccountResponse

Field Type Description
account poolrpcAccount The state of the account after processing the withdrawal.
withdraw_txid byte The transaction used to withdraw funds from the account.

protobufAny

Field Type Description
type_url string
value byte

REST Enums

InvalidOrderFailReason

Name Value Description
INVALID_AMT 0

poolrpcAccountState

Name Value Description
PENDING_OPEN 0
PENDING_UPDATE 1
OPEN 2
EXPIRED 3
PENDING_CLOSED 4
CLOSED 5
RECOVERY_FAILED 6
PENDING_BATCH 7

poolrpcDurationBucketState

Name Value Description
NO_MARKET 0
MARKET_CLOSED 1
ACCEPTING_ORDERS 2
MARKET_OPEN 3

poolrpcMatchRejectReason

Name Value Description
NONE 0
SERVER_MISBEHAVIOR 1
BATCH_VERSION_MISMATCH 2
PARTIAL_REJECT_COLLATERAL 3
PARTIAL_REJECT_DUPLICATE_PEER 4
PARTIAL_REJECT_CHANNEL_FUNDING_FAILED 5

poolrpcMatchState

Name Value Description
PREPARE 0
ACCEPTED 1
REJECTED 2
SIGNED 3
FINALIZED 4

poolrpcNodeTier

Name Value Description
TIER_DEFAULT 0
TIER_0 1
TIER_1 2

poolrpcOrderState

Name Value Description
ORDER_SUBMITTED 0
ORDER_CLEARED 1
ORDER_PARTIALLY_FILLED 2
ORDER_EXECUTED 3
ORDER_CANCELED 4
ORDER_EXPIRED 5
ORDER_FAILED 6

Other API References

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