2. Atomicdex
  3. Api
  4. V20 Dev
  5. Lightning
  6. Channels
latest contributor to this doc

Last Edit: @smk762 ,

Lightning Network Channels

Lightning methods are currently only available using the native AtomicDEX-API. WASM support should be available in late 2023.

API-v2lightning::channels::open_channel

Open Channel

The lightning::channels::open_channel method opens a new channel with a remote node.

Request Parameters

ParameterTypeDescription
coinstringThe ticker of the coin you would like to open a channel for.
node_addressstringLightning node addresses always have a format of node_pubkey@ip_address:port.
amountobjectA standard LightningChannelAmount object.
push_msatintegerOptional. The amount in millisatoshi to push to the counterparty while openning, to create inbound liquidity for the channel. Using the push_msat parameter avoids having to send funds in a separate request later. Please note that the funds given using push_msat is given unconditionally, meaning that there is no proof of payment in a preimage as with paying an invoice.
channel_optionsobjectOptional. A standard LightningChannelOptions object.
channel_configsobjectOptional. A standard LightningChannelConfig object.

📌 Example using an exact amount

POST
open_channel
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::open_channel",
  "params": {
    "coin": "tBTC-lightning",
    "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735",
    "amount": {
      "type": "Exact",
      "value": 0.004
    }
  },
  "id": 22
}

📌 Example using max available with channel options and configs

POST
open_channel
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::open_channel",
  "params": {
    "coin": "tBTC-lightning",
    "node_address": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9@203.132.94.196:9735",
    "amount": {
      "type": "Max"
    },
    "push_msat": 0,
    "channel_options": {
      "proportional_fee_in_millionths_sats": 0,
      "base_fee_msat": 1000,
      "cltv_expiry_delta": 72,
      "max_dust_htlc_exposure_msat": 5000000,
      "force_close_avoidance_max_fee_satoshis": 1000
    },
    "channel_configs": {
      "counterparty_locktime": 144,
      "our_htlc_minimum_msat": 1,
      "negotiate_scid_privacy": false,
      "max_inbound_in_flight_htlc_percent": 10,
      "commit_upfront_shutdown_pubkey": true,
      "inbound_channels_confirmations": 3,
      "their_channel_reserve_sats": 10000
    }
  },
  "id": null
}
API-v2lightning::channels::close_channel

Close Channel

The lightning::channels::close_channel method closes a channel with a remote node.

Request Parameters

ParameterTypeDescription
coinstringThe ticker of the coin you would like to close a channel for.
uuidstringUnique channel identifier.
force_closebooleanOptional, defaults to false. If true, will force closure of the channel.

It is not recommended to force close a channel unless the counterparty is offline or unreachable for a long time. Force closure of a channel will makeresult in the party who initiates the force closure to wait for a number of blocks (equal to the force_close_spend_delay value returned by lightning::channels::get_channel_details) before they can get their funds on chain.

📌 Example to force closing a channel

POST
close_channel
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::close_channel",
  "params": {
    "coin": "tBTC-lightning",
    "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92",
    "force_close": true
  },
  "id": 8
}
API-v2lightning::channels::update_channel

Update Channel

The lightning::channels::update_channel method updates channel options.

Request Parameters

ParameterTypeDescription
coinstringThe ticker of the coin you would like to update channel configuration options for.
uuidstringUnique channel identifier.
channel_optionsobjectA standard LightningChannelOptions object.

📌 Example to update all available channel options

POST
update_channel
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::update_channel",
  "params": {
    "coin": "tBTC-lightning",
    "uuid": "434681f8-95e5-484f-af49-fa80d8ae857b",
    "channel_options": {
      "proportional_fee_in_millionths_sats": 1,
      "base_fee_msat": 1100,
      "cltv_expiry_delta": 72,
      "max_dust_htlc_exposure_msat": 5000000,
      "force_close_avoidance_max_fee_satoshis": 1000
    }
  },
  "id": 2
}
API-v2lightning::channels::get_channel_details

Get Channel Details

The lightning::channels::get_channel_details method returns details about a channel.

Request Parameters

ParameterTypeDescription
coinstringThe ticker of the coin you would like to view channel details for.
uuidstringUnique channel identifier.

📌 Example to update all available channel options

POST
get_channel_details
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::get_channel_details",
  "params": {
    "coin": "tBTC-lightning",
    "uuid": "2b50e274-c173-4fa1-95f3-97f9f82ace92"
  },
  "id": 54
}
API-v2lightning::channels::get_claimable_balances

Get Claimable Balances

The lightning::channels::get_claimable_balances method returns a list of claimable balances for a coin.

Request Parameters

ParameterTypeDescription
coinstringThe ticker of the coin you would like to view claimable balances for.
include_open_channels_balancesintegerOptional, defaults to false. If true, includes balances from open channels.

📌 Example to update all available channel options

POST
get_claimable_balances
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::get_claimable_balances",
  "params": {
    "coin": "tBTC-lightning",
    "include_open_channels_balances": true
  },
  "id": 762
}
API-v2lightning::channels::list_open_channels_by_filter

List Open Channels by Filter

The lightning::channels::list_open_channels_by_filter method returns a list of open channels filtered by the provided filter object.

Request Parameters

ParameterTypeDescription
coinstringThe ticker of the coin you would like to view open channels for.
filterobjectA standard LightningOpenChannelsFilter object.
paging_optionsobjectOptional. A standard Pagination object.
limitintegerOptional, defaults to 10. Maximum number of results to return.

📌 Example without using filter parameter

Command

POST
list_open_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_open_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning"
  },
  "id": 55
}

📌 Example with filter for inbound channels only

Command

POST
list_open_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_open_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning",
    "filter": {
      "is_outbound": false
    }
  },
  "id": 55
}

📌 Example with filter for a specific node_id

Command

POST
list_open_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_open_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning",
    "filter": {
      "counterparty_node_id": "02eb0b178576857b6990ba57d56aa08f651a05a8098496004f42df5e7440b0a9c1"
    }
  },
  "id": 55
}

📌 Example with filter for a node with between 100000 and 500000 satoshi funding value

Command

POST
list_open_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_open_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning",
    "filter": {
      "from_funding_value_sats": 1000,
      "to_funding_value_sats": 500000
    }
  },
  "id": 55
}
API-v2lightning::channels::list_closed_channels_by_filter

List Closed Channels by Filter

The lightning::channels::list_closed_channels_by_filter method returns a list of closed channels filtered by the provided filter object.

Request Parameters

ParameterTypeDescription
coinstringThe ticker of the coin you would like to view closed channels for.
filterobjectA standard LightningClosedChannelsFilter object.
paging_optionsobjectOptional. A standard Pagination object.
limitintegerOptional, defaults to 10. Maximum number of results to return.

📌 Example without using filter parameter

Command

POST
list_closed_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_closed_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning"
  },
  "id": 55
}

📌 Example with filter for inbound channels only

Command

POST
list_closed_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_closed_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning",
    "filter": {
      "channel_type": "Inbound"
    }
  },
  "id": 55
}

📌 Example with filter for a specific node_id

Command

POST
list_closed_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_closed_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning",
    "filter": {
      "counterparty_node_id": "038863cf8ab91046230f561cd5b386cbff8309fa02e3f0c3ed161a3aeb64a643b9"
    }
  },
  "id": 55
}

📌 Example with filter for a node with between 100000 and 500000 satoshi funding value

Command

POST
list_closed_channels_by_filter
{
  "userpass": "testpsw",
  "mmrpc": "2.0",
  "method": "lightning::channels::list_closed_channels_by_filter",
  "params": {
    "coin": "tBTC-lightning",
    "filter": {
      "from_funding_value_sats": 100000,
      "to_funding_value_sats": 500000
    }
  },
  "id": 55
}