LN+ API Documentation

Introduction

This document describes the operation of the LightningNetwork.Plus JSON API version 2.3. This API is designed to give programmatic access to all the core functionality required to authenticate, manage account information, create swaps, participate in swaps, give ratings, receive notifications and get node information.

Authentication

Some API calls require authentication. Authentication is done by first getting a message to be signed. Then, the user needs to sign the message with their Bitcoin Lightning Network node. Finally, both the message and the signature needs to be submitted in the API request. Requested messages can be used for up to 5 minutes, which is typically more than sufficient to make several API calls with the same message and signature. After the 5 minutes passed a new message needs to be requested for security purposes. Authentication provides the API with your pubkey so LN+ can associate you with your node.

Get Message

Request for a new message to be signed:

Example of code 200 success response:

{
  "message": "lnplus-api-575cd7b-28be7bf-3f4ac18",
  "expires_at": "2022-07-11T10:37:29.756Z"
}

Verify Signature

You can test if authenticating with a given node works as follows. Replace [message] with the message you received in Get Message API call and [signature] with the signature your node generated.

Example request with dummy parameters:

Example of code 200 success response:

{
  "node_found": true,
  "pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
  "node_url": "https://lightningnetwork.plus/nodes/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f"
}

Verification may fail for various reasons:

• The node is new and doesn't have channels in lightning network
• The node is not pulled from the gossip network by LN+ yet
• The message is older than 5 minutes
• The signature is not valid
• The node/user has been cancelled by user or banned by administrator

Swaps

Swaps are agreements between bitcoin lightning network node operators to open channels to each other. With the API you can request existing swaps with different conditions, create and delete swaps as follows.

Swap related API calls return a single swap or an array of swaps. Each swap contains a hash of swap details and an array with all the participants who already applied along with their essential information as described below.

Swap Fields

• id - The unique ID of the swap, important information for many API calls.
• web_url - The URL of the swap on LightningNetwork.plus website.
• image_url - The URL of the image that represents the swap on LN+.
• created_by_pubkey - The pubkey of the user's node who created the swap.
• created_at - When the swap was originally created.
• updated_at - When the swap was last edited. Swaps can't be edited once there are more than 1 applicants.
• starts - The time when the last applicant joined and channel opening started. Applicants have 48 hours from this time to open channels.
• ends - The time when the swap agreement ends and participants can close their channels without penalty.
• status - Swap status that can have three values: pending, opening, and completed.
• humanized_status - Same as status, but in form that is more understandable for a human user.
• capacity_sats - The swap capacity. The amount of funds participants need to have to participate and open channels.
• duration_months - The length of the swap agreement. The amount of time participants have to keep the channels open without incuring penalty.
• participant_max_count - The number of participants the swap can have. 2 means dual funded channel, 3 is a triangle, 4 is a square, 5 is a pentagon. No other values are allowed.
• rating_received - The rating received within this swap. The value null means no rating was received. The positive and negative values are self explanatory.
• rating_given - The rating given within this swap. The value null means no rating was given. The positive and negative values are self explanatory.
• participant_applied_count - The number of participants already applied to the swap.
• participant_waiting_for_count - The number of new participants required before the swap is full.
• participant_min_capacity_sats - The amount of sats a participant must at minimum have on their node to be allowed to join.
• participant_min_channels_count - The number of channels a participant must at minimum have on their node to be allowed to join.
• clearnet_connection_allowed - Clearnet connection support is required by the node joining the swap. True means yes, false means no.
• tor_connection_allowed - Tor connection support is required by the node joining the swap. True means yes, false means no.
• description - Any note or requirement swap creator added to the swap.
• prime - Boolean indicating whether the swap is marked as Prime. Only Pro Membership holding users can create Prime swaps. Only Prime Nodes can join prime swaps. Prime Nodes are nodes that have at least 10 positive (happy) ratings and maintain a 90% positive rating.
• pro - Created by a user with Pro Membership. Pro swaps are listed first in the Swaps index on the website.
• private - Swap privacy status. Private swaps can only be joined with a pin code that only swap creator has.
• platform - Lightning implementation platform of the participant that is allowed to join a given swap. Can be either "any", "lnd". LND stands for Lightning Network Daemon, which also assumes that the swap participant can use the BOS (Balance of Satoshis) tool alongside their LND node.
• comments_count - The number of comments posted on the swap.

Participant Field within a Swap

• participant_identifier - The participant's position within a swap. Values can be A, B, C, D, E.
• application_id - Unique identifier of the application. Not used by other API calls.
• applied_at - Time the participant first applied to the swap.
• updated_at - Time when the application has changed last. Typically shows the latest time when status changed.
• last_seen_at - Time when the participant was last seen.
• cancelled - True if the participant cancelled their own account. False otherwise.
• banned - True is LN+ banned the participant (a red flag). False otherwise.
• application_status - The status of the application. Can have three values: pending, opening, and completed.
• pubkey - The bitcoin lightning network node public key of the participant.
• address_1 - The first address of the LN node of the participant.
• address_2 - The second address of the LN node of the participant, if exists.
• alias - The alias of the participant's LN node.
• avatar - URL of the node profile image provided by the node operator and hosted on LN+'s CDN server.
• capacity_sats - The participant's LN node's total capacity.
• channels_count - The participant's LN node's total number of channels.
• lnplus_rank_number - The participant's LN node's Lightning Network Plus' rating. Can be a number between 1 to 10.
• lnplus_rank_name - The participant's LN node's Lightning Network Plus' name. The above rating named by metals.
• positive_ratings_count - The number of positive ratings the user received.
• negative_ratings_count - The number of negative ratings the user received.
• opening_to_participant_identifier - The swap identifier or the participant the user should be opening a channel to.
• receiving_from_participant_identifier - The swap identifier or the participant the user should be receiving a channel from.

Get Swaps

To get a list of swaps, you don't need to authenticate.

You can filter the requested swaps by status. If no parameter is provided, swaps of all statuses are returned. The valid swap statuses are the following:

• all - All swaps regardless of status
• pending - Newly opened swap that is waiting for participants to apply
• opening - Swap that has all the required participants and is in process of opening channels
• completed - Swap that has been completed

You can filter swaps by privacy status. If no, privacy status is provided, only public swaps are returned. The valid privacy statuses are the following:

• false - Public swaps, this is the default
• true - Private swaps

By default the last 50 swaps are returned. 50 is the maximum the API can provide, but it's more than sufficient because we usually have less than 30 swaps open for application at any time.

You can also include an optional platform parameter. By default the platform is any which returns all the swaps that any node implementation can apply to. You can specify the value lnd in order to retrieve only the swaps that LND/BOS nodes can apply to.

Simplest way to request swaps:

You can request swaps with parameters. Replace [status] with the swap status, [private] with true or false, and [limit] with the number of swaps you want returned (max 50).

Example request with parameters to get the latest pending (open for applications) public swap:

Example of code 200 success response:

[
  {
    "id": 9,
    "web_url": "https://lightningnetwork.plus/swaps/9",
    "image_url": "https://ds29si9p6n9nh.cloudfront.net/static/neon-pentagon-small-card.webp",
    "created_by_pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "created_at": "2022-07-09T13:29:51.145Z",
    "updated_at": "2022-07-09T13:29:51.145Z",
    "starts": null,
    "ends": null,
    "status": "pending",
    "humanized_status": "Open for Application",
    "capacity_sats": 500000,
    "duration_months": 13,
    "participant_max_count": 5,
    "participant_applied_count": 1,
    "participant_waiting_for_count": 4,
    "participant_min_capacity_sats": 10000000,
    "participant_min_channels_count": 10,
    "clearnet_connection_allowed": true,
    "tor_connection_allowed": true,
    "description": "Must have reasonable fees",
    "prime": true,
    "pro": false,
    "private": false,
    "platform": "any",
    "comments_count": 1,
    "participants": [
      {
        "participant_identifier": "A",
        "application_id": 23,
        "applied_at": "2022-07-09T13:29:51.167Z",
        "updated_at": "2022-07-09T13:29:51.167Z",
        "last_seen_at": "2022-07-09T13:29:51.167Z",
        "cancelled": false,
        "banned": false,
        "application_status": "pending",
        "pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
        "address_1": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f@mueqiomlbw6yq7smawrdogfzttmzkw4ouuovcyut7mmozowccb3bodqd.onion:9735",
        "address_2": null,
        "alias": "Admin",
        "avatar": "https://ds29si9p6n9nh.cloudfront.net/n98kzfrqyw97a2n9vrrlam3p7aye",
        "capacity_sats": 15100100,
        "channels_count": 5,
        "lnplus_rank_number": 3,
        "lnplus_rank_name": "Copper",
        "rating_received": "positive",
        "rating_given": null,
        "positive_ratings_count": 2,
        "negative_ratings_count": 0,
        "opening_to_participant_identifier": "B",
        "receiving_from_participant_identifier": "E"
      }
    ]
  }
]

The request may fail for the following reason:

• Swap parameters are not valid

Example of code 422 error response:

{
  "errors": {
    "swap": [
      "invalid status, allowed: all, pending, opening, completed"
    ]
  }
}

Get Swap

Request a single swap's details and its participants as follows:

Example request with parameters to get the latest pending (open for applications) public swap:

The API response is the same to the response received when requesting multiple swaps (see Get Swaps), except a single swap is returned.

The request may fail for various reasons:

• Swap id is not provided
• Swap with the id requested doesn't exist

Example of code 422 error response:

{
  "errors": {
    "swap": [
      "not found"
    ]
  }
}

Get Applicable Swaps

This API request returns all the swaps that the user can apply to based on their node parameters, such as total node capacity, the node's number of channels, and Prime status. Only nodes that have a Prime value of true can apply to swaps with a Prime value of true. In other words Prime nodes can apply to both Prime swaps and non-Prime swaps, but non-Prime nodes can only apply to non-Prime swaps. Prime nodes are nodes that have at least 10 positive ratings and maintain a 90% positive rating. If a user's node is already connected to another node in the swap, the swap is excluded from the response to avoid duplicate channels. This request is useful to determine if there are existing swaps a user can apply to with their node before creating a new one. Authentication is required. Only pending (open for application) swaps are returned and filters are not supported.

Request applicable swaps as follows:

The successful API response is the same to the response received when requesting multiple swaps (see Get Swaps).

Verification may fail if authentication is not successful (see Authentication).

Create Swap

This API request allows an authenticated user to create a new swap, and make them a participant at once. At minimum the following parameters need to be provided:

• message - Message required for authentication.
• signature - Signed message required for authentication.
• participants - Number of participants accepted to the swap. Valid values are: 2, 3, 4, 5. Recommended is 3 as it's the easiest to fill and doesn't require special tools to open channels. When setting the participants value to 2 (dual funded) the platform must be set to "lnd" and the can_use_bos flag must be set to true, because LND node and the BOS (Balance of Satoshis) tool is required to open dual funded channels.
• capacity - Size of the channels each participant will open in satoshis. Recommended minimum is 1 million satoshis. In case of a 2 participant swap (dual funded), specify only your side of the capacity, which is half of total channel capacity.
• duration - The length of the swap agreement in months. Recommended minimum is 3 months. Recommended value is 12.

The following optional parameters can also be provided:

• min_channels - The number of minimum channels swap participants must have in order to qualify to join the swap. Ensures only nodes of a certain size can join, but reduces the pool of potential participants.
• min_capacity - The amount of minimum total capacity swap participants must have in order to qualify to join the swap. Ensures only nodes of a certain size can join, but reduces the pool of potential participants.
• clearnet_connection_allowed - Clearnet connection support is required by the node joining the swap. True means yes, false means no. Defaults to true if not prodvided.
• tor_connection_allowed - Tor connection support is required by the node joining the swap. True means yes, false means no. Defaults to true if not prodvided.
• platform - If set to "lnd", only LND nodes can join the swap that can use the BOS (Balance of Satoshis) tool. Such LND swaps are opened with the BOS commands create-channel-group and join-channel-group for 3, 4, or 5 participant swaps and open-balanced-channel for the 2 (dual funded) participant swaps. Defaults to "any" if not provided.
• can_use_bos - This flag must be set to true only if the swap creator has an LND node and can use BOS. This flag is required to be set to true for LND swaps. Defaults to false if not provided.
• rules - Any other rules expressed in simple sentences. The text must be URL encoded. For example, spaces are represented as %20.

Create a swap as follows:

Example request to create a 1 million satoshi triangle with 6 month duration, and a simple text based rule:

The API response is the same to the response received when requesting multiple swaps (see Get Swaps), except a single swap is returned.

Swap creation may fail for various reasons:

• Authentication is not successful
• Swap parameters are invalid

Delete Swap

This API request allows an authenticated user to delete a new swap as long as the swap creator matches the user trying to delete the swap and no other participants have joined the swap yet. Besides authentication, only the swap id needs to be provided in the request.

Delete a swap as follows:

Example to delete swap with id 10:

The API response is the same to the response received when requesting multiple swaps (see Get Swaps), except a single swap is returned.

Swap creation may fail for various reasons:

• Authentication is not successful
• Swap id is not provided
• Swap with the id requested doesn't exist

Application

Application is the act of agreeing to participating in a swap. Users can manage their applications through the API.

Create Application

To apply to a swap you are required to authenticate and provide the id of the swap as follows, and set the value of can_do_bos to true if you want to join LND/BOS swaps (platform: "lnd"). The parameter "can_do_bos" is optional and defaults to false:

Example of an application to swap id 10:

The successful API call results in the same response received when requesting a swaps (see Get Swap) and it will include the new application.

The application may fail for various reasons:

• Authentication is not successful
• Swap id is not provided
• Swap with the id requested doesn't exist
• Swap is not in pending status
• User is not allowed to apply to the swap because of swap restrictions
• User already has an application on the given swap
• User is applying to an LND/BOS swap without setting can_do_bos to true

Example of code 422 error response:

{
  "errors": {
    "user": [
      "can't apply to swap"
    ]
  }
}

Delete Application

To delete an existing application on a swap you're required to authenticate and provide the id of the swap as follows:

Example of an application to swap id 10:

The successful API call results in the same response received when requesting a swaps (see Get Swap) and it will include the new application.

The application may fail for various reasons:

• Authentication is not successful
• Swap id is not provided
• Swap with the id requested doesn't exist
• Swap is not in pending status
• User is not allowed to delete the application as it's the only one in the swap
• User doesn't have an application on the given swap

Example of code 422 error response:

{
  "errors": {
    "swap": [
      "can't delete application"
    ]
  }
}

Complete Application

To complete an existing application on a swap you're required to authenticate and provide the id of the swap as follows:

Example of an application to swap id 10:

The successful API call results in the same response received when requesting a swaps (see Get Swap) and it will include the new application.

The application may fail for various reasons:

• Authentication is not successful
• Swap id is not provided
• Swap with the id requested doesn't exist
• Application is not in opening status
• User doesn't have an application on the given swap

Example of code 422 error response:

{
  "errors": {
    "swap": [
      "application is not in opening state"
    ]
  }
}

Ratings

With the following API command, you can create a rating on swaps. A rating should reflect the performance of the node operator who agreed to open a channel to a given node. You can't delete a rating, but you can overwrite it. For example, a positive rating can be overwritten with a negative one. You can only rate within a swap once.

Create Rating

To create a rating on a swap you are required to authenticate, provide the id of the swap and indicate if the rating is positive or negative as follows:

Example of a request to create a comment on swap id 10:

The successful API response results in the same response received when requesting multiple swaps (see Get Swaps), except a single swap is returned, which includes all ratings including the newly created one.

The request may fail for various reasons:

• Swap id is not provided
• Swap with the id requested doesn't exist
• User is not allowed to rate on a swap that they don't participate in
• The value of the rating isn't either "positive" or "negative"
• The swap isn't completed

Example of code 422 error response:

{
  "errors": {
    "rating": [
      "invalid rating value"
    ]
  }
}

Comments

With the following API commands, you can create and retrive comments posted on swaps.

Get Comments

To get the comments posted on a swap you are required to authenticate and provide the id of the swap as follows:

Example of a request for comments on swap id 10:

Example of code 200 success response:

{
  "id": 3,
  "comments_count": 2,
  "public_visibility": false,
  "comments":
    [
      {
        "comment_id": 16,
        "created_at": "2022-07-09T07:53:08.892Z",
        "pubkey": "0402536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f12345",
        "alias": "Iceman",
        "body": "Just give me a few minutes. Restarting my node."
      },
      {
        "comment_id" :17,
        "created_at" :"2022-07-09T07:56:34.974Z",
        "pubkey": "0502536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04fabcdef",
        "alias": "Rooster",
        "body": "Take your time bud."
      }
    ]
}

The request may fail for various reasons:

• Swap id is not provided
• Swap with the id requested doesn't exist
• User is not allowed to read comments on non-pending (open for applications) swap that they don't participate in

Example of code 422 error response:

{
  "errors": {
    "user": [
      "incorrect permissions"
    ]
  }
}

Create Comment

To post a comment on a swap you are required to authenticate, provide the id of the swap and body text for the comment as follows:

Example of a request to create a comment on swap id 10:

The successful API call results in the same response received when requesting the comments on a swaps (see Get Comments) and it will include the newly created comment.

The request may fail for various reasons:

• Swap id is not provided
• Swap with the id requested doesn't exist
• User is not allowed to post comments on non-pending (open for applications) swap that they don't participate in

Example of code 422 error response:

{
  "errors": {
    "user": [
      "can't comment on swap"
    ]
  }
}

My Area

My area has four API commands. The first returns all swaps you participated in, and the second one lists all the immediate to-dos you have to pay attention to. The third one gets the account information associated with a given node. The last one updates the account information.

Get My Swaps

This API request returns all the swaps that the user is participating in. The swaps are organized by their statuses: pending, opening, and completed. Depending on the status, relevant fields are provided for each swap as follows.

Shared Fields

• id - The unique ID of the swap, important information for many API calls.
• web_url - The URL of the swap on LightningNetwork.plus website.
• image_url - The URL of the image that represents the swap on LN+.
• created_at - When the swap was originally created.
• updated_at - When the swap was last edited. Swaps can't be edited once there are more than 1 applicants.
• status - Swap status that can have three values: pending, opening, and completed.
• humanized_status - Same as status, but in form that is more understandable for a human user.
• application_status - The status of the application. Can have three values: pending, opening, and completed.
• capacity_sats - The swap capacity. The amount of funds participants need to have to participate and open channels.
• duration_months - The length of the swap agreement. The amount of time participants have to keep the channels open without incuring penalty.
• participant_max_count - The number of participants the swap can have. 2 means dual funded channel, 3 is a triangle, 4 is a square, 5 is a pentagon. No other values are allowed.
• participant_applied_count - The number of participants already applied to the swap.
• participant_waiting_for_count - The number of new participants required before the swap is full.
• private - Swap privacy status. Private swaps can only be joined with a pin code that only swap creator has.
• comments_count - The number of comments posted on the swap.
• instruction - Instructions to the user on what to do next.

Unique fields to Opening Swaps

• outgoing_peer_pubkey - The pubkey of the node the user needs to open a channel to according to the swap agreement.
• outgoing_peer_tor_address - The tor address of the node the user need to open a channel to.
• outgoing_peer_crearnet_address - The clearnet address of the node the user need to open a channel to.
• deadline - User needs to open the channel before this time.

Unique fields to Completed Swaps

• incoming_peer_pubkey - The pubkey of the node the user is expecting a channel open from within the swap.
• outgoing_peer_pubkey - The pubkey of the node the user is required to open a channel to within the swap.
• starts - The time when the last applicant joined and channel opening started. Applicants have 48 hours from this time to open channels.
• ends - The time when the swap agreement ends and participants can close their channels without penalty.
• can_close - True is the channels can be closed, and false if they need to be kept open.

Get my swaps as follows:

Example of how to get the swaps of a user they are participating in:

Example of code 200 success response:

[
  {
    "pending": [
      {
        "id": 10,
        "web_url": "https://lightningnetwork.plus/swaps/10",
        "image_url": "https://ds29si9p6n9nh.cloudfront.net/static/neon-triangle-small-card.webp",
        "created_at": "2022-07-09T13:29:51.145Z",
        "updated_at": "2022-07-09T13:29:51.145Z",
        "status": "pending",
        "humanized_status": "Open for Application",
        "application_status": "pending",
        "capacity_sats": 100000,
        "duration_months": 10,
        "participant_max_count": 3,
        "participant_applied_count": 1,
        "participant_waiting_for_count": 2,
        "private": false,
        "comments_count": 5,
        "application_status": "pending",
        "instruction": "wait for applications"
      },
      {
        "id": 9,
        "web_url": "https://lightningnetwork.plus/swaps/9",
        "image_url": "https://ds29si9p6n9nh.cloudfront.net/static/neon-pentagon-small-card.webp",
        "created_at": "2022-07-09T13:29:51.145Z",
        "updated_at": "2022-07-09T13:29:51.145Z",
        "status": "pending",
        "humanized_status": "Open for Application",
        "application_status": "pending",
        "capacity_sats": 100000,
        "duration_months": 5,
        "participant_max_count": 5,
        "participant_applied_count": 1,
        "participant_waiting_for_count": 4,
        "private": false,
        "comments_count": 2,
        "application_status": "pending",
        "instruction": "wait for applications"
      }
    ],
    "opening": [
      {
        "id": 3,
        "web_url": "https://lightningnetwork.plus/swaps/3",
        "image_url": "https://ds29si9p6n9nh.cloudfront.net/static/neon-triangle-small-card.webp",
        "created_at": "2022-07-09T13:29:51.145Z",
        "updated_at": "2022-07-09T13:29:51.145Z",
        "status": "opening",
        "humanized_status": "Opening Channels",
        "application_status": "completed",
        "capacity_sats": 300000,
        "duration_months": 5,
        "participant_max_count": 3,
        "participant_applied_count": 3,
        "participant_waiting_for_count": 0,
        "private": false,
        "comments_count": 2,
        "instruction": "wait for all channels to be opened",
        "outgoing_peer_pubkey": "0219911bceefc3b65af9a8e3cd850dfec99137505250915e31d59f75b59804f281",
        "outgoing_peer_tor_address": "0219911bceefc3b65af9a8e3cd850dfec99137505250915e31d59f75b59804f281@bk4jx22qb5ev3mgzikhvg4xchwrghatb77cvxicx4bhfrnslyjfw5had.onion:9735",
        "outgoing_peer_clearnet_address": null,
        "deadline": "2022-07-11T07:49:42.621Z"
      }
    ],
    "completed": [
      {
        "id": 5,
        "web_url": "https://lightningnetwork.plus/swaps/5",
        "image_url": "https://ds29si9p6n9nh.cloudfront.net/static/neon-triangle-small-card.webp",
        "created_at": "2022-07-09T13:29:51.145Z",
        "updated_at": "2022-07-09T13:29:51.145Z",
        "status": "completed",
        "humanized_status": "Completed",
        "application_status": "completed",
        "capacity_sats": 500000,
        "duration_months": 12,
        "participant_max_count": 3,
        "participant_applied_count": 3,
        "participant_waiting_for_count": 0,
        "private": false,
        "comments_count": 1,
        "instruction": "rate incoming peer",
        "incoming_peer_pubkey": "ccc6b7d6f6479decea58e759f9cd5f42b6c1c446d4ba4bdcb30ee817aec9660f4",
        "outgoing_peer_pubkey": "dddc6b7d6f6479decea58e759f9cd5f42b6c1c446d4ba4bdcb30ee817aec9660f4",
        "starts": "2022-04-01T08:15:11.054Z",
        "ends": "2023-04-01T08:15:11.054Z",
        "can_close": false
      }
    ]
  }
]

Get my swaps may fail if authentication is not successful.

Get My Todos

This API request returns all the swaps that the user needs to take an urgent action on.

Get my todos as follows:

Example of how to get the swaps of a user they are participating in:

Example of code 200 success response:

[
  {
    "opening": [
      {
        "id": 3,
        "web_url": "https://lightningnetwork.plus/swaps/3",
        "application_status": "opening",
        "instruction": "open channel to peer",
        "outgoing_peer_pubkey": "0219911bceefc3b65af9a8e3cd850dfec99137505250915e31d59f75b59804f281",
        "outgoing_peer_tor_address": "0219911bceefc3b65af9a8e3cd850dfec99137505250915e31d59f75b59804f281@bk4jx22qb5ev3mgzikhvg4xchwrghatb77cvxicx4bhfrnslyjfw5had.onion:9735",
        "outgoing_peer_clearnet_address": null,
        "capacity_sats": 5000000,
        "deadline": "2022-07-11T07:49:42.621Z"
      }
    ]
  }
]

Get my todos may fail if authentication is not successful.

Get Account Info

This API request returns the account information associated with the user's node.

Available Fields

• pubkey - The unique pubkey of the node.
• email - User's email used for notifications or as an alternate login to LN+ in case Lighting sign in wasn't available. This is not public information.
• avatar - URL of the node profile image provided by the node operator and hosted on LN+'s CDN server.
• name - Name of the node operator. Typically same as the alias.
• twitter - Twitter url of the node operator.
• website - Website url of the node operator.
• bio - Short bio of the node operator.
• send_notifications - whether the user wants notifications sent to them to their email. Values can be true or false. This is not public information.
• can_connect_to_tor - Whether the user can connect to tor nodes. Values can be true or false. This is not public information.

Get the account information as follows:

Example request:

Example of code 200 success response:

[
  {
    "pubkey: "0202536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e52",
    "email": "router_node@noderunner.com",
    "avatar": "https://d48ttl5m5edbw.cloudfront.net/52nk60717d9eg6facvzlrejbedtd",
    "name": "Router Node",
    "twitter": "https://x.com/@routernode",
    "website: "https://routernode.com",
    "bio": "Highly available bitcoin lightning routing node.",
    "send_notifications": true,
    "can_connect_to_tor": true
  }
]

Get account info may fail if authentication is not successful.

Update Account Info

This API allows the update of account information associated with the user's node. You're not required to send all information, only the authentication message, signature and the fields that require updating. The rest of the fields do not need to be included in the request. Updating the user's avatar is currently not supported via the API, only through the website interface. The pubkey naturally can't be updated at all.

Update the account information as follows:

Example request:

Example of code 200 success response:

[
  {
    "pubkey: "0202536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e52",
    "email": "new_email@noderunner.com",
    "avatar": "https://d48ttl5m5edbw.cloudfront.net/52nk60717d9eg6facvzlrejbedtd",
    "name": "Node Runner 2000",
    "twitter": "https://x.com/@routernode2000",
    "website: "https://routernode2000.com",
    "bio": "A new reliable router for a new millennium.",
    "send_notifications": true,
    "can_connect_to_tor": true
  }
]

The request may fail for various reasons:

• Email is invalid
• User authentication is not successful

Notifications

With the following API commands, you can retrive notifications for a specific node user, and mark them all as read. Each notification contains unique notification_id, the date of creation, notification type, a message body, and an url that points to the website where further action can be taken. Notifications come in various different types:

• Swap - Action required on a swap, such as channel opening or rating
• Comment - New comment posted on a Swap
• Rating - User received a positive or negative rating
• Message - User received a new direct message
• Answer - User received an answer to a support question
• Reply - User received a reply to their profile post

Get Notifications

To get the notifications sent to a node user you are only required to authenticate as follows:

Example request:

Example of code 200 success response:

{
  "pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
  "notification_count": 1,
  "notifications":
    [
      {
        "notification_id": 1301,
        "created_at": "2022-07-09T07:53:08.892Z",
        "type": "Swap",
        "body": "Swap 20: Initiate channel opening!",
        "url": "https://lightningnetwork.plus/swaps/20"
      }
    ]
}

The request may fail for various reasons:

• The message is older than 5 minutes
• The signature is not valid
• The node/user has been cancelled by user or banned by administrator

Example of code 422 error response:

{
  "errors": {
    "user": [
      "incorrect permissions"
    ]
  }
}

Mark Notifications as Read

To clear all unread notifications, you can mark them as read just by authenticating as follows:

Example request:

If the API call is successful it should return a notification count of zero and an empty array of notifications. Example of code 200 success response:

{
  "pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
  "notification_count": 0,
  "notifications":
    []
}

The request may fail for various reasons:

• The message is older than 5 minutes
• The signature is not valid
• The node/user has been cancelled by user or banned by administrator

Example of code 422 error response:

{
  "errors": {
    "user": [
      "incorrect permissions"
    ]
  }
}

Nodes

This API call returns information about a specific bitcoin lightning network node. The information includes publicly available node information pulled from the lightning gossip network and also LN+ related reputation information.

Node Fields

• pubkey - The unique pubkey of the node.
• alias - The alias (name) set by node operator to their node.
• open_channels - The number of open and public channels visible on the gossip network.
• capacity - The size of the channel in satoshis.
• min_channel_size - Minimum channel size the node is willing to accept, based on their LN+ account settings.
• address_1 - The primary address of the node.
• address_2 - The secondary address of the node, if the node supports both tor and clearnet.
• hubness_rank - Measures influence of a given node in the network. Better ranks imply a well-connected node that is linked to other well-connected nodes. Lower numbers are better. Acquired from LN node insight.
• weighted_hubness_rank - Same as hubness_rank, but weighted for channel sizes.
• hopness_rank - Measures how many hops it takes to reach any node on the network. The better the rank, the fewer the hops are required to reach other nodes. Lower numbers are better. Acquired from LN node insight.
• weighted_hopness_rank - Same as hopness_rank, but weighted for channel sizes.
• betweenness_rank - Measures how often this node falls on the shortest path between other nodes. The better the rank, the more likely the node will route a payments. Lower numbers are better. Acquired from LN node insight.
• weighted_betweenness_rank - Same as betweenness_rank, but weighted for channel sizes.
• website - Self reported website url of the node operator.
• twitter - Self reported Twitter url of the node operator.
• nostr - Self reported Nostr pubkey of the node operator.
• youtube - Self reported YouTube url of the node operator.
• facebook - Self reported Facebook url of the node operator.
• linkedin - Self reported LinkedIn url of the node operator.
• telegram - Self reported Telegram url of the node operator.
• instagram - Self reported Instagram url of the node operator.
• discord - Self reported Discord url of the node operator.
• medium - Self reported Medium url of the node operator.
• tiktok - Self reported TikTok url of the node operator.
• github - Self reported GitHub url of the node operator.
• bio - Self reported bio of the node operator.
• avatar - URL of the node profile image provided by the node operator and hosted on LN+'s CDN server.
• social_image - URL of the social image generated by LN+ from the node's alias, color and avatar.
• name - Self reported name of the node operator. Typically same as the alias.
• lnp_verified_user - Boolean indicating whether the user has successfuly signed in with their node to LN+.
• lnp_updated_at - Datetime of when the information on node profile has been updated last.
• lnp_rank - LN+ ranking level between 0 and 10. Higher is better.
• prime - Boolean indicating whether the node is a prime node. Prime nodes are nodes that have at least 10 positive (happy) ratings and maintain a 90% positive rating ratio.
• pro - Boolean indicating whether the Node owner is a Pro Membership holder.
• lnp_rank_name - LN+ ranking level expressed as a name of a specific metal.
• lnp_positive_ratings_received - The number of positive ratings the node operator received on LN+ from other users. Higher is better.
• lnp_negative_ratings_received - The number of negative ratings the node operator received on LN+ from other users. Lower is better.
• lnp_positive_ratings_given - The number of positive ratings the node operator received on LN+ from other users.
• lnp_negative_ratings_given - The number of negative ratings the node operator received on LN+ from other users.
• lnp_badges - An array of hashes with badges received on LN+, each with a name and short description. The more the better.
• profile_urls - A hash of URLs to several known bitcoin lightning network node explorers, each with a name of the service and the relevant URL.

Get Node

To get node information, you don't need to authenticate. You only need to provide the node's unique pubkey.

Simplest way to request swaps:

Example request:

Example of code 200 success response:

{
  "pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
  "alias": "LightningNetwork.Plus",
  "color_hex": "#6d28d9",
  "open_channels": 209,
  "capacity": 544816737,
  "min_channel_size": 100000,
  "address_1": "44.233.203.243:9735",
  "address_2": "zlvvqxyk5on7oxiyllk2uof7ucaxgrnlzf3qytmraaku6q4bhbiplnad.onion:9735",
  "hubness_rank": 189,
  "weighted_hubness_rank": 354,
  "hopness_rank": 686,
  "weighted_hopness_rank": 2548,
  "betweenness_rank": 74,
  "weighted_betweenness_rank": 130,
  "twitter": "https://x.com/BTC_LN",
  "website": "https://lightningnetworkplus.com",
  "bio": "LN+'s highly reliable node.",
  "avatar": "https://d48ttl5m5edbw.cloudfront.net/52nk60717d9eg6facvzlrejbedtd",
  "social_image": "https://d48ttl5m5edbw.cloudfront.net/fnat2hmrjuw6pt7pn6xbj1vg5vy5",
  "name": "LightningNetwork.Plus",
  "lnp_verified_user": true,
  "lnp_updated_at": "2022-06-18T07:04:13.008Z",
  "lnp_rank": 8,
  "lnp_rank_name": "Gold",
  "prime": false,
  "pro": true,
  "lnp_positive_ratings_received": 35,
  "lnp_negative_ratings_received": 0,
  "lnp_positive_ratings_given": 37,
  "lnp_negative_ratings_given": 0,
  "lnp_badges": [
    {
      "name": "Verified",
      "description": "Node signed"
    },
    {
      "name": "OG",
      "description": "Early registrant"
    },
    {
      "name": "Opener",
      "description": "Opened a channel"
    },
    {
      "name": "Passionate",
      "description": "Opened 10+ channels"
    },
    {
      "name": "Impactful",
      "description": "Opened 25+ channels"
    },
    {
      "name": "Superstar",
      "description": "Opened 50+ channels"
    },
    {
      "name": "Trustworthy",
      "description": "Received a good rating"
    },
    {
      "name": "Honourable",
      "description": "Received 10+ good ratings"
    },
    {
      "name": "Virtuous",
      "description": "Received 25+ good ratings"
    },
    {
      "name": "Social",
      "description": "Posted a comment"
    },
    {
      "name": "Inquisitive",
      "description": "Asked a question"
    },
    {
      "name": "Resolver",
      "description": "Answered a question"
    },
    {
      "name": "Generous",
      "description": "Donated to LN+"
    }
  ],
  "profile_urls": {
    "LN+": "https://lightningnetwork.plus/nodes/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "Mempool": "https://mempool.space/lightning/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "1ML": "https://1ml.com/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "Amboss": "https://amboss.space/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "CheeseRobot": "https://cheeserobot.org/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "LnRouter": "https://lnrouter.app/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "ACINQ": "https://explorer.acinq.co/n/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "Terminal": "https://terminal.lightning.engineering/#/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "HashXP": "https://hashxp.org/lightning/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "ExpLayers": "https://app.exponentiallayers.com/Nodes/Details/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "BoltObserver": "https://bolt.observer/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f"
  }
}

The request may fail if the pubkey is not found.

Example of code 422 error response:

{
  "errors": {
    "node": [
      "not found"
    ]
  }
}