Faraday gRPC API Reference
Welcome to the gRPC API reference documentation for Faraday.
Faraday is an external service intended to be run in conjunction with the lnd
implementation of the Lightning Network. It queries LND for information about its existing
channels and provides channel close recommendations if channels are under-performing.
This site features the documentation for frcli
(CLI), and the API documentation
for Python and JavaScript clients in order to communicate with a local faraday
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
ddd3cd123e628b6ef32b70c5ae9577ddd774d941
.
Service FaradayServer
FaradayServer.ChannelInsights
Unary RPC
List currently open channel with routing and uptime information. Example request: http://localhost:8466/v1/faraday/insights
# List currently open channel with routing and uptime information.
$ frcli insights [arguments...]
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the frdrpc/faraday.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub
>>> channel = grpc.insecure_channel('localhost:8465')
>>> stub = faradaystub.FaradayServerStub(channel)
>>> request = frdrpc.ChannelInsightsRequest()
>>> response = stub.ChannelInsights(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"channel_insights": <array ChannelInsight>,
}
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
const faradayServer = new frdrpc.FaradayServer('localhost:8465', grpc.credentials.createInsecure());
let request = {}
faradayServer.channelInsights(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "channel_insights": <array ChannelInsight>,
// }
This request has no parameters.
Parameter |
Type |
Description |
channel_insights |
array ChannelInsight |
Insights for the set of currently open channels. |
FaradayServer.CloseReport
Unary RPC
Get a channel close report for a specific channel. Example request: http://localhost:8466/v1/faraday/closereport
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the frdrpc/faraday.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub
>>> channel = grpc.insecure_channel('localhost:8465')
>>> stub = faradaystub.FaradayServerStub(channel)
>>> request = frdrpc.CloseReportRequest(
channel_point=<string>,
)
>>> response = stub.CloseReport(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"channel_point": <string>,
"channel_initiator": <bool>,
"close_type": <string>,
"close_txid": <string>,
"open_fee": <string>,
"close_fee": <string>,
}
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
const faradayServer = new frdrpc.FaradayServer('localhost:8465', grpc.credentials.createInsecure());
let request = {
channel_point: <string>,
};
faradayServer.closeReport(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "channel_point": <string>,
// "channel_initiator": <bool>,
// "close_type": <string>,
// "close_txid": <string>,
// "open_fee": <string>,
// "close_fee": <string>,
// }
Parameter |
Type |
Description |
channel_point |
string |
The funding outpoint of the channel the report should be created for, formatted txid:outpoint. |
Parameter |
Type |
Description |
channel_point |
string |
The funding outpoint of the channel. |
channel_initiator |
bool |
True if we opened the channel, false if the remote peer did. |
close_type |
string |
The type of close that resolved this channel. |
close_txid |
string |
The transaction id of the close transaction that confirmed on chain. |
open_fee |
string |
The fee we paid on chain to open this channel in satoshis, note that this field will be zero if the remote party paid. |
close_fee |
string |
The fee we paid on chain for the close transaction in staoshis, note that this field will be zero if the remote party paid. |
FaradayServer.ExchangeRate
Unary RPC
frcli: Get fiat prices for btc. Example request: http://localhost:8466/v1/faraday/exchangerate
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the frdrpc/faraday.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub
>>> channel = grpc.insecure_channel('localhost:8465')
>>> stub = faradaystub.FaradayServerStub(channel)
>>> request = frdrpc.ExchangeRateRequest(
timestamps=<array uint64>,
granularity=<Granularity>,
fiat_backend=<FiatBackend>,
custom_prices=<array BitcoinPrice>,
)
>>> response = stub.ExchangeRate(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"rates": <array ExchangeRate>,
}
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
const faradayServer = new frdrpc.FaradayServer('localhost:8465', grpc.credentials.createInsecure());
let request = {
timestamps: <array uint64>,
granularity: <Granularity>,
fiat_backend: <FiatBackend>,
custom_prices: <array BitcoinPrice>,
};
faradayServer.exchangeRate(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "rates": <array ExchangeRate>,
// }
Parameter |
Type |
Description |
timestamps |
array uint64 |
A set of timestamps for which we want the bitcoin price. |
granularity |
Granularity |
The level of granularity at which we want the bitcoin price to be quoted. |
fiat_backend |
FiatBackend |
The api to be used for fiat related queries. |
custom_prices |
array BitcoinPrice |
Custom price points to use if the CUSTOM FiatBackend option is set. |
Parameter |
Type |
Description |
rates |
array ExchangeRate |
Rates contains a set of exchange rates for the set of timestamps |
FaradayServer.NodeAudit
Unary RPC
Get a report of your node's activity over a period. Example request: http://localhost:8466/v1/faraday/nodeaudit
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the frdrpc/faraday.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub
>>> channel = grpc.insecure_channel('localhost:8465')
>>> stub = faradaystub.FaradayServerStub(channel)
>>> request = frdrpc.NodeAuditRequest(
start_time=<uint64>,
end_time=<uint64>,
disable_fiat=<bool>,
granularity=<Granularity>,
custom_categories=<array CustomCategory>,
fiat_backend=<FiatBackend>,
custom_prices=<array BitcoinPrice>,
)
>>> response = stub.NodeAudit(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"reports": <array ReportEntry>,
}
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
const faradayServer = new frdrpc.FaradayServer('localhost:8465', grpc.credentials.createInsecure());
let request = {
start_time: <uint64>,
end_time: <uint64>,
disable_fiat: <bool>,
granularity: <Granularity>,
custom_categories: <array CustomCategory>,
fiat_backend: <FiatBackend>,
custom_prices: <array BitcoinPrice>,
};
faradayServer.nodeAudit(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "reports": <array ReportEntry>,
// }
Parameter |
Type |
Description |
start_time |
uint64 |
The unix time from which to produce the report, inclusive. |
end_time |
uint64 |
The unix time until which to produce the report, exclusive. |
disable_fiat |
bool |
Set to generate a report without conversion to fiat. If set, fiat values will display as 0. |
granularity |
Granularity |
The level of granularity at which we wish to produce fiat prices. |
custom_categories |
array CustomCategory |
An optional set of custom categories which can be used to identify bespoke categories in the report. Each category must have a unique name, and may not have common identifier regexes. Transactions that are matched to these categories report the category name in the CustomCategory field. |
fiat_backend |
FiatBackend |
The api to be used for fiat related queries. |
custom_prices |
array BitcoinPrice |
Custom price points to use if the CUSTOM FiatBackend option is set. |
Parameter |
Type |
Description |
reports |
array ReportEntry |
On chain reports for the period queried. |
FaradayServer.OutlierRecommendations
Unary RPC
Get close recommendations for currently open channels based on whether it is an outlier. Example request: http://localhost:8466/v1/faraday/outliers/REVENUE?rec_request.minimum_monitored=123
# Get close recommendations for currently open channels based on whether it is an outlier.
$ frcli outliers [command options] [arguments...]
# --outlier_mult value (optional with outlier strategy) Number of inter quartile ranges a channel should be from quartiles to be considered an outlier. Recommended values are 1.5 for aggressive recommendations and 3 for conservative ones.
# --uptime set to get recommendations based on the channel's peer's ratio of uptime to time monitored
# --revenue get recommendations based on the channel's revenue per confirmation
# --incoming_volume get recommendations based on the channel's incoming volume per confirmation
# --outgoing_volume get recommendations based on the channel's outgoing volume per confirmation
# --volume get recommendations based on the channel's total volume per confirmation
# --min_monitored value amount of time in seconds a channel should be monitored for to be eligible for close (default: 2419200)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the frdrpc/faraday.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub
>>> channel = grpc.insecure_channel('localhost:8465')
>>> stub = faradaystub.FaradayServerStub(channel)
>>> request = frdrpc.OutlierRecommendationsRequest(
rec_request=<CloseRecommendationRequest>,
outlier_multiplier=<float>,
)
>>> response = stub.OutlierRecommendations(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"total_channels": <int32>,
"considered_channels": <int32>,
"recommendations": <array Recommendation>,
}
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
const faradayServer = new frdrpc.FaradayServer('localhost:8465', grpc.credentials.createInsecure());
let request = {
rec_request: <CloseRecommendationRequest>,
outlier_multiplier: <float>,
};
faradayServer.outlierRecommendations(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "total_channels": <int32>,
// "considered_channels": <int32>,
// "recommendations": <array Recommendation>,
// }
Parameter |
Type |
Description |
rec_request |
CloseRecommendationRequest |
The parameters that are common to all close recommendations. |
outlier_multiplier |
float |
The number of inter-quartile ranges a value needs to be beneath the lower quartile/ above the upper quartile to be considered a lower/upper outlier. Lower values will be more aggressive in recommending channel closes, and upper values will be more conservative. Recommended values are 1.5 for aggressive recommendations and 3 for conservative recommendations. |
Parameter |
Type |
Description |
total_channels |
int32 |
The total number of channels, before filtering out channels that are not eligible for close recommendations. |
considered_channels |
int32 |
The number of channels that were considered for close recommendations. |
recommendations |
array Recommendation |
A set of channel close recommendations. The absence of a channel in this set implies that it was not considered for close because it did not meet the criteria for close recommendations (it is private, or has not been monitored for long enough). |
FaradayServer.RevenueReport
Unary RPC
Get a pairwise revenue report for a channel. Example request: http://localhost:8466/v1/faraday/revenue
# Get a pairwise revenue report for a channel.
$ frcli revenue [command options] [arguments...]
# --chan_points value (optional) A set of channels to generate a revenue report for. If not specified, reports will be created for all channels that forwarded payments over the period provided. A single channel can be set directly using --chan_points=txid:outpoint,multiple channels should be specified usinga comma separated list in braces --chan_points={chan, chan}
# --start_time value (optional) The unix timestamp in seconds from which the report should be generated.If not set, the report will be generated from the time of channel open. (default: 0)
# --end_time value (optional) The unix timestamp in secondsuntil which the report should be generated.If not set, the report will be produced until the present. (default: 0)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the frdrpc/faraday.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub
>>> channel = grpc.insecure_channel('localhost:8465')
>>> stub = faradaystub.FaradayServerStub(channel)
>>> request = frdrpc.RevenueReportRequest(
chan_points=<array string>,
start_time=<uint64>,
end_time=<uint64>,
)
>>> response = stub.RevenueReport(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"reports": <array RevenueReport>,
}
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
const faradayServer = new frdrpc.FaradayServer('localhost:8465', grpc.credentials.createInsecure());
let request = {
chan_points: <array string>,
start_time: <uint64>,
end_time: <uint64>,
};
faradayServer.revenueReport(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "reports": <array RevenueReport>,
// }
Parameter |
Type |
Description |
chan_points |
array string |
The funding transaction outpoints for the channels to generate a revenue report for. If this is empty, it will be generated for all open and closed channels. Channel funding points should be expressed with the format fundingTxID:outpoint. |
start_time |
uint64 |
Start time is beginning of the range over which the report will be generated, expressed as unix epoch offset in seconds. |
end_time |
uint64 |
End time is end of the range over which the report will be generated, expressed as unix epoch offset in seconds. |
Parameter |
Type |
Description |
reports |
array RevenueReport |
Reports is a set of pairwise revenue report generated for the channel(s) over the period specified. |
FaradayServer.ThresholdRecommendations
Unary RPC
Get close recommendations for currently open channels based whether they are below a set threshold. Example request: http://localhost:8466/v1/faraday/threshold/UPTIME?rec_request.minimum_monitored=123
# Get close recommendations for currently open channels based on whether they are below a set threshold.
$ frcli threshold [command options] [arguments...]
# --uptime value Ratio of uptime to time monitored, expressed in [0;1]. (default: 0)
# --revenue value threshold revenue (in msat) per confirmation beneath which channels will be identified for close. (default: 0)
# --incoming value threshold incoming volume (in msat) per confirmation beneath which channels will be identified for close (default: 0)
# --outgoing value threshold outgoing volume (in msat) per confirmation beneath which channels will be identified for close (default: 0)
# --volume value threshold total volume (in msat) per confirmation beneath which channels will be identified for close (default: 0)
# --min_monitored value amount of time in seconds a channel should be monitored for to be eligible for close (default: 2419200)
>>> import codecs, grpc, os
>>> # Generate the following 2 modules by compiling the frdrpc/faraday.proto with the grpcio-tools.
>>> # See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
>>> import faraday_pb2 as frdrpc, faraday_pb2_grpc as faradaystub
>>> channel = grpc.insecure_channel('localhost:8465')
>>> stub = faradaystub.FaradayServerStub(channel)
>>> request = frdrpc.ThresholdRecommendationsRequest(
rec_request=<CloseRecommendationRequest>,
threshold_value=<float>,
)
>>> response = stub.ThresholdRecommendations(request, metadata=[('macaroon', macaroon)])
>>> print(response)
{
"total_channels": <int32>,
"considered_channels": <int32>,
"recommendations": <array Recommendation>,
}
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const loaderOptions = {
keepCase: true,
longs: String,
enums: String,
defaults: true,
oneofs: true
};
const packageDefinition = protoLoader.loadSync('faraday.proto', loaderOptions);
const frdrpc = grpc.loadPackageDefinition(packageDefinition).frdrpc;
const faradayServer = new frdrpc.FaradayServer('localhost:8465', grpc.credentials.createInsecure());
let request = {
rec_request: <CloseRecommendationRequest>,
threshold_value: <float>,
};
faradayServer.thresholdRecommendations(request, function(err, response) {
console.log(response);
});
// Console output:
// {
// "total_channels": <int32>,
// "considered_channels": <int32>,
// "recommendations": <array Recommendation>,
// }
Parameter |
Type |
Description |
rec_request |
CloseRecommendationRequest |
The parameters that are common to all close recommendations. |
threshold_value |
float |
The threshold that recommendations will be calculated based on. For uptime: ratio of uptime to observed lifetime beneath which channels will be recommended for closure. For revenue: revenue per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For incoming volume: The incoming volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For outgoing volume: The outgoing volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For total volume: The total volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. |
Parameter |
Type |
Description |
total_channels |
int32 |
The total number of channels, before filtering out channels that are not eligible for close recommendations. |
considered_channels |
int32 |
The number of channels that were considered for close recommendations. |
recommendations |
array Recommendation |
A set of channel close recommendations. The absence of a channel in this set implies that it was not considered for close because it did not meet the criteria for close recommendations (it is private, or has not been monitored for long enough). |
gRPC Messages
frdrpc.BitcoinPrice
Parameter |
Type |
Description |
price |
string |
The price of 1 BTC, expressed in USD. |
price_timestamp |
uint64 |
The timestamp for this price price provided. |
currency |
string |
The currency that the price is denoted in. |
frdrpc.ChannelInsight
Parameter |
Type |
Description |
chan_point |
string |
The outpoint of the channel's funding transaction. |
monitored_seconds |
uint64 |
The amount of time in seconds that we have monitored the channel peer's uptime for. |
uptime_seconds |
uint64 |
The amount of time in seconds that the channel peer has been online over the period it has been monitored for. |
volume_incoming_msat |
int64 |
The volume, in millisatoshis, that has been forwarded with this channel as the incoming channel. |
volume_outgoing_msat |
int64 |
The volume, in millisatoshis, that has been forwarded with this channel as the outgoing channel. |
fees_earned_msat |
int64 |
The total fees earned by this channel for its participation in forwards, expressed in millisatoshis. Note that we attribute fees evenly across incoming and outgoing channels. |
confirmations |
uint32 |
The number of confirmations the funding transaction has. |
private |
bool |
True if the channel is private. |
frdrpc.ChannelInsightsRequest
This message has no parameters.
frdrpc.ChannelInsightsResponse
Parameter |
Type |
Description |
channel_insights |
array ChannelInsight |
Insights for the set of currently open channels. |
frdrpc.CloseRecommendationRequest
Parameter |
Type |
Description |
minimum_monitored |
int64 |
The minimum amount of time in seconds that a channel should have been monitored by lnd to be eligible for close. This value is in place to protect against closing of newer channels. |
metric |
Metric |
The data point base close recommendations on. Available options are: Uptime: ratio of channel peer's uptime to the period they have been monitored to. Revenue: the revenue that the channel has produced per block that its funding transaction has been confirmed for. |
frdrpc.CloseRecommendationsResponse
Parameter |
Type |
Description |
total_channels |
int32 |
The total number of channels, before filtering out channels that are not eligible for close recommendations. |
considered_channels |
int32 |
The number of channels that were considered for close recommendations. |
recommendations |
array Recommendation |
A set of channel close recommendations. The absence of a channel in this set implies that it was not considered for close because it did not meet the criteria for close recommendations (it is private, or has not been monitored for long enough). |
frdrpc.CloseReportRequest
Parameter |
Type |
Description |
channel_point |
string |
The funding outpoint of the channel the report should be created for, formatted txid:outpoint. |
frdrpc.CloseReportResponse
Parameter |
Type |
Description |
channel_point |
string |
The funding outpoint of the channel. |
channel_initiator |
bool |
True if we opened the channel, false if the remote peer did. |
close_type |
string |
The type of close that resolved this channel. |
close_txid |
string |
The transaction id of the close transaction that confirmed on chain. |
open_fee |
string |
The fee we paid on chain to open this channel in satoshis, note that this field will be zero if the remote party paid. |
close_fee |
string |
The fee we paid on chain for the close transaction in staoshis, note that this field will be zero if the remote party paid. |
frdrpc.CustomCategory
Parameter |
Type |
Description |
name |
string |
The name for the custom category which will contain all transactions that are labelled with a string matching one of the regexes provided in label identifiers. |
on_chain |
bool |
Set to true to apply this category to on chain transactions. Can be set in conjunction with off_chain to apply the category to all transactions. |
off_chain |
bool |
Set to true to apply this category to off chain transactions. Can be set in conjunction with on_chain to apply the category to all transactions. |
label_patterns |
array string |
A set of regular expressions which identify transactions by their label as belonging in this custom category. If a label matches any single regex in the set, it is considered to be in the category. These expressions will be matched against various labels that are present in lnd: on chain transactions will be matched against their label field, off chain receipts will be matched against their memo. At present, there is no way to match forwards or off chain payments. These expressions must be unique across custom categories, otherwise faraday will not be able to identify which custom category a transaction belongs in. |
frdrpc.ExchangeRate
Parameter |
Type |
Description |
timestamp |
uint64 |
timestamp is the timestamp of the original request made. |
btc_price |
BitcoinPrice |
Price is the bitcoin price approximation for the timestamp queried. Note that this value has its own timestamp because we are not guaranteed to get price points for the exact timestamp that was queried. |
frdrpc.ExchangeRateRequest
Parameter |
Type |
Description |
timestamps |
array uint64 |
A set of timestamps for which we want the bitcoin price. |
granularity |
Granularity |
The level of granularity at which we want the bitcoin price to be quoted. |
fiat_backend |
FiatBackend |
The api to be used for fiat related queries. |
custom_prices |
array BitcoinPrice |
Custom price points to use if the CUSTOM FiatBackend option is set. |
frdrpc.ExchangeRateResponse
Parameter |
Type |
Description |
rates |
array ExchangeRate |
Rates contains a set of exchange rates for the set of timestamps |
frdrpc.NodeAuditRequest
Parameter |
Type |
Description |
start_time |
uint64 |
The unix time from which to produce the report, inclusive. |
end_time |
uint64 |
The unix time until which to produce the report, exclusive. |
disable_fiat |
bool |
Set to generate a report without conversion to fiat. If set, fiat values will display as 0. |
granularity |
Granularity |
The level of granularity at which we wish to produce fiat prices. |
custom_categories |
array CustomCategory |
An optional set of custom categories which can be used to identify bespoke categories in the report. Each category must have a unique name, and may not have common identifier regexes. Transactions that are matched to these categories report the category name in the CustomCategory field. |
fiat_backend |
FiatBackend |
The api to be used for fiat related queries. |
custom_prices |
array BitcoinPrice |
Custom price points to use if the CUSTOM FiatBackend option is set. |
frdrpc.NodeAuditResponse
Parameter |
Type |
Description |
reports |
array ReportEntry |
On chain reports for the period queried. |
frdrpc.OutlierRecommendationsRequest
Parameter |
Type |
Description |
rec_request |
CloseRecommendationRequest |
The parameters that are common to all close recommendations. |
outlier_multiplier |
float |
The number of inter-quartile ranges a value needs to be beneath the lower quartile/ above the upper quartile to be considered a lower/upper outlier. Lower values will be more aggressive in recommending channel closes, and upper values will be more conservative. Recommended values are 1.5 for aggressive recommendations and 3 for conservative recommendations. |
frdrpc.PairReport
Parameter |
Type |
Description |
amount_outgoing_msat |
int64 |
Amount outgoing msat is the amount in millisatoshis that arrived on the pair channel to be forwarded onwards by our channel. |
fees_outgoing_msat |
int64 |
Fees outgoing is the amount of fees in millisatoshis that we attribute to the channel for its role as the outgoing channel in forwards. |
amount_incoming_msat |
int64 |
Amount incoming msat is the amount in millisatoshis that arrived on our channel to be forwarded onwards by the pair channel. |
fees_incoming_msat |
int64 |
Fees incoming is the amount of fees in millisatoshis that we attribute to the channel for its role as the incoming channel in forwards. |
frdrpc.Recommendation
Parameter |
Type |
Description |
chan_point |
string |
The channel point [funding txid: outpoint] of the channel being considered for close. |
value |
float |
The value of the metric that close recommendations were based on. |
recommend_close |
bool |
A boolean indicating whether we recommend closing the channel. |
frdrpc.ReportEntry
Parameter |
Type |
Description |
timestamp |
uint64 |
The unix timestamp of the event. |
on_chain |
bool |
Whether the entry occurred on chain or off chain. |
amount |
uint64 |
The amount of the entry, expressed in millisatoshis. |
credit |
bool |
Whether the entry is a credit or a debit. |
asset |
string |
The asset affected by the entry. |
type |
EntryType |
The kind of activity that this entry represents. |
custom_category |
string |
This field will be populated for entry type custom, and represents the name of a custom category that the report was produced with. |
txid |
string |
The transaction id of the entry. |
fiat |
string |
The fiat amount of the entry's amount in the currency specified in the btc_price field. |
reference |
string |
A unique identifier for the entry, if available. |
note |
string |
An additional note for the entry, providing additional context. |
btc_price |
BitcoinPrice |
The bitcoin price and timestamp used to calculate our fiat value. |
frdrpc.RevenueReport
Parameter |
Type |
Description |
target_channel |
string |
Target channel is the channel that the report is generated for; incoming fields in the report mean that this channel was the incoming channel, and the pair as the outgoing, outgoing fields mean that this channel was the outgoing channel and the peer was the incoming channel. |
pair_reports |
array PairReportsEntry |
Pair reports maps the channel point of a peer that we generated revenue with to a report detailing the revenue. |
frdrpc.RevenueReport.PairReportsEntry
Parameter |
Type |
Description |
key |
string |
|
value |
PairReport |
|
frdrpc.RevenueReportRequest
Parameter |
Type |
Description |
chan_points |
array string |
The funding transaction outpoints for the channels to generate a revenue report for. If this is empty, it will be generated for all open and closed channels. Channel funding points should be expressed with the format fundingTxID:outpoint. |
start_time |
uint64 |
Start time is beginning of the range over which the report will be generated, expressed as unix epoch offset in seconds. |
end_time |
uint64 |
End time is end of the range over which the report will be generated, expressed as unix epoch offset in seconds. |
frdrpc.RevenueReportResponse
Parameter |
Type |
Description |
reports |
array RevenueReport |
Reports is a set of pairwise revenue report generated for the channel(s) over the period specified. |
frdrpc.ThresholdRecommendationsRequest
Parameter |
Type |
Description |
rec_request |
CloseRecommendationRequest |
The parameters that are common to all close recommendations. |
threshold_value |
float |
The threshold that recommendations will be calculated based on. For uptime: ratio of uptime to observed lifetime beneath which channels will be recommended for closure. For revenue: revenue per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For incoming volume: The incoming volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For outgoing volume: The outgoing volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For total volume: The total volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. |
gRPC Enums
Metric
Name |
Value |
Description |
UNKNOWN |
0 |
|
UPTIME |
1 |
|
REVENUE |
2 |
|
INCOMING_VOLUME |
3 |
|
OUTGOING_VOLUME |
4 |
|
TOTAL_VOLUME |
5 |
|
EntryType
Name |
Value |
Description |
UNKNOWN |
0 |
|
LOCAL_CHANNEL_OPEN |
1 |
A channel opening transaction for a channel opened by our node. |
REMOTE_CHANNEL_OPEN |
2 |
A channel opening transaction for a channel opened by a remote node. |
CHANNEL_OPEN_FEE |
3 |
The on chain fee paid to open a channel. |
CHANNEL_CLOSE |
4 |
A channel closing transaction. |
RECEIPT |
5 |
Receipt of funds. On chain this reflects receives, off chain settlement of invoices. |
PAYMENT |
6 |
Payment of funds. On chain this reflects sends, off chain settlement of our payments. |
FEE |
7 |
Payment of fees. |
CIRCULAR_RECEIPT |
8 |
Receipt of a payment to ourselves. |
FORWARD |
9 |
A forward through our node. |
FORWARD_FEE |
10 |
Fees earned from forwarding. |
CIRCULAR_PAYMENT |
11 |
Sending of a payment to ourselves. |
CIRCULAR_FEE |
12 |
The fees paid to send an off chain payment to ourselves. |
SWEEP |
13 |
A transaction that sweeps funds back into our wallet's control. |
SWEEP_FEE |
14 |
The amount of fees paid for a sweep transaction. |
CHANNEL_CLOSE_FEE |
15 |
The fees paid to close a channel. |
FiatBackend
FiatBackend is the API endpoint to be used for any fiat related queries.
Name |
Value |
Description |
UNKNOWN_FIATBACKEND |
0 |
|
COINCAP |
1 |
Use the CoinCap API for fiat price information. This API is reached through the following URL: https://api.coincap.io/v2/assets/bitcoin/history |
COINDESK |
2 |
Use the CoinDesk API for fiat price information. This API is reached through the following URL: https://api.coindesk.com/v1/bpi/historical/close.json |
CUSTOM |
3 |
Use custom price data provided in a CSV file for fiat price information. |
COINGECKO |
4 |
Use the CoinGecko API for fiat price information. This API is reached through the following URL: https://api.coingecko.com/api/v3/coins/bitcoin/market_chart |
Granularity
Granularity describes the aggregation level at which the Bitcoin price should be queried. Note that setting lower levels of granularity may require more queries to the fiat backend.
Name |
Value |
Description |
UNKNOWN_GRANULARITY |
0 |
|
MINUTE |
1 |
|
FIVE_MINUTES |
2 |
|
FIFTEEN_MINUTES |
3 |
|
THIRTY_MINUTES |
4 |
|
HOUR |
5 |
|
SIX_HOURS |
6 |
|
TWELVE_HOURS |
7 |
|
DAY |
8 |
|
Faraday REST API Reference
Welcome to the gRPC API reference documentation for Faraday.
Faraday is an external service intended to be run in conjunction with the lnd
implementation of the Lightning Network. It queries LND for information about its existing
channels and provides channel close recommendations if channels are under-performing.
This site features the API documentation for shell script (CLI), Python and
JavaScript clients in order to communicate with a local faraday
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
ddd3cd123e628b6ef32b70c5ae9577ddd774d941
.
/v1/faraday/closereport
$ curl -X GET http://localhost:8082/v1/faraday/closereport
{
"channel_point": <string>,
"channel_initiator": <boolean>,
"close_type": <string>,
"close_txid": <string>,
"open_fee": <string>,
"close_fee": <string>,
}
>>> import base64, json, requests
>>> url = 'http://localhost:8082/v1/faraday/closereport'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"channel_point": <string>,
"channel_initiator": <boolean>,
"close_type": <string>,
"close_txid": <string>,
"open_fee": <string>,
"close_fee": <string>,
}
const request = require('request');
let options = {
url: 'http://localhost:8082/v1/faraday/closereport',
json: true
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "channel_point": <string>,
// "channel_initiator": <boolean>,
// "close_type": <string>,
// "close_txid": <string>,
// "open_fee": <string>,
// "close_fee": <string>,
// }
GET /v1/faraday/closereport
Get a channel close report for a specific channel.
Example request: http://localhost:8466/v1/faraday/closereport
Field |
Type |
Placement |
Description |
channel_point |
string |
query |
The funding outpoint of the channel the report should be created for, formatted txid:outpoint. |
Response
Field |
Type |
Description |
channel_point |
string |
The funding outpoint of the channel. |
channel_initiator |
boolean |
True if we opened the channel, false if the remote peer did. |
close_type |
string |
The type of close that resolved this channel. |
close_txid |
string |
The transaction id of the close transaction that confirmed on chain. |
open_fee |
string |
The fee we paid on chain to open this channel in satoshis, note that this field will be zero if the remote party paid. |
close_fee |
string |
The fee we paid on chain for the close transaction in staoshis, note that this field will be zero if the remote party paid. |
/v1/faraday/exchangerate
$ curl -X GET http://localhost:8082/v1/faraday/exchangerate
{
"rates": <array frdrpcExchangeRate>,
}
>>> import base64, json, requests
>>> url = 'http://localhost:8082/v1/faraday/exchangerate'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"rates": <array frdrpcExchangeRate>,
}
const request = require('request');
let options = {
url: 'http://localhost:8082/v1/faraday/exchangerate',
json: true
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "rates": <array frdrpcExchangeRate>,
// }
GET /v1/faraday/exchangerate
frcli: Get fiat prices for btc.
Example request: http://localhost:8466/v1/faraday/exchangerate
Field |
Type |
Placement |
Description |
timestamps |
array |
query |
A set of timestamps for which we want the bitcoin price. |
granularity |
string |
query |
The level of granularity at which we want the bitcoin price to be quoted. |
fiat_backend |
string |
query |
The api to be used for fiat related queries. - COINCAP: Use the CoinCap API for fiat price information. This API is reached through the following URL: https://api.coincap.io/v2/assets/bitcoin/history - COINDESK: Use the CoinDesk API for fiat price information. This API is reached through the following URL: https://api.coindesk.com/v1/bpi/historical/close.json - CUSTOM: Use custom price data provided in a CSV file for fiat price information. - COINGECKO: Use the CoinGecko API for fiat price information. This API is reached through the following URL: https://api.coingecko.com/api/v3/coins/bitcoin/market_chart |
Response
/v1/faraday/insights
$ curl -X GET http://localhost:8082/v1/faraday/insights
{
"channel_insights": <array frdrpcChannelInsight>,
}
>>> import base64, json, requests
>>> url = 'http://localhost:8082/v1/faraday/insights'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"channel_insights": <array frdrpcChannelInsight>,
}
const request = require('request');
let options = {
url: 'http://localhost:8082/v1/faraday/insights',
json: true
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "channel_insights": <array frdrpcChannelInsight>,
// }
GET /v1/faraday/insights
frcli: insights
List currently open channel with routing and uptime information.
Example request: http://localhost:8466/v1/faraday/insights
This request has no parameters.
Response
/v1/faraday/nodeaudit
$ curl -X GET http://localhost:8082/v1/faraday/nodeaudit
{
"reports": <array frdrpcReportEntry>,
}
>>> import base64, json, requests
>>> url = 'http://localhost:8082/v1/faraday/nodeaudit'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"reports": <array frdrpcReportEntry>,
}
const request = require('request');
let options = {
url: 'http://localhost:8082/v1/faraday/nodeaudit',
json: true
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "reports": <array frdrpcReportEntry>,
// }
GET /v1/faraday/nodeaudit
Get a report of your node's activity over a period.
Example request: http://localhost:8466/v1/faraday/nodeaudit
Field |
Type |
Placement |
Description |
start_time |
string |
query |
The unix time from which to produce the report, inclusive. |
end_time |
string |
query |
The unix time until which to produce the report, exclusive. |
disable_fiat |
boolean |
query |
Set to generate a report without conversion to fiat. If set, fiat values will display as 0. |
granularity |
string |
query |
The level of granularity at which we wish to produce fiat prices. |
fiat_backend |
string |
query |
The api to be used for fiat related queries. - COINCAP: Use the CoinCap API for fiat price information. This API is reached through the following URL: https://api.coincap.io/v2/assets/bitcoin/history - COINDESK: Use the CoinDesk API for fiat price information. This API is reached through the following URL: https://api.coindesk.com/v1/bpi/historical/close.json - CUSTOM: Use custom price data provided in a CSV file for fiat price information. - COINGECKO: Use the CoinGecko API for fiat price information. This API is reached through the following URL: https://api.coingecko.com/api/v3/coins/bitcoin/market_chart |
Response
/v1/faraday/outliers
$ curl -X GET http://localhost:8082/v1/faraday/outliers/{rec_request.metric}
{
"total_channels": <int32>,
"considered_channels": <int32>,
"recommendations": <array frdrpcRecommendation>,
}
>>> import base64, json, requests
>>> url = 'http://localhost:8082/v1/faraday/outliers/{rec_request.metric}'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"total_channels": <int32>,
"considered_channels": <int32>,
"recommendations": <array frdrpcRecommendation>,
}
const request = require('request');
let options = {
url: 'http://localhost:8082/v1/faraday/outliers/{rec_request.metric}',
json: true
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "total_channels": <int32>,
// "considered_channels": <int32>,
// "recommendations": <array frdrpcRecommendation>,
// }
GET /v1/faraday/outliers/{rec_request.metric}
frcli: outliers
Get close recommendations for currently open channels based on whether it is an outlier.
Example request: http://localhost:8466/v1/faraday/outliers/REVENUE?rec_request.minimum_monitored=123
Field |
Type |
Placement |
Description |
rec_request.metric |
string |
path |
The data point base close recommendations on. Available options are: Uptime: ratio of channel peer's uptime to the period they have been monitored to. Revenue: the revenue that the channel has produced per block that its funding transaction has been confirmed for. |
rec_request.minimum_monitored |
string |
query |
The minimum amount of time in seconds that a channel should have been monitored by lnd to be eligible for close. This value is in place to protect against closing of newer channels. |
outlier_multiplier |
number |
query |
The number of inter-quartile ranges a value needs to be beneath the lower quartile/ above the upper quartile to be considered a lower/upper outlier. Lower values will be more aggressive in recommending channel closes, and upper values will be more conservative. Recommended values are 1.5 for aggressive recommendations and 3 for conservative recommendations. |
Response
Field |
Type |
Description |
total_channels |
int32 |
The total number of channels, before filtering out channels that are not eligible for close recommendations. |
considered_channels |
int32 |
The number of channels that were considered for close recommendations. |
recommendations |
array frdrpcRecommendation |
A set of channel close recommendations. The absence of a channel in this set implies that it was not considered for close because it did not meet the criteria for close recommendations (it is private, or has not been monitored for long enough). |
/v1/faraday/revenue
$ curl -X GET http://localhost:8082/v1/faraday/revenue
{
"reports": <array frdrpcRevenueReport>,
}
>>> import base64, json, requests
>>> url = 'http://localhost:8082/v1/faraday/revenue'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"reports": <array frdrpcRevenueReport>,
}
const request = require('request');
let options = {
url: 'http://localhost:8082/v1/faraday/revenue',
json: true
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "reports": <array frdrpcRevenueReport>,
// }
GET /v1/faraday/revenue
frcli: revenue
Get a pairwise revenue report for a channel.
Example request: http://localhost:8466/v1/faraday/revenue
Field |
Type |
Placement |
Description |
chan_points |
array |
query |
The funding transaction outpoints for the channels to generate a revenue report for. If this is empty, it will be generated for all open and closed channels. Channel funding points should be expressed with the format fundingTxID:outpoint. |
start_time |
string |
query |
Start time is beginning of the range over which the report will be generated, expressed as unix epoch offset in seconds. |
end_time |
string |
query |
End time is end of the range over which the report will be generated, expressed as unix epoch offset in seconds. |
Response
Field |
Type |
Description |
reports |
array frdrpcRevenueReport |
Reports is a set of pairwise revenue report generated for the channel(s) over the period specified. |
/v1/faraday/threshold
$ curl -X GET http://localhost:8082/v1/faraday/threshold/{rec_request.metric}
{
"total_channels": <int32>,
"considered_channels": <int32>,
"recommendations": <array frdrpcRecommendation>,
}
>>> import base64, json, requests
>>> url = 'http://localhost:8082/v1/faraday/threshold/{rec_request.metric}'
>>> r = requests.get(url, verify=cert_path)
>>> print(r.json())
{
"total_channels": <int32>,
"considered_channels": <int32>,
"recommendations": <array frdrpcRecommendation>,
}
const request = require('request');
let options = {
url: 'http://localhost:8082/v1/faraday/threshold/{rec_request.metric}',
json: true
};
request.get(options, function(error, response, body) {
console.log(body);
});
// Console output:
// {
// "total_channels": <int32>,
// "considered_channels": <int32>,
// "recommendations": <array frdrpcRecommendation>,
// }
GET /v1/faraday/threshold/{rec_request.metric}
frcli: threshold
Get close recommendations for currently open channels based whether they are below a set threshold.
Example request: http://localhost:8466/v1/faraday/threshold/UPTIME?rec_request.minimum_monitored=123
Field |
Type |
Placement |
Description |
rec_request.metric |
string |
path |
The data point base close recommendations on. Available options are: Uptime: ratio of channel peer's uptime to the period they have been monitored to. Revenue: the revenue that the channel has produced per block that its funding transaction has been confirmed for. |
rec_request.minimum_monitored |
string |
query |
The minimum amount of time in seconds that a channel should have been monitored by lnd to be eligible for close. This value is in place to protect against closing of newer channels. |
threshold_value |
number |
query |
The threshold that recommendations will be calculated based on. For uptime: ratio of uptime to observed lifetime beneath which channels will be recommended for closure. For revenue: revenue per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For incoming volume: The incoming volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For outgoing volume: The outgoing volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. For total volume: The total volume per block that capital has been committed to the channel beneath which channels will be recommended for closure. This value is provided per block so that channels that have been open for different periods of time can be compared. |
Response
Field |
Type |
Description |
total_channels |
int32 |
The total number of channels, before filtering out channels that are not eligible for close recommendations. |
considered_channels |
int32 |
The number of channels that were considered for close recommendations. |
recommendations |
array frdrpcRecommendation |
A set of channel close recommendations. The absence of a channel in this set implies that it was not considered for close because it did not meet the criteria for close recommendations (it is private, or has not been monitored for long enough). |
REST Messages
frdrpcBitcoinPrice
Field |
Type |
Description |
price |
string |
The price of 1 BTC, expressed in USD. |
price_timestamp |
string |
The timestamp for this price price provided. |
currency |
string |
The currency that the price is denoted in. |
frdrpcChannelInsight
Field |
Type |
Description |
chan_point |
string |
The outpoint of the channel's funding transaction. |
monitored_seconds |
string |
The amount of time in seconds that we have monitored the channel peer's uptime for. |
uptime_seconds |
string |
The amount of time in seconds that the channel peer has been online over the period it has been monitored for. |
volume_incoming_msat |
string |
The volume, in millisatoshis, that has been forwarded with this channel as the incoming channel. |
volume_outgoing_msat |
string |
The volume, in millisatoshis, that has been forwarded with this channel as the outgoing channel. |
fees_earned_msat |
string |
The total fees earned by this channel for its participation in forwards, expressed in millisatoshis. Note that we attribute fees evenly across incoming and outgoing channels. |
confirmations |
int64 |
The number of confirmations the funding transaction has. |
private |
boolean |
True if the channel is private. |
frdrpcChannelInsightsResponse
frdrpcCloseRecommendationRequest
Field |
Type |
Description |
minimum_monitored |
string |
The minimum amount of time in seconds that a channel should have been monitored by lnd to be eligible for close. This value is in place to protect against closing of newer channels. |
metric |
CloseRecommendationRequestMetric |
The data point base close recommendations on. Available options are: Uptime: ratio of channel peer's uptime to the period they have been monitored to. Revenue: the revenue that the channel has produced per block that its funding transaction has been confirmed for. |
frdrpcCloseRecommendationsResponse
Field |
Type |
Description |
total_channels |
int32 |
The total number of channels, before filtering out channels that are not eligible for close recommendations. |
considered_channels |
int32 |
The number of channels that were considered for close recommendations. |
recommendations |
array frdrpcRecommendation |
A set of channel close recommendations. The absence of a channel in this set implies that it was not considered for close because it did not meet the criteria for close recommendations (it is private, or has not been monitored for long enough). |
frdrpcCloseReportResponse
Field |
Type |
Description |
channel_point |
string |
The funding outpoint of the channel. |
channel_initiator |
boolean |
True if we opened the channel, false if the remote peer did. |
close_type |
string |
The type of close that resolved this channel. |
close_txid |
string |
The transaction id of the close transaction that confirmed on chain. |
open_fee |
string |
The fee we paid on chain to open this channel in satoshis, note that this field will be zero if the remote party paid. |
close_fee |
string |
The fee we paid on chain for the close transaction in staoshis, note that this field will be zero if the remote party paid. |
frdrpcCustomCategory
Field |
Type |
Description |
name |
string |
The name for the custom category which will contain all transactions that are labelled with a string matching one of the regexes provided in label identifiers. |
on_chain |
boolean |
Set to true to apply this category to on chain transactions. Can be set in conjunction with off_chain to apply the category to all transactions. |
off_chain |
boolean |
Set to true to apply this category to off chain transactions. Can be set in conjunction with on_chain to apply the category to all transactions. |
label_patterns |
array string |
A set of regular expressions which identify transactions by their label as belonging in this custom category. If a label matches any single regex in the set, it is considered to be in the category. These expressions will be matched against various labels that are present in lnd: on chain transactions will be matched against their label field, off chain receipts will be matched against their memo. At present, there is no way to match forwards or off chain payments. These expressions must be unique across custom categories, otherwise faraday will not be able to identify which custom category a transaction belongs in. |
frdrpcExchangeRate
Field |
Type |
Description |
timestamp |
string |
timestamp is the timestamp of the original request made. |
btc_price |
frdrpcBitcoinPrice |
Price is the bitcoin price approximation for the timestamp queried. Note that this value has its own timestamp because we are not guaranteed to get price points for the exact timestamp that was queried. |
frdrpcExchangeRateResponse
frdrpcNodeAuditResponse
frdrpcPairReport
Field |
Type |
Description |
amount_outgoing_msat |
string |
Amount outgoing msat is the amount in millisatoshis that arrived on the pair channel to be forwarded onwards by our channel. |
fees_outgoing_msat |
string |
Fees outgoing is the amount of fees in millisatoshis that we attribute to the channel for its role as the outgoing channel in forwards. |
amount_incoming_msat |
string |
Amount incoming msat is the amount in millisatoshis that arrived on our channel to be forwarded onwards by the pair channel. |
fees_incoming_msat |
string |
Fees incoming is the amount of fees in millisatoshis that we attribute to the channel for its role as the incoming channel in forwards. |
frdrpcRecommendation
Field |
Type |
Description |
chan_point |
string |
The channel point [funding txid: outpoint] of the channel being considered for close. |
value |
float |
The value of the metric that close recommendations were based on. |
recommend_close |
boolean |
A boolean indicating whether we recommend closing the channel. |
frdrpcReportEntry
Field |
Type |
Description |
timestamp |
string |
The unix timestamp of the event. |
on_chain |
boolean |
Whether the entry occurred on chain or off chain. |
amount |
string |
The amount of the entry, expressed in millisatoshis. |
credit |
boolean |
Whether the entry is a credit or a debit. |
asset |
string |
The asset affected by the entry. |
type |
frdrpcEntryType |
The kind of activity that this entry represents. |
custom_category |
string |
This field will be populated for entry type custom, and represents the name of a custom category that the report was produced with. |
txid |
string |
The transaction id of the entry. |
fiat |
string |
The fiat amount of the entry's amount in the currency specified in the btc_price field. |
reference |
string |
A unique identifier for the entry, if available. |
note |
string |
An additional note for the entry, providing additional context. |
btc_price |
frdrpcBitcoinPrice |
The bitcoin price and timestamp used to calculate our fiat value. |
frdrpcRevenueReport
Field |
Type |
Description |
target_channel |
string |
Target channel is the channel that the report is generated for; incoming fields in the report mean that this channel was the incoming channel, and the pair as the outgoing, outgoing fields mean that this channel was the outgoing channel and the peer was the incoming channel. |
pair_reports |
object |
Pair reports maps the channel point of a peer that we generated revenue with to a report detailing the revenue. |
frdrpcRevenueReportResponse
Field |
Type |
Description |
reports |
array frdrpcRevenueReport |
Reports is a set of pairwise revenue report generated for the channel(s) over the period specified. |
protobufAny
Field |
Type |
Description |
type_url |
string |
|
value |
byte |
|
rpcStatus
REST Enums
CloseRecommendationRequestMetric
Name |
Value |
Description |
UNKNOWN |
0 |
|
UPTIME |
1 |
|
REVENUE |
2 |
|
INCOMING_VOLUME |
3 |
|
OUTGOING_VOLUME |
4 |
|
TOTAL_VOLUME |
5 |
|
frdrpcEntryType
Name |
Value |
Description |
UNKNOWN |
0 |
|
LOCAL_CHANNEL_OPEN |
1 |
|
REMOTE_CHANNEL_OPEN |
2 |
|
CHANNEL_OPEN_FEE |
3 |
|
CHANNEL_CLOSE |
4 |
|
RECEIPT |
5 |
|
PAYMENT |
6 |
|
FEE |
7 |
|
CIRCULAR_RECEIPT |
8 |
|
FORWARD |
9 |
|
FORWARD_FEE |
10 |
|
CIRCULAR_PAYMENT |
11 |
|
CIRCULAR_FEE |
12 |
|
SWEEP |
13 |
|
SWEEP_FEE |
14 |
|
CHANNEL_CLOSE_FEE |
15 |
|
frdrpcFiatBackend
Name |
Value |
Description |
UNKNOWN_FIATBACKEND |
0 |
|
COINCAP |
1 |
|
COINDESK |
2 |
|
CUSTOM |
3 |
|
COINGECKO |
4 |
|
frdrpcGranularity
Name |
Value |
Description |
UNKNOWN_GRANULARITY |
0 |
|
MINUTE |
1 |
|
FIVE_MINUTES |
2 |
|
FIFTEEN_MINUTES |
3 |
|
THIRTY_MINUTES |
4 |
|
HOUR |
5 |
|
SIX_HOURS |
6 |
|
TWELVE_HOURS |
7 |
|
DAY |
8 |
|
Other API References
This is the gRPC and REST API reference for the faraday
daemon. There are separate API reference documents for the
following daemons: