通道管理

闪电通道生命周期接口的完整参考。所有路径均带 /api/v1 前缀。

列出通道

GET /api/v1/channels

列出节点当前的所有通道。

响应:

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

字段说明:

• channel_id：通道标识符，关闭类接口以此为准
• user_channel_id：本节点侧通道标识，POST /channel/close 使用该字段
• counterparty_node_id：对端节点公钥
• channel_point：出资 outpoint（txid:vout），可选
• channel_value_sats：通道总容量（聪）
• outbound_capacity_msat / inbound_capacity_msat：可发送 / 可接收容量（毫聪）
• local_balance_msat / remote_balance_msat：本地与对端余额（毫聪），可选
• is_channel_ready：通道是否已完成建立
• is_usable：通道当前是否可用于支付
• is_announced：通道是否向网络公告
• rgb_balance：RGB 通道的内通道资产余额，非 RGB 通道不含该字段

开启通道

POST /api/v1/channel/open

与对等节点开启新通道；rgb 字段存在时开启 RGB 通道。

请求（普通 BTC 通道）:

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

请求（RGB 通道）:

{
  "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://<节点域名>/api/v1/rgb/consignments/{txid}?format=zip"
  }
}

参数说明:

• node_id（必填）：对端节点公钥
• address（必填）：对端 P2P 地址
• channel_amount_sats（必填）：通道出资额（聪）
• push_to_counterparty_msat：向对端推送的初始金额（毫聪），默认 0
• announce：是否向网络公告通道，默认公开
• channel_direction：通道方向，取 buy 或 sell
• rgb.contract_id（RGB 通道必填）：RGB 合约 ID
• rgb.asset_amount（RGB 通道必填）：注入通道的资产数量
• rgb.desired_asset_amount：期望的资产数量，可选
• rgb.color_context_data：consignment 下载地址模板；RGB 通道必须提供，节点会以 {txid} 占位符替换出资交易 ID
• rgb.funding_utxo_policy：自动选币策略，取 single-rgb-anchor、rgb-anchor-with-btc-support 或 merge-rgb-anchors-with-btc-support
• rgb.funding_utxos：显式指定出资输入数组（txid、vout、role），role 取 rgb-state 或 fee-support；与 funding_utxo_policy 互斥

响应:

{
  "user_channel_id": "user_abc123"
}

开通道为异步操作：先在链上广播出资交易，等待确认后通道才可用。通过 事件流 的 ChannelPending / ChannelReady 事件跟踪进度，或用 GET /channels 观察 is_channel_ready 与 is_usable。RGB 通道需要先准备颜色载体 UTXO，参见 RGB 操作。

关闭通道

POST /api/v1/channel/close

协作关闭现有通道。

请求:

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

参数说明:

• user_channel_id（必填）：来自通道列表的 user_channel_id
• counterparty_node_id（必填）：对端节点公钥

响应:

{ "ok": true }

POST /api/v1/channel/force_close

发起强制关闭。适用于对端离线或无法协作的场景，向链上广播最新承诺交易。

请求: 与 POST /channel/close 相同（user_channel_id + counterparty_node_id）。

响应:

{ "ok": true }

强制关闭可能产生链上费用，且资金需要等待链上确认后才能取回；不能视为普通的节点启停操作。

关闭中的通道

GET /api/v1/channels/closing

列出已发起关闭、但资金尚未回到链上钱包的通道。

响应:

[
  {
    "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..."
    }
  }
]

字段说明:

• status：关闭阶段，取 negotiating、broadcasting、confirming、contested 或 sweeping
• close_source：关闭发起方，取 coop、holder_force、counterparty_force 或 unknown
• closing_txid：关闭交易 ID；协商中或交易未知时为 null
• btc_balances：仍在跟踪的待领取 BTC；强制关闭可能产生多项（主输出与各 HTLC）
• sweeping_balances：正在被扫回链上钱包的 BTC
• rgb：非 RGB 通道为 null；sweep_status 取 parked、in_flight 或 done
• user_channel_id：仅在通道管理器仍跟踪该通道（negotiating）时可用，应以 channel_id 作为主键

通道从 /channels 与 /channels/closing 中同时消失，说明已完全结算——这是判断最终完成的可靠信号。部分旧版本节点可能不支持该接口并返回 404。

错误处理

• 400：请求参数无效
• 404：通道不存在
• 409：通道状态冲突，例如已存在与对端通道或通道正在关闭
• 500：节点内部错误
• 503：节点未就绪或正在同步

示例

开启公开 BTC 通道

curl -X POST https://<你的节点域名>/api/v1/channel/open \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "02def456...",
    "address": "203.0.113.20:9735",
    "channel_amount_sats": "1000000",
    "announce": true
  }'

开启 RGB 通道

curl -X POST https://<你的节点域名>/api/v1/channel/open \
  -H "Authorization: Bearer <节点凭证>" \
  -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://<你的节点域名>/api/v1/rgb/consignments/{txid}?format=zip"
    }
  }'

协作关闭通道

curl -X POST https://<你的节点域名>/api/v1/channel/close \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_channel_id": "user_abc123",
    "counterparty_node_id": "02def456..."
  }'