QueryAssetRates

QueryAssetRates returns current asset rate information for a given asset and direction. This can be used for rate discovery, outgoing RFQ request construction, or general pricing information.

Source: portfoliopilotrpc/portfolio_pilot.proto

gRPC

rpc QueryAssetRates (QueryAssetRatesRequest) returns (QueryAssetRatesResponse);

REST

HTTP Method	Path
POST	/v1/taproot-assets/rfq/portfoliopilot/assetrates

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 = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
const TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync('portfoliopilotrpc/portfolio_pilot.proto', loaderOptions);
const portfoliopilotrpc = grpc.loadPackageDefinition(packageDefinition).portfoliopilotrpc;
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 portfoliopilotrpc.PortfolioPilot(GRPC_HOST, creds);
let request = {
  asset_specifier: <AssetSpecifier>,
  direction: <AssetTransferDirection>,
  intent: <Intent>,
  asset_amount: <uint64>,
  payment_amount: <uint64>,
  asset_rate_hint: <AssetRate>,
  price_oracle_metadata: <string>,
  peer_id: <bytes>,
  expiry_timestamp: <uint64>,
};
client.queryAssetRates(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "asset_rate": <AssetRate>,
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the portfoliopilotrpc/portfolio_pilot.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import portfolio_pilot_pb2 as portfoliopilotrpc, portfolio_pilot_pb2_grpc as portfolio_pilotstub

GRPC_HOST = 'localhost:10029'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_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 = portfolio_pilotstub.PortfolioPilotStub(channel)
request = portfoliopilotrpc.QueryAssetRatesRequest(
  asset_specifier=<AssetSpecifier>,
  direction=<AssetTransferDirection>,
  intent=<Intent>,
  asset_amount=<uint64>,
  payment_amount=<uint64>,
  asset_rate_hint=<AssetRate>,
  price_oracle_metadata=<string>,
  peer_id=<bytes>,
  expiry_timestamp=<uint64>,
)
response = stub.QueryAssetRates(request)
print(response)
# {
#    "asset_rate": <AssetRate>,
# }

REST

Javascript

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

const REST_HOST = 'localhost:8089'
const MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'

let requestBody = {
  asset_specifier: <object>, // <AssetSpecifier> 
  direction: <string>, // <AssetTransferDirection> 
  intent: <string>, // <Intent> 
  asset_amount: <string>, // <uint64> 
  payment_amount: <string>, // <uint64> 
  asset_rate_hint: <object>, // <AssetRate> 
  price_oracle_metadata: <string>, // <string> 
  peer_id: <string>, // <bytes> (base64 encoded)
  expiry_timestamp: <string>, // <uint64> 
};
let options = {
  url: `https://${REST_HOST}/v1/taproot-assets/rfq/portfoliopilot/assetrates`,
  // 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:
//  {
//    "asset_rate": <object>, // <AssetRate> 
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8089'
MACAROON_PATH = 'TAPROOT-ASSETS_DIR/regtest/taproot-assets.macaroon'
TLS_PATH = 'TAPROOT-ASSETS_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/taproot-assets/rfq/portfoliopilot/assetrates'
macaroon = codecs.encode(open(MACAROON_PATH, 'rb').read(), 'hex')
headers = {'Grpc-Metadata-macaroon': macaroon}
data = {
  'asset_specifier': <AssetSpecifier>,
  'direction': <AssetTransferDirection>,
  'intent': <Intent>,
  'asset_amount': <uint64>,
  'payment_amount': <uint64>,
  'asset_rate_hint': <AssetRate>,
  'price_oracle_metadata': <string>,
  'peer_id': base64.b64encode(<bytes>),
  'expiry_timestamp': <uint64>,
}
r = requests.post(url, headers=headers, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "asset_rate": <AssetRate>,
# }

Shell

# There is no CLI command for this RPC

Messages

portfoliopilotrpc.QueryAssetRatesRequest

Source: portfoliopilotrpc/portfolio_pilot.proto

Field	gRPC Type	REST Type	REST Placement
asset_specifier asset_specifier identifies the subject asset.	AssetSpecifier	object	body
direction direction specifies whether we want to buy or sell the asset.	AssetTransferDirection	string	body
intent intent specifies the purpose of the query.	Intent	string	body
asset_amount asset_amount is an optional constraint on the asset amount. If set to zero, it is considered unset.	uint64	string	body
payment_amount payment_amount is an optional constraint on the payment amount in msat. If set to zero, it is considered unset.	uint64	string	body
asset_rate_hint asset_rate_hint is an optional suggested asset rate.	AssetRate	object	body
price_oracle_metadata price_oracle_metadata is optional metadata for pricing decisions.	string	string	body
peer_id peer_id is the 33-byte public key of the counterparty peer.	bytes	string	body
expiry_timestamp expiry_timestamp is an optional expiry Unix timestamp (seconds) for the query context. If set to zero, it is considered unset.	uint64	string	body

portfoliopilotrpc.QueryAssetRatesResponse

Source: portfoliopilotrpc/portfolio_pilot.proto

Field	gRPC Type	REST Type
asset_rate asset_rate is the asset exchange rate response.	AssetRate	object

Nested Messages

portfoliopilotrpc.AssetRate

Field	gRPC Type	REST Type
rate rate is the asset to BTC conversion rate represented as a fixed-point number.	FixedPoint	object
expiry_timestamp expiry_timestamp is the Unix timestamp in seconds after which the rate is no longer valid.	uint64	string

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

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

Enums

portfoliopilotrpc.AssetTransferDirection

Name	Number
ASSET_TRANSFER_DIRECTION_UNSPECIFIED ASSET_TRANSFER_DIRECTION_UNSPECIFIED indicates an unspecified direction.	0
ASSET_TRANSFER_DIRECTION_BUY ASSET_TRANSFER_DIRECTION_BUY indicates we want to buy the asset.	1
ASSET_TRANSFER_DIRECTION_SELL ASSET_TRANSFER_DIRECTION_SELL indicates we want to sell the asset.	2

portfoliopilotrpc.Intent

Name	Number
INTENT_UNSPECIFIED INTENT_UNSPECIFIED is used to indicate that the intent of the price rate query is not specified. This is the fallback default value and should not be used in production code. It is primarily used for backward compatibility with older versions of the protocol that did not include intent information.	0
INTENT_PAY_INVOICE_HINT INTENT_PAY_INVOICE_HINT is used to indicate that the user is requesting a price rate hint for paying an invoice. This is typically used by the payer of an invoice to provide a suggestion of the expected asset rate to the RFQ peer (edge node) that will determine the actual rate for the payment.	1
INTENT_PAY_INVOICE INTENT_PAY_INVOICE is used to indicate that a peer wants to pay an invoice with assets. This is typically used by the edge node that facilitates the swap from assets to BTC for the payer of an invoice. This intent is used to provide the actual asset rate for the payment, which may differ from the hint provided by the payer.	2
INTENT_PAY_INVOICE_QUALIFY INTENT_PAY_INVOICE_QUALIFY is used to indicate that the payer of an invoice has received an asset rate from their RFQ peer (edge node) and is qualifying the rate for the payment. This is typically used by the payer of an invoice to ensure that the asset rate provided by their peer (edge node) is acceptable before proceeding with the payment.	3
INTENT_RECV_PAYMENT_HINT INTENT_RECV_PAYMENT_HINT is used to indicate that the user is requesting a price rate hint for receiving a payment through an invoice. This is typically used by the creator of an invoice to provide a suggestion of the expected asset rate to the RFQ peer (edge node) that will determine the actual rate used for creating an invoice.	4
INTENT_RECV_PAYMENT INTENT_RECV_PAYMENT is used to indicate that a peer wants to create an invoice to receive a payment with assets. This is typically used by the edge node that facilitates the swap from BTC to assets for the receiver of a payment. This intent is used to provide the actual asset rate for the invoice creation, which may differ from the hint provided by the receiver.	5
INTENT_RECV_PAYMENT_QUALIFY INTENT_RECV_PAYMENT_QUALIFY is used to indicate that the creator of an invoice received an asset rate from their RFQ peer (edge node) and is qualifying the rate for the creation of the invoice. This is typically used by the creator of an invoice to ensure that the asset rate provided by their peer (edge node) is acceptable before proceeding with creating the invoice.	6