LN+ API Documentation

Please note, that version 1 of the API which supports basic swap listing functionality is still functional, but has been deprecated. Please upgrade your application to version 2 described below.

Introduction

This document describes the operation of the LightningNetwork.Plus JSON API version 2. This API is designed to give programmatic access to all the core functionality required to create swaps, and participate in swaps.


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:

curl https://lightningnetwork.plus/api/2/get_message

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.

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature]}' https://lightningnetwork.plus/api/2/verify_signature

Example request with dummy parameters:

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike"}' https://lightningnetwork.plus/api/2/verify_signature

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.
  • 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.
  • 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.
  • description - Any note or requirement swap creator added to the swap.
  • private - Swap privacy status. Private swaps can only be joined with a pin code that only swap creator has.

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


Simplest way to request swaps:

curl https://lightningnetwork.plus/api/2/get_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).

curl https://lightningnetwork.plus/api/2/get_swaps/status=[status]/private=[private]/limit=[limit]

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

curl https://lightningnetwork.plus/api/2/get_swaps/status=pending/private=false/limit=1

Example of code 200 success response:

[
  {
    "id": 9,
    "web_url": "https://lightningnetwork.plus/swaps/9",
    "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,
    "description": "Must have reasonable fees",
    "private": false,
    "participants": [
      {
        "participant_identifier": "A",
        "application_id": 23,
        "applied_at": "2022-07-09T13:29:51.167Z",
        "updated_at": "2022-07-09T13:29:51.167Z",
        "status": "pending",
        "pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
        "address_1": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f@mueqiomlbw6yq7smawrdogfzttmzkw4ouuovcyut7mmozowccb3bodqd.onion:9735",
        "address_2": null,
        "alias": "Admin",
        "capacity_sats": 15100100,
        "channels_count": 5,
        "lnplus_rank_number": 3,
        "lnplus_rank_name": "Copper",
        "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:

curl https://lightningnetwork.plus/api/2/get_swap/id=[id]

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

curl https://lightningnetwork.plus/api/2/get_swap/id=9

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 and the node's number of channels. 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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature]}' https://lightningnetwork.plus/api/2/get_applicable_swaps

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, as opposed to dual channel argreements (2).
  • capacity - Size of the channels each participant will open in satoshis. Recommended minimum is 1 million satoshis.
  • 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.
  • 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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature], "participants": [participants], "capacity": [capacity], "duration": [duration], "min_channels": [min_channels], "min_capacity": [min_capacity], "rules": [rules]}' https://lightningnetwork.plus/api/2/create_swap

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

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike", "participants": 3, "capacity": 1000000, "duration": 6, "rules": "Keep fees reasonable"}' https://lightningnetwork.plus/api/2/create_swap

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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature], "id": [id]}' https://lightningnetwork.plus/api/2/delete_swap

Example to delete swap with id 10:

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike", "id": 10}' https://lightningnetwork.plus/api/2/delete_swap

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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature], "id": [id]}' https://lightningnetwork.plus/api/2/create_application

Example of an application to swap id 10:

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike", "id": 10}' https://lightningnetwork.plus/api/2/create_application

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

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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature], "id": [id]}' https://lightningnetwork.plus/api/2/delete_application

Example of an application to swap id 10:

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike", "id": 10}' https://lightningnetwork.plus/api/2/delete_application

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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature], "id": [id]}' https://lightningnetwork.plus/api/2/complete_application

Example of an application to swap id 10:

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike", "id": 10}' https://lightningnetwork.plus/api/2/complete_application

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"
    ]
  }
}

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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature], "id": [id]}' https://lightningnetwork.plus/api/2/get_comments

Example of a request for comments on swap id 10:

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike", "id": 10}' https://lightningnetwork.plus/api/2/get_comments

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 now 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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature], "id": [id], "body": [body]}' https://lightningnetwork.plus/api/2/create_comment

Example of a request for comments on swap id 10:

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike", "id": 10, "body": "Take your time buddy!"}' https://lightningnetwork.plus/api/2/create_comment

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 now 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 two 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.


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.

Pending Swaps

  • id - The unique ID of the swap, important information for many API calls.
  • web_url - The URL of the swap on LightningNetwork.plus website.
  • waiting_for - The number of new participants required before the swap is full.
  • application_status - The status of the application. Can have three values: pending, opening, and completed.
  • instruction - Instructions to the user on what to do next.

Opening Swaps

  • id - The unique ID of the swap, important information for many API calls.
  • web_url - The URL of the swap on LightningNetwork.plus website.
  • application_status - The status of the application. Can have three values: pending, opening, and completed.
  • instruction - Instructions to the user on what to do next.
  • 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.
  • channel_size - The size of the channel that needs to be opened in satoshis.
  • deadline - User needs to open the channel before this time.

Completed Swaps

  • id - The unique ID of the swap, important information for many API calls.
  • web_url - The URL of the swap on LightningNetwork.plus website.
  • application_status - The status of the application. Can have three values: pending, opening, and completed.
  • instruction - Instructions to the user on what to do next.
  • 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.
  • open_till - The time until the channels need to be kept open accroding to the swap agreement.
  • can_close - True is the channels can be closed, and false if they need to be kept open.

Get my swaps as follows:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature]}' https://lightningnetwork.plus/api/2/get_my_swaps

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

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike"}' https://lightningnetwork.plus/api/2/get_my_swaps

Example of code 200 success response:

[
  {
    "pending": [
      {
        "id": 10,
        "web_url": "https://lightningnetwork.plus/swaps/10",
        "waiting_for": 2,
        "application_status": "pending",
        "instruction": "wait for applications"
      },
      {
        "id": 9,
        "web_url": "https://lightningnetwork.plus/swaps/9",
        "waiting_for": 4,
        "application_status": "pending",
        "instruction": "wait for applications"
      }
    ],
    "opening": [
      {
        "id": 3,
        "web_url": "https://lightningnetwork.plus/swaps/3",
        "application_status": "completed",
        "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,
        "channel_size": 5000000,
        "deadline": "2022-07-11T07:49:42.621Z"
      }
    ],
    "completed": [
      {
        "id": 5,
        "web_url": "https://lightningnetwork.plus/swaps/5",
        "application_status": "completed",
        "instruction": "rate incoming peer",
        "incoming_peer_pubkey": "ccc6b7d6f6479decea58e759f9cd5f42b6c1c446d4ba4bdcb30ee817aec9660f4",
        "outgoing_peer_pubkey": "dddc6b7d6f6479decea58e759f9cd5f42b6c1c446d4ba4bdcb30ee817aec9660f4",
        "open_till": "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:

curl -X POST -H "Content-Type: application/json" -d '{"message": [message], "signature": [signature]}' https://lightningnetwork.plus/api/2/get_my_todos

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

curl -X POST -H "Content-Type: application/json" -d '{"message": "lnplus-api-6e872a9-b2e6f5c-88c7335", "signature": "thisisnotavalidsignaturejustanexampleofalongstringofhowasignatureprovidedbyanodewouldlooklike"}' https://lightningnetwork.plus/api/2/get_my_todos

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,
        "channel_size": 5000000,
        "deadline": "2022-07-11T07:49:42.621Z"
      }
    ]
  }
]

Get my todos may fail if authentication is not successful.