c13n RPC API
Services
ChannelService
ChannelService exposes endpoints pertaining to channel management.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| OpenChannel | 🔗 | 🔗 | Opens a channel to a node. Returns immediately after the funding transaction has been published, but does not wait for the channel to be considered open. |
ContactService
ContactService exposes endpoints pertaining to contacts.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetContacts | 🔗 | 🔗 | Lists all current contacts. Returns a list of all contacts currently in the database. |
| AddContact | 🔗 | 🔗 | Adds a node as a contact. Accepts a node and adds them as a contact in the database. |
| RemoveContactByID | 🔗 | 🔗 | Removes a contact. Accepts a contact id and removes it from the database. |
| RemoveContactByAddress | 🔗 | 🔗 | Removes a contact. Accepts a contact address and removes it from the database. |
DiscussionService
DiscussionService exposes functionality pertaining to discussion creation, deletion and history.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetDiscussions | 🔗 | 🔗 stream | Creates a unidirectional stream from server to client over which all discussions' info are sent. The stream terminates when all discussion info is transmitted. |
| GetDiscussionHistoryByID | 🔗 | 🔗 stream | Creates a unidirectional stream from server to client over which previously exchanged messages belonging to a specific discussion are sent. The stream terminates when all requested discussion messages are transmitted. |
| GetDiscussionStatistics | 🔗 | 🔗 | Calculates statistics about the requested discussion. |
| AddDiscussion | 🔗 | 🔗 | Adds a discussion to the database. |
| UpdateDiscussionLastRead | 🔗 | 🔗 | Updates a discussion's last read message. |
| RemoveDiscussion | 🔗 | 🔗 | Removes a discussion from the database. |
| Send | 🔗 | 🔗 | Sends a message. |
| Subscribe | 🔗 | 🔗 stream | Creates a unidirectional stream over which to be notified of all transmitted messages. |
MessageService
MessageService exposes functionality pertaining to message creation and exchange.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| EstimateMessage | 🔗 | 🔗 | Estimates the route and fees for the requested message. In case of failure (payment amount too large or small, payload too large), an empty response is returned. |
| SendMessage | 🔗 | 🔗 | Sends a message In case of failure (payment amount too large or small, payload too large), an empty response is returned. |
| SubscribeMessages | 🔗 | 🔗 stream | Creates a unidirectional stream from server to client over which all received messages are sent. The stream does not terminate until the client stops it. |
NodeInfoService
NodeInfoService exposes functionality pertaining to queries about node information.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetVersion | 🔗 | 🔗 | Returns version information about the current daemon. |
| GetSelfInfo | 🔗 | 🔗 | Returns info about the current underlying node. |
| GetSelfBalance | 🔗 | 🔗 | Returns the balance of the current underlying node. |
| GetNodes | 🔗 | 🔗 | Lists all nodes on the Lightning network. Returns a list of all nodes visible to the underlying Lightning node, including the address of the current node. Nodes with private channels are not visible if not directly connected to the underlying node. |
| SearchNodeByAddress | 🔗 | 🔗 | Searches for a Lighting node based on their Lightning address. Returns a list of all nodes with that address, which will be at most 1. The node must be visible from the underlying node. |
| SearchNodeByAlias | 🔗 | 🔗 | Searches for a Lightning node based on their Lightning alias. Returns a list of all nodes with that alias visible from the underlying node. |
| ConnectNode | 🔗 | 🔗 | Connects a node as a peer. |
PaymentService
PaymentService exposes payment and invoice functionality.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| CreateInvoice | 🔗 | 🔗 | Creates a new invoice. |
| LookupInvoice | 🔗 | 🔗 | Performs an invoice lookup. |
| Pay | 🔗 | 🔗 | Performs a payment. |
| SubscribeInvoices | 🔗 | 🔗 stream | Subscribes to invoice (final state) updates. |
| SubscribePayments | 🔗 | 🔗 stream | Subscribes to payment (final state) updates. |
| GetRoute | 🔗 | 🔗 | Attempts to find a route capable of carrying the requested amount to the destination. |
| GetInvoices | 🔗 | 🔗 stream | Retrieves invoices from the database. |
| GetPayments | 🔗 | 🔗 stream | Retrieves payments from the database. |
Messages
AddContactRequest
Corresponds to a request to add a node as a contact.
| Field | Type | Label | Description |
|---|---|---|---|
| contact | ContactInfo | The node to add as a contact. |
AddContactResponse
A AddContactResponse is received in response to an AddContact rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| contact | ContactInfo | The newly added contact's information. |
AddDiscussionRequest
Corresponds to a request to add a discussion to database.
| Field | Type | Label | Description |
|---|---|---|---|
| discussion | DiscussionInfo |
AddDiscussionResponse
An AddDiscussionResponse is received in response to an AddDiscussion rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| discussion | DiscussionInfo |
Chain
Represents a blockchain and network for a Lightning node.
| Field | Type | Label | Description |
|---|---|---|---|
| chain | string | The blockchain in use. | |
| network | string | The network a node is operating on. |
ConnectNodeRequest
Corresponds to a request to create a peer connection with a node.
| Field | Type | Label | Description |
|---|---|---|---|
| address | string | The address of the node to connect. | |
| hostport | string | The network location of the node. |
ConnectNodeResponse
A ConnectNodeResponse is received in response to a ConnectNode request.
ContactInfo
A message representing a contact of the application.
| Field | Type | Label | Description |
|---|---|---|---|
| node | NodeInfo | The node corresponding to the contact. | |
| id | uint64 | The contact id. | |
| display_name | string | A contact's chat nickname. |
CreateInvoiceRequest
Corresponds to an invoice creation request.
| Field | Type | Label | Description |
|---|---|---|---|
| memo | string | Memo of the invoice. | |
| amt_msat | uint64 | The invoice amount (in millisatoshi). | |
| expiry | int64 | Invoice expiry time (in seconds since creation). | |
| private | bool | Whether to include hints for private channels. |
CreateInvoiceResponse
A CreateInvoiceResponse is received in response to an invoice creation request.
| Field | Type | Label | Description |
|---|---|---|---|
| invoice | Invoice | The created invoice. |
DiscussionInfo
Represents the information for a specific discussion.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | The discussion id. | |
| participants | string | repeated | The list of participants in the discussion. |
| options | DiscussionOptions | The default options applicable for all discussion messages. | |
| last_read_msg_id | uint64 | The id of the last read message in the discussion. | |
| last_msg_id | uint64 | The id of the last discussion message. |
DiscussionOptions
DiscussionOptions represents the per-discussion options.
| Field | Type | Label | Description |
|---|---|---|---|
| fee_limit_msat | int64 | The maximum fee allowed for sending a message (in millisatoshi). If not set, the default fee limit, as defined in the app package, is used. |
|
| anonymous | bool | Whether to send as anonymous on this discussion. |
EstimateMessageRequest
Corresponds to a request to estimate a message.
| Field | Type | Label | Description |
|---|---|---|---|
| discussion_id | uint64 | The discussion id where the message is to be sent. | |
| payload | string | The message payload (as a string). | |
| amt_msat | int64 | The intended payment amount to the recipient of the message (in millisatoshi). | |
| options | MessageOptions | The message option overrides for the current message. |
EstimateMessageResponse
A EstimateMessageResponse is received in response to a EstimateMessage rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| success_prob | double | The probability of successful arrival of the message, as reported by the Lightning daemon's mission control. |
|
| message | Message | Contains the estimated route and fees for the requested message. |
GetContactsRequest
Corresponds to a request to list all contacts.
GetContactsResponse
A GetContactsResponse is received in response to a GetContacts rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| contacts | ContactInfo | repeated | The list of contacts in the database. |
GetDiscussionHistoryByIDRequest
Corresponds to a request to create a stream over which to receive previously exchanged messages of the identified discussion.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | The discussion id of interest. | |
| page_options | KeySetPageOptions | The pagination options of the request. |
GetDiscussionHistoryResponse
A GetDiscussionHistoryResponse is received in response to a GetHistory rpc call, and represents an exchanged message.
| Field | Type | Label | Description |
|---|---|---|---|
| message | Message | The exchanged message. |
GetDiscussionStatisticsRequest
Corresponds to a request for statistics about the requested discussion, identified by its id.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | The discussion id. |
GetDiscussionStatisticsResponse
A GetDiscussionStatisticsResponse is received in response to a GetDiscussionStatistics rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| amt_msat_sent | uint64 | The total amount sent in the discussion (in millisatoshi). | |
| amt_msat_received | uint64 | The total amount received in the discussion (in millisatoshi). | |
| amt_msat_fees | uint64 | The total amount of fees for sent messages in the discussion (in millisatoshi). | |
| messages_sent | uint64 | The total amount of sent messages in the discussion. | |
| messages_received | uint64 | The total amount of received messages in the discussion. |
GetDiscussionsRequest
Corresponds to a request to receive all discussion info.
GetDiscussionsResponse
A GetDiscussionsResponse is received in the stream returned in response to a GetDiscussions rpc call, and represents a discussion.
| Field | Type | Label | Description |
|---|---|---|---|
| discussion | DiscussionInfo |
GetInvoicesRequest
Corresponds to an invoice retrieval request.
| Field | Type | Label | Description |
|---|---|---|---|
| page_options | KeySetPageOptions | The pagination options of the request. |
GetNodesRequest
Corresponds to a request to list all nodes on the Lightning Network.
GetPaymentsRequest
Corresponds to a payment retrieval request.
| Field | Type | Label | Description |
|---|---|---|---|
| page_options | KeySetPageOptions | The pagination options of the request. |
HopHint
Represents a hop hint.
| Field | Type | Label | Description |
|---|---|---|---|
| pubkey | string | Public key of hop ingress node. | |
| chan_id | uint64 | The short channel id of the channel to be used for the hop. | |
| fee_base_msat | uint32 | The base fee of the channel (in millisatoshi). | |
| fee_rate | uint32 | The fee rate of the channel (in microsatoshi/sat). | |
| cltv_expiry_delta | uint32 | The timelock delta of the channel. |
Invoice
Represents an Lightning network invoice.
| Field | Type | Label | Description |
|---|---|---|---|
| memo | string | The invoice memo. | |
| hash | string | The preimage hash. | |
| preimage | string | The invoice preimage. | |
| payment_request | string | The payment request of the invoice. | |
| value_msat | uint64 | The value (amount requested) of the invoice (in millisatoshi). | |
| amt_paid_msat | uint64 | The amount paid to the invoice (in millisatoshi). | |
| created_timestamp | google.protobuf.Timestamp | The time the invoice was created. | |
| settled_timestamp | google.protobuf.Timestamp | The time the invoice was settled. | |
| expiry | int64 | The invoice expiry (in seconds since creation time). | |
| private | bool | Whether the invoice contains hints for private channels. | |
| route_hints | RouteHint | repeated | Invoice route hints. |
| state | InvoiceState | The invoice state. | |
| add_index | uint64 | The add index of the invoice. | |
| settle_index | uint64 | The settle index of the invoice. | |
| invoice_htlcs | InvoiceHTLC | repeated | The set of HTLCs paying to the invoice. |
InvoiceHTLC
Represents an HTLC paying to an invoice.
| Field | Type | Label | Description |
|---|---|---|---|
| chan_id | uint64 | The short channel id of the channel the HTLC was arrived. | |
| amt_msat | uint64 | The amount of this HTLC (in millisatoshi). | |
| state | InvoiceHTLCState | State of the HTLC. | |
| accept_timestamp | google.protobuf.Timestamp | HTLC accept timestamp. | |
| resolve_timestamp | google.protobuf.Timestamp | HTLC resolve timestamp. | |
| expiry_height | int32 | Block height at which this HTLC expires. |
KeySetPageOptions
Corresponds to pagination parameters for requests. Represents a request for page_size elements, terminating with the element with id last_id. If reverse is true, the returned elements end with last_id.
| Field | Type | Label | Description |
|---|---|---|---|
| last_id | uint64 | The id of the first element of the requested range. | |
| page_size | int64 | The number of elements to return. | |
| reverse | bool | Whether the range starts or ends with last_id element. |
LookupInvoiceRequest
Corresponds to an invoice lookup request.
| Field | Type | Label | Description |
|---|---|---|---|
| pay_req | string | Payment Request |
LookupInvoiceResponse
A LookupResponse is received in response to an invoice lookup request.
| Field | Type | Label | Description |
|---|---|---|---|
| invoice | Invoice | The returned invoice. |
Message
Represents a message sent over the Lightning network.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | The unique id of the message. | |
| discussion_id | uint64 | The discussion id this message is associated with. | |
| sender | string | The Lightning address of the sender node. | |
| receiver | string | Deprecated. The Lightning address of the receiver node. | |
| sender_verified | bool | Whether the message sender was verified. | |
| payload | string | The message payload. | |
| amt_msat | int64 | The amount paid over this message (in millisatoshi). | |
| total_fees_msat | int64 | Deprecated. The total routing fees paid for this message across all routes (in millisatoshi). This field is meaningful only for sent and estimated messages. |
|
| sent_timestamp | google.protobuf.Timestamp | The time the message was sent. | |
| received_timestamp | google.protobuf.Timestamp | The time the message was received. | |
| payment_routes | PaymentRoute | repeated | Deprecated. The routes that fulfilled this message. This field is meaningful only for sent and estimated messages. |
| preimage | string | Deprecated. The preimage belonging to the associated payment. This field is only meaningful for received messages and messages sent successfully to non-group discussions. |
|
| pay_req | string | Deprecated. The payment request this message was paid to. If empty, corresponds to a spontaneous payment. |
|
| payments | Payments | ||
| invoice | Invoice |
MessageOptions
Represents messaging options.
| Field | Type | Label | Description |
|---|---|---|---|
| fee_limit_msat | int64 | The maximum fee allowed for a message (in millisatoshi). | |
| anonymous | bool | Whether to include the sender address when sending a message. |
NodeInfo
A message representing a node on the Lightning network.
| Field | Type | Label | Description |
|---|---|---|---|
| alias | string | A node's Lightning alias. | |
| address | string | A node's Lightning address. |
NodeInfoResponse
A NodeInfoResponse is received in response to a node query.
It contains all visible nodes corresponding to the query.
| Field | Type | Label | Description |
|---|---|---|---|
| nodes | NodeInfo | repeated | The list of Lightning nodes matching the query. |
OpenChannelRequest
Corresponds to a request to open a channel.
| Field | Type | Label | Description |
|---|---|---|---|
| address | string | The address of the node to open a channel to. | |
| amt_msat | uint64 | The total amount to be committed to the channel (in millisatoshi). | |
| push_amt_msat | uint64 | The amount to be sent to the other party (in millisatoshi). | |
| min_input_confs | int32 | The minimum number of confirmations each input of the channel funding transaction must have. In case of a negative value being provided, unconfirmed funds can be used. |
|
| target_confirmation_block | uint32 | The number of blocks the funding transaction should confirm by. Used for fee estimation. |
|
| sat_per_vbyte | uint64 | The fee rate (satoshis per virtual byte) the funding transaction should cost. |
OpenChannelResponse
An OpenChannelResponse is received in response to an OpenChannel call.
| Field | Type | Label | Description |
|---|---|---|---|
| funding_txid | string | The channel funding transaction. | |
| output_index | uint32 | The output index of the funding transaction. |
PayRequest
Corresponds to a pay request.
| Field | Type | Label | Description |
|---|---|---|---|
| pay_req | string | The payment request to pay to. | |
| address | string | The address to pay to. | |
| amt_msat | uint64 | The payment amount (in millisatoshi). | |
| options | PaymentOptions | The payment options. |
PayResponse
A PayResponse is received in response to a pay request.
| Field | Type | Label | Description |
|---|---|---|---|
| payment | Payment | The returned payment. |
Payment
Represents a Lightning network payment.
| Field | Type | Label | Description |
|---|---|---|---|
| hash | string | The payment hash of the payment. | |
| preimage | string | The preimage of the payment hash. | |
| amt_msat | uint64 | The payment amount. | |
| created_timestamp | google.protobuf.Timestamp | The time the payment was created. | |
| resolved_timestamp | google.protobuf.Timestamp | The time the payment was finalized. | |
| pay_req | string | The fulfilled payment request (if any). | |
| state | PaymentState | The payment state. | |
| payment_index | uint64 | The payment index. | |
| HTLCs | PaymentHTLC | repeated | The payment HTLCs. |
PaymentHTLC
Represents an HTLC attempt of a payment.
| Field | Type | Label | Description |
|---|---|---|---|
| route | PaymentRoute | The route of the HTLC. | |
| attempt_timestamp | google.protobuf.Timestamp | The time the HTLC was sent. | |
| resolve_timestamp | google.protobuf.Timestamp | The time the HTLC was resolved. | |
| state | HTLCState | The HTLC state. | |
| preimage | string | The preimage used to settle the HTLC. |
PaymentHop
Represents a hop of a route of a message.
| Field | Type | Label | Description |
|---|---|---|---|
| chan_id | uint64 | The channel id. | |
| hop_address | string | The address of the hop node. | |
| amt_to_forward_msat | int64 | The amount to be forwarded by the hop (in millisatoshi). | |
| fee_msat | int64 | The fee to be paid to the hop for forwarding the message (in millisatoshi). |
PaymentOptions
PaymentOptions represents the payment's options.
| Field | Type | Label | Description |
|---|---|---|---|
| fee_limit_msat | int64 | The maximum fee allowed for sending a payment. |
PaymentRoute
Represents a route fulfilling a payment HTLC.
| Field | Type | Label | Description |
|---|---|---|---|
| hops | PaymentHop | repeated | The list of hops for this route. |
| total_timelock | uint32 | The total timelock of the route. | |
| route_amt_msat | int64 | The amount sent via this route, disregarding the route fees (in millisatoshi). | |
| route_fees_msat | int64 | The fees paid for this route (in millisatoshi). |
Payments
Represents a list of payments.
| Field | Type | Label | Description |
|---|---|---|---|
| payments | Payment | repeated | The list of payments fulfilling a message. |
RemoveContactByAddressRequest
Corresponds to a request to remove a contact.
| Field | Type | Label | Description |
|---|---|---|---|
| address | string | The Lightning address of the contact to remove. |
RemoveContactByIDRequest
Corresponds to a request to remove a contact.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | The id of the contact to remove. |
RemoveContactResponse
A RemoveContactResponse is received in response to a RemoveContactBy* rpc call.
RemoveDiscussionRequest
Corresponds to a request to remove a discussion.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 | The id of the discussion to remove. |
RemoveDiscussionResponse
A RemoveDiscussionResponse is received in response to a RemoveDiscussion rpc call.
RouteHint
Represents a route hint for assistance in invoice payment.
| Field | Type | Label | Description |
|---|---|---|---|
| hop_hints | HopHint | repeated | A chain of hop hints that can reach the desetination. |
RouteRequest
Corresponds to a route discovery request.
| Field | Type | Label | Description |
|---|---|---|---|
| pay_req | string | The payment request to pay to. | |
| address | string | The address to pay to. | |
| amt_msat | uint64 | The payment amount (in millisatoshi). | |
| options | PaymentOptions | The payment options. |
RouteResponse
A RouteResponse is received in response to a route discovery request.
| Field | Type | Label | Description |
|---|---|---|---|
| route | PaymentRoute | A route that can fulfil the requested payment. |
SearchNodeByAddressRequest
Corresponds to a node query based on node address.
| Field | Type | Label | Description |
|---|---|---|---|
| address | string | The node address to search. |
SearchNodeByAliasRequest
Corresponds to a node query based on node alias.
| Field | Type | Label | Description |
|---|---|---|---|
| alias | string | The node alias substring to search. |
SelfBalanceRequest
Corresponds to a query to retrieve the balance of the underlying lightning node.
SelfBalanceResponse
A SelfBalanceResponse is received in response to a GetSelfBalance rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| wallet_confirmed_sat | int64 | The confirmed balance of the node's wallet (in satoshi). | |
| wallet_unconfirmed_sat | int64 | The unconfirmed balance of the node's wallet (in satoshi). | |
| channel_local_msat | uint64 | The local balance available across all open channels (in millisatoshi). | |
| channel_remote_msat | uint64 | The remote balance available across all open channels (in millisatoshi). | |
| pending_open_local_msat | uint64 | The local balance in pending open channels (in millisatoshi). | |
| pending_open_remote_msat | uint64 | The remote balance in pending open channels (in millisatoshi). | |
| unsettled_local_msat | uint64 | The local balance unsettled across all open channels (in millisatoshi). | |
| unsettled_remote_msat | uint64 | The remote balance unsettled across all open channels (in millisatoshi). |
SelfInfoRequest
Correponds to a query to retrieve the information of the underlying lightning node.
SelfInfoResponse
A SelfInfoResponse is received in response to a GetSelfInfo rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| info | NodeInfo | General node information about the current node. | |
| chains | Chain | repeated | A list of chain networks the node is operating on. |
SendMessageRequest
Corresponds to a request to send a message.
| Field | Type | Label | Description |
|---|---|---|---|
| discussion_id | uint64 | The discussion id where the message is to be sent. | |
| payload | string | The message payload (as a string). | |
| amt_msat | int64 | The intended payment amount to the recipient of the message (in millisatoshi). | |
| pay_req | string | A payment request (invoice) to pay to. If empty, a spontaneous message is sent. If specified, discussion_id is not used and should not be specified. Instead, the message will be sent to the discussion associated with the recipient specified by the the payment request (which will be created if it does not exist). The discussion_id will be returned in the response. |
|
| options | MessageOptions | The message option overrides for the current message. |
SendMessageResponse
A SendMessageResponse is received in response to a SendMessage rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| sent_message | Message | The sent message. |
SendRequest
Represents a request to send a message.
| Field | Type | Label | Description |
|---|---|---|---|
| discussion_id | uint64 | The discussion where the message is to be sent. | |
| pay_req | string | The payment request to fulfil. If empty, a spontaneous message is sent. A discussion with the recipient node will be created if it does not exist. |
|
| amt_msat | int64 | The intended amount to be used for payment to each recipient. | |
| payload | string | The message payload. | |
| options | MessageOptions | The message options for the current message (overriding any discussion options). |
SendResponse
A SendResponse is received in response to a Send rpc call.
| Field | Type | Label | Description |
|---|---|---|---|
| sent_message | Message | The sent message. |
SubscribeInvoicesRequest
Corresponds to a subscription request for invoice updates.
SubscribeMessageRequest
Corresponds to a request to create a stream over which to be notified of received messages.
SubscribeMessageResponse
A SubscribeMessageResponse is received in the stream returned in response to a SubscribeMessages rpc call, and represents a received message.
| Field | Type | Label | Description |
|---|---|---|---|
| received_message | Message | The received message. |
SubscribeMessagesRequest
Corresponds to a message subscription request.
SubscribePaymentsRequest
Corresponds to a subscription request for payment updates.
UpdateDiscussionLastReadRequest
Represents a request to update the last read discussion message.
| Field | Type | Label | Description |
|---|---|---|---|
| discussion_id | uint64 | The discussion id. | |
| last_read_msg_id | uint64 | The message id to mark as the last read. |
UpdateDiscussionResponse
An UpdateDiscussionResponse is returned in reponse to an UpdateDiscussionLastRead request.
Version
A message containing the current c13n version and build information.
| Field | Type | Label | Description |
|---|---|---|---|
| version | string | The semantic version of c13n. | |
| commit | string | The commit descriptor of the build. | |
| commit_hash | string | The commit hash of the build. |