LN+ API Documentation

Introduction

This document describes the LightningNetwork.Plus JSON API version 2.4. Version 2.4 adds optional Node API Key authentication while preserving every version 2.3 endpoint and Lightning-signature request format. Endpoint URLs remain under /api/2.

Authentication

Protected API calls support two alternative authentication methods: a reusable Node API Key in the Authorization header, or the existing short-lived message signed by a Lightning node. Existing signed integrations remain fully supported in version 2.4.

Use exactly one authentication method per request. Requests containing both methods are rejected, and an invalid bearer key never falls back to a supplied signature.

Lightning Signature Authentication

First request a message, sign it with the Bitcoin Lightning Network node, then submit both the message and signature in the protected API request. A requested message can be reused for up to five minutes. After five minutes a new message is required. Successful verification associates the request with the signing 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

Node API Keys

A Node API Key is a reusable credential for one verified Lightning node. It is useful for bots and long-running integrations that should not ask the node to sign a new challenge every five minutes. Company membership does not change API identity: every key always represents exactly one node and its current LN+ user.

Manage Node API Keys from your Dashboard

Create and Store a Key

On the Node API Keys page, choose a verified node, enter a descriptive name, select the minimum scopes the client requires, and confirm the expiration date. Expiration defaults to—and cannot exceed—one year from creation. A node can have at most three active keys, and administrator accounts cannot create or use Node API Keys. The complete key is displayed only once. Store it in a secret manager; LN+ stores only a digest and cannot recover a lost key.

A key has this form:

Use Bearer Authentication

Send the complete key in the HTTP Authorization header. Do not send it in the URL, query string, or JSON body. Omit the legacy message and signature fields. No pubkey parameter is needed because the key selects the node.

The signed examples throughout this documentation remain valid. To use a Node API Key with any protected endpoint, add the Bearer header and remove only the message and signature fields from its JSON body; keep all endpoint-specific fields unchanged.

Scopes

Every key has one or more scopes. Create separate, narrowly scoped keys for independent integrations.

• read — applicable swaps, protected comments, My Swaps, My Todos, account information, and notifications.
• swaps:write — create/delete swaps and create/delete/complete applications.
• pool:write — create/update/delete pool credit transaction offers, approve/reject offers, mark pool channel opening started, and update pool visibility settings.
• social:write — create comments and ratings for swaps and pool credit transactions.
• notifications:write — mark notifications as read.
• account:write — update non-sensitive profile information and preferences. Login email and password cannot be changed through the API.

Lightning signature authentication retains access to all protected operations and does not use scopes.

Expiration, Rotation, and Revocation

A key stops authenticating at its required expiration or immediately after revocation. Expiration cannot be more than one year after creation. To rotate safely when three keys are active, revoke an unused key before creating its replacement. Existing complete keys cannot be displayed again.

Keys also stop working while their user is banned, cancelled, or locked, and they do not follow a node transferred to another user. Company membership changes do not revoke a key or let it act as a sibling account.

Rate Limits

Every authenticated request counts against its individual key, including requests that later fail scope checks or business validation. Each key is limited to 10 calls in any rolling minute, 30 calls in any rolling hour, and 100 calls in any rolling 24-hour period.

Authentication Errors

• 400 Bad Request — both authentication methods were supplied, or bearer authentication was sent to the signature-verification endpoint.
• 401 Unauthorized — the bearer key is malformed, unknown, incorrect, expired, revoked, inactive, or no longer matches the node owner. The response intentionally does not distinguish these cases.
• 403 Forbidden — the key is valid but lacks the endpoint's required scope.
• 422 Unprocessable Entity — authentication succeeded but endpoint input or a business rule failed. Existing signed-authentication error behavior is unchanged.
• 429 Too Many Requests — the key exceeded a rolling request limit. Wait for the number of seconds in the Retry-After response header before retrying.

{
  "errors": {
    "authentication": [
      "invalid API credential"
    ]
  }
}

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.
• outgoing_channel_detected - True when LN+ currently detects an active channel between this participant and the participant they should open to. False otherwise.

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",
        "outgoing_channel_detected": false
      }
    ]
  }
]

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

Node API Key scope: read

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.

Node API Key request:

Lightning signature request:

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

Node API Key scope: swaps:write

This API request allows an authenticated user to create a new swap and become its first participant. Authenticate with either a Node API Key or a Lightning signature. When using a Node API Key, provide the bearer header and omit the message and signature fields. The following swap parameters are required:

• message - Required only when using Lightning signature authentication.
• signature - Required only when using Lightning signature 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.

Node API Key request:

Lightning signature request:

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

Node API Key scope: swaps:write

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.

Node API Key request:

Lightning signature request:

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

Create Application

Node API Key scope: swaps:write

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_use_bos to true if you want to join LND/BOS swaps (platform: "lnd"). The parameter "can_use_bos" is optional and defaults to false:

Node API Key request:

Lightning signature request:

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

You can remove your own application with no time limit while the swap is pending, provided nobody has joined after you. The creator (A) cannot withdraw. Filling the final position starts channel opening and ends withdrawal eligibility. Remaining participants keep their positions and are notified; the withdrawal is recorded in the activity log.

Node API Key scope: swaps:write

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

Node API Key request:

Lightning signature request:

Example of withdrawing from swap id 10:

A successful withdrawal returns HTTP 200 with {"swap": "application successfully deleted"}.

The withdrawal 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 the creator (A), or another participant has joined after them
• User doesn't have an application on the given swap

Example of code 422 error response:

{
  "errors": {
    "swap": [
      "You can only remove your application while the swap is pending and nobody has joined after you. The creator cannot withdraw."
    ]
  }
}

Complete Application

Node API Key scope: swaps:write

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

Node API Key request:

Lightning signature request:

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

Create Rating

Node API Key scope: social:write

Create or update a rating on a completed swap. A rating should reflect the performance of the node operator who opened to you or the node operator you opened to. You are required to authenticate, provide the swap id, and indicate whether the rating is positive or negative.

The optional direction parameter controls who is rated: use "incoming" to rate the user who opened to you, or "outgoing" to rate the user you opened to. If direction is omitted, "incoming" is used to preserve the original API behavior.

Node API Key request:

Lightning signature request:

Example of a Lightning signature request to create a rating 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 value of direction isn't either "incoming" or "outgoing"
• The swap isn't completed

Example of code 422 error response:

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

Get Comments

Node API Key scope when authentication is required: read

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

Node API Key request:

Lightning signature request:

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

Node API Key scope: social:write

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:

Node API Key request:

Lightning signature request:

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

Delete Comment

Node API Key scope: social:write

To delete a comment on a swap you are required to authenticate, provide the swap id, and provide the comment_id returned by Get Comments.

Node API Key request:

Lightning signature request:

Example of a request to delete comment id 16 from swap id 10:

The successful API call results in the same response received when requesting the comments on a swap (see Get Comments) after the comment has been removed.

The request may fail for various reasons:

• Swap id is not provided
• Swap with the id requested doesn't exist
• Comment id is not provided
• Comment with the id requested doesn't exist on the swap
• User is not allowed to delete the comment

Example of code 422 error response:

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

Liquidity Pool

The Liquidity Pool API exposes the pool workflow available on the website: discover pool nodes, create channel offers, review incoming offers, report channel opening, track accounting, comment, and rate counterparties.

Credit transactions have a fixed 50 day duration. The channel opener earns liquidity credits over that period, and the receiver spends credits as the channel stays open.

Credit Transaction Statuses

• requested - The initiator created an offer and the receiver needs to review it.
• approved - The receiver accepted the offer and the initiator should open the channel.
• opened - The initiator marked the channel opening as started and LN+ is waiting to detect confirmation.
• confirmed - LN+ detected the live channel and credits are settling.
• closed - LN+ detected that the channel closed.
• rejected - The offer was declined, expired, or stopped before becoming confirmed.

Node API Key Scopes

• read - read private pool transactions, pool todos, pool accounting, and pool comments.
• pool:write - create and manage pool credit transaction offers and pool settings.
• social:write - create pool comments and ratings.

Get Pool Nodes

This public endpoint returns active nodes currently visible in the Liquidity Pool.

Optional parameters: search, min_size, connection, limit, page.

Example fields returned for each node: pubkey, alias, web_url, credits_balance_sats, min_channel_size_sats, capacity_sats, open_channels, connection, clearnet_address, tor_address, lnp_rank, ratings, bio, profile_urls, and highlighted.

Get Credit Transaction

Node API Key scope: read

Returns one pool credit transaction with role-aware next action, deadlines, peer details, progress, channel summary, comments count, and rating state.

Node API Key request:

Lightning signature request:

Get My Credit Transactions

Node API Key scope: read

Returns pool transactions involving the authenticated node. Optional filters: direction (all, initiated, received), status, limit, page.

Node API Key request:

Get My Pool Todos

Node API Key scope: read

Returns requested offers the authenticated node needs to review and approved offers where the authenticated node needs to open a channel.

Node API Key request:

Create Credit Transaction

Node API Key scope: pool:write

Creates an offer to open a channel to a pool node. The authenticated node becomes the initiator.

• to_node_id or to_pubkey - The pool node receiving the channel.
• size - Channel size in satoshis. It must be at least 100,000 sats, satisfy the receiver's minimum channel size, and not exceed the receiver's available pool credits.

Node API Key request:

Lightning signature request:

Manage Credit Transactions

Node API Key scope: pool:write

These endpoints update the state of an existing pool credit transaction. The authenticated node must have the correct role for the requested action.

• update_credit_transaction - Initiator can edit size while status is requested.
• delete_credit_transaction - Initiator can delete while status is requested.
• approve_credit_transaction - Receiver can accept while status is requested.
• reject_credit_transaction - Receiver can decline while status is requested.
• open_credit_transaction - Initiator can mark opening started while status is approved.

Node API Key examples:

Lightning signature examples:

Pool Accounting

Node API Key scope: read

Returns the authenticated node's pool visibility setting, required minimum channel size, available balance, purchased/gifted credits, and earned/spent credit totals by state.

Node API Key request:

Lightning signature request:

Update Pool Settings

Node API Key scope: pool:write

Updates pool visibility and required minimum channel size for the authenticated node/user.

Node API Key request:

Lightning signature request:

Create Rating

Node API Key scope: social:write

Create or update a rating on a Liquidity Pool credit transaction after it is confirmed or closed. You are required to authenticate, provide the credit transaction id, and indicate whether the rating is positive or negative.

Node API Key request:

Lightning signature request:

The request may fail if the credit transaction does not exist, the authenticated node is not a participant, the transaction is not confirmed or closed, or the rating value is not "positive" or "negative".

Get Comments

Node API Key scope: read

To get comments on a pool credit transaction you are required to authenticate and provide the credit transaction id.

Node API Key request:

Lightning signature request:

Create Comment

Node API Key scope: social:write

To post a comment on a pool credit transaction you are required to authenticate, provide the credit transaction id, and provide body text for the comment.

Node API Key request:

Lightning signature request:

The request may fail if the credit transaction does not exist, the authenticated node is not a participant, or the body is missing.

Delete Comment

Node API Key scope: social:write

To delete a comment on a pool credit transaction you are required to authenticate, provide the credit transaction id, and provide the comment_id returned by Get Comments.

Node API Key request:

Lightning signature request:

The successful API call results in the same response received when requesting the pool credit transaction comments after the comment has been removed.

The request may fail if the credit transaction does not exist, the comment_id is missing, the comment does not belong to the credit transaction, or the authenticated user is not allowed to delete the comment.

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

Node API Key scope: read

This API request returns all the swaps that the user is participating in. The swaps are organized by their statuses: pending, opening, and completed. Each swap includes the same detailed fields returned by Get Swap, plus status-specific fields such as the authenticated user's application status, instruction, peer details, deadlines, and close eligibility.

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.
• created_by_pubkey - The pubkey of the user's node who created the swap.
• 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.
• tor_connection_allowed - Tor connection support is required by the node joining the swap.
• description - Any note or requirement swap creator added to the swap.
• prime - Boolean indicating whether the swap is marked as Prime.
• pro - Created by a user with Pro Membership.
• platform - Lightning implementation platform allowed for a given swap. Can be either "any" or "lnd".
• participants - Array with the same participant details returned by Get 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.

Node API Key request:

Lightning signature request:

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,
        "created_by_pubkey": "0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
        "participant_min_capacity_sats": 1000000,
        "participant_min_channels_count": 5,
        "clearnet_connection_allowed": true,
        "tor_connection_allowed": true,
        "description": "Keep fees reasonable",
        "prime": false,
        "pro": false,
        "platform": "any",
        "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": "Iceman",
            "avatar": "https://ds29si9p6n9nh.cloudfront.net/n98kzfrqyw97a2n9vrrlam3p7aye",
            "capacity_sats": 15100100,
            "channels_count": 5,
            "lnplus_rank_number": 3,
            "lnplus_rank_name": "Copper",
            "rating_received": null,
            "rating_given": null,
            "positive_ratings_count": 2,
            "negative_ratings_count": 0,
            "opening_to_participant_identifier": "B",
            "receiving_from_participant_identifier": "C",
            "outgoing_channel_detected": false
          }
        ],
        "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

Node API Key scope: read

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

Node API Key request:

Lightning signature request:

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

Node API Key scope: read

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.

Node API Key request:

Lightning signature request:

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

Node API Key scope: account:write

This API allows the update of non-sensitive profile information and preferences associated with the user's node. Send only the fields that require updating. Login email, password, avatar, pubkey, permissions, and company membership cannot be changed through the API, regardless of authentication method. Use the authenticated website for login settings. With a Node API Key, authenticate through the bearer header and omit message and signature. With Lightning signature authentication, include message and signature in the JSON body.

Node API Key request:

Lightning signature request:

Example request:

Example of code 200 success response:

[
  {
    "pubkey: "0202536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e52",
    "email": "router_node@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:

• A login credential such as email or password was supplied
• 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
• Question - New support question posted
• 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

Node API Key scope: read

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

Node API Key request:

Lightning signature request:

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

Node API Key scope: notifications:write

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

Node API Key request:

Lightning signature request:

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.
• 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. Prime and Pro Membership are included here as "Prime" and "Member" badges when the node operator qualifies.
• 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",
  "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": true,
  "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": "Member",
      "description": "Pro Membership Holder"
    },
    {
      "name": "Prime",
      "description": "10+ Ratings and 90%+ Happy"
    },
    {
      "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",
    "Terminal": "https://terminal.lightning.engineering/explore/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "HashXP": "https://hashxp.org/lightning/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "OKLink": "https://www.oklink.com/btc/node/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f",
    "Yalls": "https://yalls.org/network/0302536817c335e45bcd0b10b78fd06bc246609405d98eb64672410dce04f49e5f"
  }
}

The request may fail if the pubkey is not found.

Example of code 422 error response:

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