SubmitOrder

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

Source: poolrpc/trader.proto

gRPC

rpc SubmitOrder (SubmitOrderRequest) returns (SubmitOrderResponse);

REST

HTTP Method	Path
POST	/v1/pool/orders

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:12010'
const MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
const TLS_PATH = 'POOL_DIR/tls.cert'

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;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
const macaroon = fs.readFileSync(MACAROON_PATH).toString('hex');
const macaroonCreds = grpc.credentials.createFromMetadataGenerator(function(args, callback) {
  let metadata = new grpc.Metadata();
  metadata.add('macaroon', macaroon);
  callback(null, metadata);
});
let creds = grpc.credentials.combineChannelCredentials(sslCreds, macaroonCreds);
let client = new poolrpc.Trader(GRPC_HOST, creds);
let request = {
  ask: <Ask>,
  bid: <Bid>,
  initiator: <string>,
};
client.submitOrder(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "invalid_order": <InvalidOrder>,
//    "accepted_order_nonce": <bytes>,
//    "updated_sidecar_ticket": <string>,
//  }

Python

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

GRPC_HOST = 'localhost:12010'
MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
TLS_PATH = 'POOL_DIR/tls.cert'

# create macaroon credentials
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
def metadata_callback(context, callback):
  callback([('macaroon', macaroon)], None)
auth_creds = grpc.metadata_call_credentials(metadata_callback)
# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# combine macaroon and SSL credentials
combined_creds = grpc.composite_channel_credentials(ssl_creds, auth_creds)
# make the request
channel = grpc.secure_channel(GRPC_HOST, combined_creds)
stub = traderstub.TraderStub(channel)
request = poolrpc.SubmitOrderRequest(
  ask=<Ask>,
  bid=<Bid>,
  initiator=<string>,
)
response = stub.SubmitOrder(request)
print(response)
# {
#    "invalid_order": <InvalidOrder>,
#    "accepted_order_nonce": <bytes>,
#    "updated_sidecar_ticket": <string>,
# }

REST

Javascript

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

const REST_HOST = 'localhost:8281'
const MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'

let requestBody = {
  ask: <object>, // <Ask> 
  bid: <object>, // <Bid> 
  initiator: <string>, // <string> 
};
let options = {
  url: `https://${REST_HOST}/v1/pool/orders`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  headers: {
    'Grpc-Metadata-macaroon': fs.readFileSync(MACAROON_PATH).toString('hex'),
  },
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//    "invalid_order": <object>, // <InvalidOrder> 
//    "accepted_order_nonce": <string>, // <bytes> 
//    "updated_sidecar_ticket": <string>, // <string> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8281'
MACAROON_PATH = 'POOL_DIR/regtest/pool.macaroon'
TLS_PATH = 'POOL_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/pool/orders'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'ask': <Ask>,
  'bid': <Bid>,
  'initiator': <string>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "invalid_order": <InvalidOrder>,
#    "accepted_order_nonce": <bytes>,
#    "updated_sidecar_ticket": <string>,
# }

Shell

$ pool orders submit --help

NAME:
   pool orders submit - 
        Submit a new order in the given market. Currently, Pool supports two
        types of orders: asks, and bids. In Pool, market participants buy/sell 
        liquidity in _units_. A unit is 100,000 satoshis.

        In the *inbound* market, the bidder pays the asker a premium for a
        channel with 50% to 100% of inbound liquidity. The premium amount is 
        calculated using the funding amount of the asker.

        In the outbound market, the bidder pays the asker a premium for  
        a channel with outbound liquidity. 
        To participate in the outbound market the asker needs to create an order
        with '--amt=100000' (one unit) and the '--min_chan_amt' equals to 
        the minimum channel size that is willing to accept.
        The bidder needs to create an order with '--amt=100000' (one unit) 
        and '--self_chan_balance' equals to the funds that is willing to commit 
        in a channel. The premium amount is calculated using the funding amount 
        of the bidder ('--self_chan_balance').
        

USAGE:
   pool orders submit command [command options] [arguments...]

COMMANDS:
   ask  offer channel liquidity
   bid  obtain channel liquidity

OPTIONS:
   --help, -h  show help
   

Messages

poolrpc.SubmitOrderRequest

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type	REST Placement
ask	Ask	object	body
bid	Bid	object	body
initiator An optional identification string that will be appended to the user agent string sent to the server to give information about the usage of 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).	string	string	body

poolrpc.SubmitOrderResponse

Source: poolrpc/trader.proto

Field	gRPC Type	REST Type
invalid_order Order failed with the given reason.	InvalidOrder	object
accepted_order_nonce The order nonce of the accepted order.	bytes	string
updated_sidecar_ticket In case a bid order was submitted for a sidecar ticket, that ticket is updated with the new state and bid order nonce.	string	string

Nested Messages

poolrpc.Ask

Field	gRPC Type	REST Type
details The common fields shared between both ask and bid order types.	Order	object
lease_duration_blocks The number of blocks the liquidity provider is willing to provide the channel funds for.	uint32	integer
version The version of the order format that is used. Will be increased once new features are added.	uint32	integer
announcement_constraints The constraints for selling the liquidity based on channel discoverability.	ChannelAnnouncementConstraints	string
confirmation_constraints The constraints for selling the liquidity based on the number of blocks before considering the channel confirmed.	ChannelConfirmationConstraints	string

poolrpc.Bid

Field	gRPC Type	REST Type
details The common fields shared between both ask and bid order types.	Order	object
lease_duration_blocks Required number of blocks that a channel opened as a result of this bid should be kept open.	uint32	integer
version The version of the order format that is used. Will be increased once new features are added.	uint32	integer
min_node_tier 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.	NodeTier	string
self_chan_balance 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 min_chan_amt must be set to the full order amount. For the inbound liquidity market the self_chan_balance can be at most the same as the order amount.	uint64	string
sidecar_ticket 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 base58 encoded ticket, including the prefix and the checksum.	string	string
unannounced_channel Signals if this bid is interested in an announced or unannounced channel.	bool	boolean
zero_conf_channel Signals if this bid is interested in a zero conf channel or not.	bool	boolean

poolrpc.InvalidOrder

Field	gRPC Type	REST Type
order_nonce	bytes	string
fail_reason	FailReason	string
fail_string	string	string

poolrpc.MatchEvent

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

poolrpc.Order

Field	gRPC Type	REST Type
trader_key The trader's account key of the account that is used for the order.	bytes	string
rate_fixed Fixed order rate in parts per billion.	uint32	integer
amt Order amount in satoshis.	uint64	string
max_batch_fee_rate_sat_per_kw Maximum fee rate the trader is willing to pay for the batch transaction, expressed in satoshis per 1000 weight units (sat/KW).	uint64	string
order_nonce Order nonce, acts as unique order identifier.	bytes	string
state The state the order currently is in.	OrderState	string
units The number of order units the amount corresponds to.	uint32	integer
units_unfulfilled 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.	uint32	integer
reserved_value_sat The value reserved from the account by this order to ensure the account can pay execution and chain fees in case it gets matched.	uint64	string
creation_timestamp_ns The unix timestamp in nanoseconds the order was first created/submitted.	uint64	string
events 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.	OrderEvent[]	array
min_units_match The minimum number of order units that must be matched per order pair.	uint32	integer
channel_type The channel type to use for the resulting matched channels.	OrderChannelType	string
allowed_node_ids List of nodes that will be allowed to match with our order. Incompatible with the `not_allowed_node_ids` field.	bytes[]	array
not_allowed_node_ids List of nodes that won't be allowed to match with our order. Incompatible with the `allowed_node_ids` field.	bytes[]	array
auction_type Auction type where this order must be considered during the matching.	AuctionType	string
is_public Flag used to signal that this order can be shared in public market places.	bool	boolean

poolrpc.OrderEvent

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

poolrpc.UpdatedEvent

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

Enums

poolrpc.AuctionType

Name	Number
AUCTION_TYPE_BTC_INBOUND_LIQUIDITY Default auction type where the bidder is paying for getting bitcoin inbound liqiudity from the asker.	0
AUCTION_TYPE_BTC_OUTBOUND_LIQUIDITY Auction type where the bidder is paying the asker to accept a channel (bitcoin outbound liquidity) from the bidder.	1

poolrpc.ChannelAnnouncementConstraints

Name	Number
ANNOUNCEMENT_NO_PREFERENCE	0
ONLY_ANNOUNCED	1
ONLY_UNANNOUNCED	2

poolrpc.ChannelConfirmationConstraints

Name	Number
CONFIRMATION_NO_PREFERENCE	0
ONLY_CONFIRMED	1
ONLY_ZEROCONF	2

poolrpc.InvalidOrder.FailReason

Name	Number
INVALID_AMT	0

poolrpc.MatchRejectReason

Name	Number
NONE No reject occurred, this is the default value.	0
SERVER_MISBEHAVIOR The client didn't come up with the same result as the server and is rejecting the batch because of that.	1
BATCH_VERSION_MISMATCH The client doesn't support the current batch verification version the server is using.	2
PARTIAL_REJECT_COLLATERAL 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.	3
PARTIAL_REJECT_DUPLICATE_PEER 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.	4
PARTIAL_REJECT_CHANNEL_FUNDING_FAILED 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.	5

poolrpc.MatchState

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

poolrpc.NodeTier

Name	Number
TIER_DEFAULT The default node tier. This value will be determined at run-time by the current order version.	0
TIER_0 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".	1
TIER_1 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.	2

poolrpc.OrderChannelType

Name	Number
ORDER_CHANNEL_TYPE_UNKNOWN Used to set defaults when a trader doesn't specify a channel type.	0
ORDER_CHANNEL_TYPE_PEER_DEPENDENT The channel type will vary per matched channel based on the features shared between its participants.	1
ORDER_CHANNEL_TYPE_SCRIPT_ENFORCED A channel type that builds upon the anchors commitment format to enforce channel lease maturities in the commitment and HTLC outputs that pay to the channel initiator/seller.	2
ORDER_CHANNEL_TYPE_SIMPLE_TAPROOT A channel type that uses a Pay-to-Taproot output for the funding output.	3

poolrpc.OrderState

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