Channel Management

Complete reference for Lightning channel lifecycle endpoints. All paths carry the /api/v1 prefix.

List channels

GET /api/v1/channels

List all channels of the node.

Response:

[
  {
    "channel_id": "abc123...",
    "user_channel_id": "user_abc123",
    "counterparty_node_id": "02def456...",
    "channel_point": "funding_txid:0",
    "channel_value_sats": "1000000",
    "outbound_capacity_msat": "500000000",
    "inbound_capacity_msat": "500000000",
    "local_balance_msat": "500000000",
    "remote_balance_msat": "500000000",
    "local_unspendable_punishment_reserve_sats": "10000",
    "remote_unspendable_punishment_reserve_sats": "10000",
    "is_channel_ready": true,
    "is_usable": true,
    "is_announced": true,
    "rgb_balance": {
      "contract_id": "contract:...",
      "local_amount": "500",
      "remote_amount": "500"
    }
  }
]

Field notes:

• channel_id: channel identifier; closing endpoints reference it for status lookups
• user_channel_id: this node's channel identifier; POST /channel/close uses this field
• counterparty_node_id: counterparty node pubkey
• channel_point: funding outpoint (txid:vout), optional
• channel_value_sats: total channel capacity (sats)
• outbound_capacity_msat / inbound_capacity_msat: sendable / receivable capacity (millisatoshis)
• local_balance_msat / remote_balance_msat: local and remote balances (millisatoshis), optional
• is_channel_ready: whether the channel has finished being established
• is_usable: whether the channel can be used for payments right now
• is_announced: whether the channel is announced to the network
• rgb_balance: in-channel RGB asset balance for RGB channels; absent on non-RGB channels

Open a channel

POST /api/v1/channel/open

Open a new channel with a peer; an rgb object opens an RGB channel.

Request (plain BTC channel):

{
  "node_id": "02def456...",
  "address": "203.0.113.20:9735",
  "channel_amount_sats": "1000000",
  "push_to_counterparty_msat": "0",
  "announce": true,
  "channel_direction": "buy"
}

Request (RGB channel):

{
  "node_id": "02def456...",
  "address": "203.0.113.20:9735",
  "channel_amount_sats": "1000000",
  "announce": true,
  "rgb": {
    "contract_id": "contract:...",
    "asset_amount": "100",
    "desired_asset_amount": "100",
    "color_context_data": "https://<your-node-domain>/api/v1/rgb/consignments/{txid}?format=zip"
  }
}

Parameter notes:

• node_id (required): counterparty node pubkey
• address (required): counterparty P2P address
• channel_amount_sats (required): channel funding amount (sats)
• push_to_counterparty_msat: initial amount pushed to the counterparty (millisatoshis), default 0
• announce: whether to announce the channel, public by default
• channel_direction: buy or sell
• rgb.contract_id (required for RGB channels): RGB contract ID
• rgb.asset_amount (required for RGB channels): asset amount injected into the channel
• rgb.desired_asset_amount: desired asset amount, optional
• rgb.color_context_data: consignment download URL template; required for RGB channels, the node replaces the {txid} placeholder with the funding transaction ID
• rgb.funding_utxo_policy: automatic coin-selection policy, one of single-rgb-anchor, rgb-anchor-with-btc-support, merge-rgb-anchors-with-btc-support
• rgb.funding_utxos: explicit funding inputs (txid, vout, role), where role is rgb-state or fee-support; mutually exclusive with funding_utxo_policy

Response:

{
  "user_channel_id": "user_abc123"
}

Opening is asynchronous: the funding transaction is broadcast on-chain and the channel becomes usable after confirmation. Track progress through ChannelPending / ChannelReady on the event stream, or watch is_channel_ready and is_usable in GET /channels. RGB channels need colorable carrier UTXOs prepared first — see RGB operations.

Close a channel

POST /api/v1/channel/close

Cooperate with the peer to close a channel.

Request:

{
  "user_channel_id": "user_abc123",
  "counterparty_node_id": "02def456..."
}

Parameter notes:

• user_channel_id (required): user_channel_id from the channel list
• counterparty_node_id (required): counterparty node pubkey

Response:

{ "ok": true }

POST /api/v1/channel/force_close

Initiate a force close. Use it when the peer is offline or cannot cooperate; the node broadcasts the latest commitment transaction.

Request: same as POST /channel/close (user_channel_id + counterparty_node_id).

Response:

{ "ok": true }

A force close can incur on-chain fees and the funds need on-chain confirmations before they can be reclaimed; it is not an ordinary node start/stop operation.

Closing channels

GET /api/v1/channels/closing

List channels whose close has been initiated but whose funds have not yet landed back in the on-chain wallet.

Response:

[
  {
    "channel_id": "abc123...",
    "counterparty_node_id": "02def456...",
    "user_channel_id": "user_abc123",
    "status": "confirming",
    "close_source": "coop",
    "closing_txid": "abc123...",
    "btc_balances": [
      {
        "kind": "claimable_awaiting_confirmations",
        "amount_sats": "980000",
        "maturity_height": 250100,
        "blocks_remaining": 6
      }
    ],
    "sweeping_balances": [],
    "rgb": {
      "contract_id": "contract:...",
      "local_amount": "500",
      "remote_amount": "500",
      "sweep_status": "in_flight",
      "sweep_txid": "def456..."
    }
  }
]

Field notes:

• status: close stage, one of negotiating, broadcasting, confirming, contested, sweeping
• close_source: who initiated the close, one of coop, holder_force, counterparty_force, unknown
• closing_txid: closing transaction ID; null while negotiating or before the tx is known
• btc_balances: claimable BTC still being tracked; a force close may yield several (main output and each HTLC)
• sweeping_balances: BTC currently being swept back to the on-chain wallet
• rgb: null for non-RGB channels; sweep_status is parked, in_flight or done
• user_channel_id: only known while the channel manager still tracks it (negotiating); key on channel_id

A channel disappearing from both /channels and /channels/closing means it has fully settled — the reliable completion signal. Some older node builds may not support this endpoint and return 404.

Error handling

• 400: invalid request parameters
• 404: channel not found
• 409: conflicting channel state, e.g. a channel with the peer already exists or the channel is closing
• 500: node internal error
• 503: node not ready or still syncing

Examples

Open a public BTC channel

curl -X POST https://<your-node-domain>/api/v1/channel/open \
  -H "Authorization: Bearer <node-credential>" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "02def456...",
    "address": "203.0.113.20:9735",
    "channel_amount_sats": "1000000",
    "announce": true
  }'

Open an RGB channel

curl -X POST https://<your-node-domain>/api/v1/channel/open \
  -H "Authorization: Bearer <node-credential>" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "02def456...",
    "address": "203.0.113.20:9735",
    "channel_amount_sats": "1000000",
    "rgb": {
      "contract_id": "contract:...",
      "asset_amount": "100",
      "color_context_data": "https://<your-node-domain>/api/v1/rgb/consignments/{txid}?format=zip"
    }
  }'

Cooperatively close a channel

curl -X POST https://<your-node-domain>/api/v1/channel/close \
  -H "Authorization: Bearer <node-credential>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_channel_id": "user_abc123",
    "counterparty_node_id": "02def456..."
  }'