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:

• faraday.proto

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

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>,
//  }

gRPC Request: frdrpc.ChannelInsightsRequest

This request has no parameters.

gRPC Response: frdrpc.ChannelInsightsResponse

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>,
//  }

gRPC Request: frdrpc.CloseReportRequest

Parameter	Type	Description
channel_point	string	The funding outpoint of the channel the report should be created for, formatted txid:outpoint.

gRPC Response: 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.

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>,
//  }

gRPC Request: 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.

gRPC Response: frdrpc.ExchangeRateResponse

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>,
//  }

gRPC Request: 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.

gRPC Response: frdrpc.NodeAuditResponse

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>,
//  }

gRPC Request: 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.

gRPC Response: 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).

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>,
//  }

gRPC Request: 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.

gRPC Response: 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.

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>,
//  }

gRPC Request: 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 Response: 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).

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:

• faraday.swagger.json

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

/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

Field	Type	Description
rates	array frdrpcExchangeRate	Rates contains a set of exchange rates for the set of timestamps

/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

Field	Type	Description
channel_insights	array frdrpcChannelInsight	Insights for the set of currently open channels.

/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

Field	Type	Description
reports	array frdrpcReportEntry	On chain reports for the period queried.

/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

Field	Type	Description
channel_insights	array frdrpcChannelInsight	Insights for the set of currently open channels.

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

Field	Type	Description
rates	array frdrpcExchangeRate	Rates contains a set of exchange rates for the set of timestamps

frdrpcNodeAuditResponse

Field	Type	Description
reports	array frdrpcReportEntry	On chain reports for the period queried.

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

Field	Type	Description
code	int32
message	string
details	array protobufAny

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:

• LND API Reference
• Lightning Loop API Reference
• Lightning Pool API Reference