AddAssetSellOrder

AddAssetSellOrder is used to add a sell order for a specific asset. If a sell order already exists for the asset, it will be updated.

Source: rfqrpc/rfq.proto

gRPC

rpc AddAssetSellOrder (AddAssetSellOrderRequest) returns (AddAssetSellOrderResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/rfq/sellorder/asset-id/{asset_specifier.asset_id_str}

Code Samples

gRPC

Javascript

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

const GRPC_HOST = 'localhost:10029'
const MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'
const TLS_PATH = 'TAPD_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('rfqrpc/rfq.proto', loaderOptions);
const rfqrpc = grpc.loadPackageDefinition(packageDefinition).rfqrpc;
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 rfqrpc.Rfq(GRPC_HOST, creds);
let request = {
  asset_specifier: <AssetSpecifier>,
  payment_max_amt: <uint64>,
  expiry: <uint64>,
  peer_pub_key: <bytes>,
  timeout_seconds: <uint32>,
  skip_asset_channel_check: <bool>,
  price_oracle_metadata: <string>,
  payment_min_amt: <uint64>,
  asset_rate_limit: <FixedPoint>,
  execution_policy: <ExecutionPolicy>,
};
client.addAssetSellOrder(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "accepted_quote": <PeerAcceptedSellQuote>,
//    "invalid_quote": <InvalidQuoteResponse>,
//    "rejected_quote": <RejectedQuoteResponse>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the rfqrpc/rfq.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import rfq_pb2 as rfqrpc, rfq_pb2_grpc as rfqstub

GRPC_HOST = 'localhost:10029'
MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'
TLS_PATH = 'TAPD_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 = rfqstub.RfqStub(channel)
request = rfqrpc.AddAssetSellOrderRequest(
  asset_specifier=<AssetSpecifier>,
  payment_max_amt=<uint64>,
  expiry=<uint64>,
  peer_pub_key=<bytes>,
  timeout_seconds=<uint32>,
  skip_asset_channel_check=<bool>,
  price_oracle_metadata=<string>,
  payment_min_amt=<uint64>,
  asset_rate_limit=<FixedPoint>,
  execution_policy=<ExecutionPolicy>,
)
response = stub.AddAssetSellOrder(request)
print(response)
# {
#    "accepted_quote": <PeerAcceptedSellQuote>,
#    "invalid_quote": <InvalidQuoteResponse>,
#    "rejected_quote": <RejectedQuoteResponse>,
# }

grpcurl

# grpcurl docs: https://github.com/fullstorydev/grpcurl
# Proto source: https://github.com/lightninglabs/taproot-assets
GRPC_HOST=localhost:10029
TAPD_DIR=~/.tapd
TAPD_SOURCE=path/to/taproot-assets
NETWORK=mainnet
MACAROON_PATH="$TAPD_DIR/data/$NETWORK/admin.macaroon"
TLS_PATH="$TAPD_DIR/tls.cert"

grpcurl \
    -import-path $TAPD_SOURCE/taprpc/ \
    -proto rfqrpc/rfq.proto \
    -cacert $TLS_PATH \
    -H "macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "asset_specifier": <AssetSpecifier>, "payment_max_amt": <uint64>, "expiry": <uint64>, "peer_pub_key": BASE64_ENCODED_VALUE, "timeout_seconds": <uint32>, "skip_asset_channel_check": <bool>, "price_oracle_metadata": <string>, "payment_min_amt": <uint64>, "asset_rate_limit": <FixedPoint>, "execution_policy": <ExecutionPolicy> }' \
    $GRPC_HOST \
    rfqrpc.Rfq/AddAssetSellOrder

REST

Javascript

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

const REST_HOST = 'localhost:8089'
const MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'

let requestBody = {
  asset_specifier: <object>, // <AssetSpecifier> 
  payment_max_amt: <unknown>, // <uint64> 
  expiry: <unknown>, // <uint64> 
  peer_pub_key: <unknown>, // <bytes> (base64 encoded)
  timeout_seconds: <unknown>, // <uint32> 
  skip_asset_channel_check: <unknown>, // <bool> 
  price_oracle_metadata: <unknown>, // <string> 
  payment_min_amt: <unknown>, // <uint64> 
  asset_rate_limit: <object>, // <FixedPoint> 
  execution_policy: <object>, // <ExecutionPolicy> 
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/rfq/sellorder/asset-id/{asset_specifier.asset_id_str}`,
  // 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:
//  {
//    "accepted_quote": <object>, // <PeerAcceptedSellQuote> 
//    "invalid_quote": <object>, // <InvalidQuoteResponse> 
//    "rejected_quote": <object>, // <RejectedQuoteResponse> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8089'
MACAROON_PATH = 'TAPD_DIR/data/regtest/admin.macaroon'
TLS_PATH = 'TAPD_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/taproot-assets/rfq/sellorder/asset-id/{asset_specifier.asset_id_str}'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'asset_specifier': <AssetSpecifier>,
  'payment_max_amt': <uint64>,
  'expiry': <uint64>,
  'peer_pub_key': base64.b64encode(<bytes>),
  'timeout_seconds': <uint32>,
  'skip_asset_channel_check': <bool>,
  'price_oracle_metadata': <string>,
  'payment_min_amt': <uint64>,
  'asset_rate_limit': <FixedPoint>,
  'execution_policy': <ExecutionPolicy>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "accepted_quote": <PeerAcceptedSellQuote>,
#    "invalid_quote": <InvalidQuoteResponse>,
#    "rejected_quote": <RejectedQuoteResponse>,
# }

curl

REST_HOST=localhost:8089
TAPD_DIR=~/.tapd
NETWORK=mainnet
MACAROON_PATH="$TAPD_DIR/data/$NETWORK/admin.macaroon"
TLS_PATH="$TAPD_DIR/tls.cert"

curl -X POST \
    --cacert $TLS_PATH \
    -H "Grpc-Metadata-macaroon: $(xxd -ps -u -c 1000 $MACAROON_PATH)" \
    -d '{ "asset_specifier": <AssetSpecifier>, "payment_max_amt": <uint64>, "expiry": <uint64>, "peer_pub_key": BASE64_ENCODED_VALUE, "timeout_seconds": <uint32>, "skip_asset_channel_check": <bool>, "price_oracle_metadata": <string>, "payment_min_amt": <uint64>, "asset_rate_limit": <FixedPoint>, "execution_policy": <ExecutionPolicy> }' \
    https://$REST_HOST/v1/taproot-assets/rfq/sellorder/asset-id/{asset_specifier.asset_id_str}

Messages

rfqrpc.AddAssetSellOrderRequest

Source: rfqrpc/rfq.proto

Field	gRPC Type	REST Type	REST Placement
asset_specifier asset_specifier is the subject asset. Nested REST Parameters asset_specifier.asset_id_str: string in path	AssetSpecifier	object	path
payment_max_amt The maximum msat amount that the responding peer must agree to pay (units: millisats).	uint64	unknown	body
expiry The unix timestamp in seconds after which the order is no longer valid.	uint64	unknown	body
peer_pub_key The public key of the intended recipient peer for the order.	bytes	unknown	body
timeout_seconds timeout_seconds is the number of seconds to wait for the peer to respond with an accepted quote (or a rejection).	uint32	unknown	body
skip_asset_channel_check If set, the check if a channel with the given asset exists with the peer will be skipped. An active channel with the peer is still required for the RFQ negotiation to work. This flag shouldn't be set outside of test scenarios.	bool	unknown	body
price_oracle_metadata An optional text field that can be used to provide additional metadata about the sell order to the price oracle. This can include information about the wallet end user that initiated the transaction, or any authentication information that the price oracle can use to give out a more accurate (or discount) asset rate. Though not verified or enforced by tapd, the suggested format for this field is a JSON string. This field is optional and can be left empty if no metadata is available. The maximum length of this field is 32'768 bytes.	string	unknown	body
payment_min_amt The optional minimum msat amount that the responding peer must agree to pay. If set, must be less than or equal to payment_max_amt. When omitted, defaults to payment_max_amt (full-fill expected). Set explicitly to 0 to accept any partial fill (units: millisats).	uint64	unknown	body
asset_rate_limit An optional rate limit constraint expressed as a fixed-point number. For sell orders this is the maximum acceptable rate (asset units per BTC). If unset, no rate ceiling is enforced.	FixedPoint	object	body
execution_policy The execution policy for this order. IOC (default) accepts any partial fill >= min threshold. FOK requires the rate to support the full max amount.	ExecutionPolicy	object	body

rfqrpc.AddAssetSellOrderResponse

Source: rfqrpc/rfq.proto

Field	gRPC Type	REST Type
accepted_quote accepted_quote holds the quote received from the peer as a response to our quote request.	PeerAcceptedSellQuote	object
invalid_quote invalid_quote is returned if the quote response received from the peer was invalid or insufficient.	InvalidQuoteResponse	object
rejected_quote rejected_quote is returned if the quote request was rejected by the peer.	RejectedQuoteResponse	object

Nested Messages

rfqrpc.AssetSpec

Field	gRPC Type	REST Type
id The 32-byte asset ID specified as raw bytes.	bytes	string
group_pub_key The 32-byte asset group public key, serialized in BIP340 format. BIP340 defines a canonical encoding for Schnorr public keys. This field is serialized using schnorr.SerializePubKey.	bytes	string

rfqrpc.AssetSpecifier

Field	gRPC Type	REST Type
asset_id The 32-byte asset ID specified as raw bytes (gRPC only).	bytes	string
asset_id_str The 32-byte asset ID encoded as a hex string (use this for REST).	string	string
group_key The 32-byte asset group key specified as raw bytes (gRPC only).	bytes	string
group_key_str The 32-byte asset group key encoded as hex string (use this for REST).	string	string

rfqrpc.FixedPoint

Field	gRPC Type	REST Type
coefficient The coefficient is the fractional value scaled-up as an integer. This integer is represented as a string as it may be too large to fit in a uint64.	string	string
scale The scale is the component that determines how many decimal places the coefficient should be divided by to obtain the fractional value.	uint32	integer

rfqrpc.InvalidQuoteResponse

Field	gRPC Type	REST Type
status status is the status of the quote response.	QuoteRespStatus	string
peer peer is the quote counterparty peer.	string	string
id id is the unique identifier of the quote request.	bytes	string

rfqrpc.PeerAcceptedSellQuote

Field	gRPC Type	REST Type
peer Quote counterparty peer.	string	string
id The unique identifier of the quote request.	bytes	string
scid scid is the short channel ID of the channel over which the payment for the quote should be made.	uint64	string
asset_amount asset_amount is the amount of the subject asset.	uint64	string
bid_asset_rate bid_asset_rate is the asset to BTC conversion rate represented as a fixed-point number.	FixedPoint	object
expiry The unix timestamp in seconds after which the quote is no longer valid.	uint64	string
min_transportable_msat The minimum amount of milli-satoshis that need to be sent out in order to transport a single asset unit over the Lightning Network with the given rate. This is the base amount of 354,000 milli-satoshi (the minimum amount for a non-dust HTLC) plus the equivalent of one asset unit in milli-satoshis.	uint64	string
price_oracle_metadata An optional user-provided text field used to provide additional metadata about the sell order to the price oracle. This can include information about the wallet end user that initiated the transaction, or any authentication information that the price oracle can use to give out a more accurate (or discount) asset rate.	string	string
asset_spec The subject asset specifier.	AssetSpec	object
accepted_max_amount accepted_max_amount is an optional negotiated fill quantity. When non-zero the responder accepted up to this many msat instead of the full request max.	uint64	string

rfqrpc.RejectedQuoteResponse

Field	gRPC Type	REST Type
peer peer is the quote counterparty peer.	string	string
id id is the unique identifier of the quote request.	bytes	string
error_message error_message is a human-readable error message.	string	string
error_code error_code is a machine-readable error code.	uint32	integer

Enums

rfqrpc.ExecutionPolicy

Name	Number
EXECUTION_POLICY_IOC EXECUTION_POLICY_IOC is Immediate-Or-Cancel: accept any partial fill at or above the minimum threshold. This is the default.	0
EXECUTION_POLICY_FOK EXECUTION_POLICY_FOK is Fill-Or-Kill: the accepted rate must support the full maximum amount or the quote is rejected.	1

rfqrpc.QuoteRespStatus

Name	Number
INVALID_ASSET_RATES INVALID_ASSET_RATES indicates that at least one asset rate in the quote response is invalid.	0
INVALID_EXPIRY INVALID_EXPIRY indicates that the expiry in the quote response is invalid.	1
PRICE_ORACLE_QUERY_ERR PRICE_ORACLE_QUERY_ERR indicates that an error occurred when querying the price oracle whilst evaluating the quote response.	2
PORTFOLIO_PILOT_ERR PORTFOLIO_PILOT_ERR indicates that an unexpected error occurred in the portfolio pilot while evaluating the quote response.	3
VALID_ACCEPT_QUOTE VALID_ACCEPT_QUOTE indicates that the accepted quote passed all validation checks successfully.	4
MIN_FILL_NOT_MET MIN_FILL_NOT_MET indicates that the minimum fill constraint was not satisfiable at the accepted rate.	5
RATE_BOUND_MISS RATE_BOUND_MISS indicates that the accepted rate violated the requester's rate limit constraint.	6
FOK_NOT_VIABLE FOK_NOT_VIABLE indicates that the FOK execution policy could not be satisfied at the accepted rate.	7