Stash Labs

中文

English

中文

English

Appearance

RGB 闪电网络节点 API 参考 ​

RGB 闪电网络节点 是基于 LDK（Lightning Development Kit）构建、支持 RGB 协议的闪电节点实现，由 Bitlight Labs 开发，Stash Cloud 负责编排运行。节点进程（rgbldkd）对外提供完整的 HTTP API，用于管理闪电通道、处理支付以及操作闪电网络上的 RGB 资产。

本组页面按节点真实接口整理，路径与字段以节点 HTTP 客户端实现为准，不复制未核验的请求体。

基础 URL 与调用方式 ​

节点 API 运行在每个节点的专属域名上：

https://<你的节点域名>
  • 数据面接口统一使用 /api/v1 前缀，例如 GET https://<你的节点域名>/api/v1/status。
  • 少量控制面接口不带前缀，直接位于根路径：/control/status、/control/version、/control/lock、/control/unlock、/node/stop。
  • 请求与响应均为 JSON（部分导入接口使用二进制体）。金额字段区分聪（_sats）与毫聪（_msat），链上费率使用 fee_rate_sats_per_vb（聪/vB）。u64 数量的数值以十进制字符串返回，避免 JSON 数值精度损失。

鉴权与访问 ​

节点运行时接口使用该节点自身的凭证。数据面 /api/v1/* 与控制面 /control/* 使用各自独立的 Bearer 令牌。

Cloud 托管节点由 Cloud 管理 API 管理生命周期；管理 API Key 不是节点运行时凭证，不能用于调用本组接口。节点域名可达不等于已获得运行时访问授权，访问方式与边界见 运行时 API 范围。

bash
curl -X GET https://<你的节点域名>/api/v1/status \
  -H "Authorization: Bearer <节点凭证>"

API 章节 ​

核心操作 ​

比特币层 ​

闪电网络 ​

RGB 协议 ​

  • RGB 操作 — RGB 钱包、合约、发行、链上转账与 RGB 闪电支付

高级功能 ​

节点状态与信息 ​

GET /api/v1/healthz ​

存活探针，用于进程存活检查。

响应:

json
{
  "ok": true,
  "checks": [
    { "name": "bitcoin", "ok": true, "detail": "chain synced" }
  ]
}

checks 为可选数组，每项包含 name、ok，以及可选的 detail、hint。

GET /api/v1/readyz ​

就绪探针，用于判断节点是否可以对外服务。就绪时返回 200；未就绪时返回非 2xx。

响应: 与 healthz 相同的 ok / checks 结构。

GET /api/v1/status ​

获取节点运行状态。

响应:

json
{
  "is_running": true,
  "is_listening": true,
  "best_block_height": 250000
}

GET /api/v1/version ​

获取节点软件版本信息。

响应:

json
{
  "api_version": "0.7.0",
  "api_crate_version": "0.7.0-bitlight.2",
  "core_crate_version": "0.7.0-bitlight.2"
}

GET /api/v1/node_id ​

获取节点公钥（secp256k1 压缩公钥，66 位十六进制）。

响应:

json
{
  "node_id": "02abc123def456..."
}

GET /api/v1/listening_addresses ​

获取节点的 Lightning 监听地址。

响应:

json
{
  "addresses": ["[email protected]:9735"]
}

GET /api/v1/balances ​

获取链上与闪电网络余额，以及 RGB 余额汇总。

响应:

json
{
  "btc": {
    "onchain_total_sats": "500000",
    "onchain_spendable_sats": "480000",
    "anchor_channels_reserve_sats": "10000",
    "lightning_total_sats": "300000"
  },
  "rgb": {
    "l1": [
      {
        "contract_id": "contract:...",
        "mined": "1000",
        "tentative": "0",
        "offchain": "0",
        "archived": "0",
        "total": "1000"
      }
    ],
    "l2": [
      {
        "channel_id": "abc123...",
        "contract_id": "contract:...",
        "local_amount": "500",
        "remote_amount": "500"
      }
    ]
  }
}

btc.* 均为聪；rgb.l1 为链上 RGB 余额，rgb.l2 为通道内 RGB 余额，数量为原始资产单位。

控制面 ​

控制面接口不带 /api/v1 前缀。数据面与控制面使用不同令牌。

GET /control/status ​

获取节点锁定与运行状态，以及是否可安全加锁。

响应:

json
{
  "locked": true,
  "running": true,
  "lockable": true
}

ok、running、lockable、checks 为可选字段。

GET /control/version ​

获取控制面版本信息。

响应:

json
{
  "ok": true,
  "protocol": "1",
  "daemon": "rgbldkd",
  "daemon_version": "0.7.0-bitlight.2"
}

POST /control/unlock ​

解锁已锁定的节点。

请求:

json
{
  "passphrase": "<keystore 口令>"
}

响应: ControlStatusDto（与 GET /control/status 相同结构）。

POST /control/lock ​

锁定运行中的节点。

请求:

json
{
  "yes": true,
  "force": false
}

yes 为必填确认字段；force 可选。响应: ControlStatusDto。

POST /node/stop ​

停止节点进程（无 /api/v1 前缀）。

响应:

json
{ "ok": true }

对等体管理 ​

GET /api/v1/peers ​

列出节点当前的对等体。

响应:

json
[
  {
    "node_id": "02def456...",
    "address": "203.0.113.20:9735",
    "is_persisted": true,
    "is_connected": true
  }
]

POST /api/v1/peers/connect ​

连接远程闪电节点。

请求:

json
{
  "node_id": "02def456...",
  "address": "203.0.113.20:9735",
  "persist": true
}

node_id 与 address 必填；persist 可选，为 true 时在重连后保持该对等体。

响应:

json
{ "ok": true }

POST /api/v1/peers/disconnect ​

断开与对等节点的连接。

请求:

json
{
  "node_id": "02def456..."
}

响应:

json
{ "ok": true }

Cloud 托管节点的入站 P2P 地址通过 Cloud 管理 API 的 p2p_* 字段申请，不能把 HTTPS API 域名当作 P2P 地址。

事件流 ​

节点通过长轮询事件队列向调用方推送状态变化。

POST /api/v1/events/wait_next ​

阻塞等待下一个节点事件，直到有事件或超时。

请求:

json
{
  "timeout_secs": 25
}

响应: 单个事件对象，type 与 data 字段。type 取值包括：

  • PaymentSuccessful — data.payment_id、data.fee_paid_msat
  • PaymentFailed — data.payment_id
  • PaymentReceived — data.payment_id、data.payment_hash、data.amount_msat、可选 data.custom_records、可选 data.rgb
  • ChannelPending — data.funding_txo
  • ChannelReady — data.user_channel_id
  • ChannelClosed — data.channel_id、data.user_channel_id、可选 data.counterparty_node_id、可选 data.reason
  • SplicePending — 可选 data.channel_id、data.user_channel_id
  • SpliceFailed — 可选 data.channel_id、data.user_channel_id、可选 data.reason
  • Other — data.kind

长轮询超时时间应设置在基础设施的网关超时之内，避免网关先行断开连接。

POST /api/v1/events/handled ​

通知节点当前事件已处理完毕，以便推送下一个事件。

响应:

json
{ "ok": true }

钱包操作 ​

POST /api/v1/wallet/address/new ​

生成新的链上比特币接收地址（推进派生索引）。

响应:

json
{
  "address": "tb1q..."
}

GET /api/v1/wallet/address/current ​

返回最近一次生成的链上地址，不推进派生索引。节点尚未初始化地址时返回 404。

响应:

json
{
  "address": "tb1q..."
}

POST /api/v1/wallet/sync ​

同步链上钱包状态。

响应:

json
{ "ok": true }

GET /api/v1/wallet/utxos ​

列出普通 L1 钱包 UTXO。节点会排除绑定 RGB 资产的 UTXO，因此该接口是纯 BTC 操作（开通道、链上发送）的权威余额来源。

查询参数: refresh=true 时先与索引器核对确认高度。

响应:

json
{
  "utxos": [
    {
      "outpoint": "txid:0",
      "value_sats": "100000",
      "confirmation": { "status": "confirmed", "height": 250000 },
      "lock": { "locked": false, "kind": "none" }
    }
  ]
}

confirmation.status 为 confirmed 或 mempool；lock.kind 为 none、manual_reservation 或 operation。

POST /api/v1/wallet/send ​

发送链上 BTC（排除 RGB 着色 UTXO）。

请求:

json
{
  "address": "tb1q...",
  "amount_sats": "10000",
  "fee_rate_sats_per_vb": 1.5
}

响应:

json
{
  "txid": "abc123..."
}

POST /api/v1/wallet/send_all ​

把链上 BTC 全部发送到指定地址（排除 RGB 着色 UTXO）。

请求:

json
{
  "address": "tb1q...",
  "retain_reserves": true,
  "fee_rate_sats_per_vb": 1.5
}

retain_reserves 为 true 时保留通道储备，避免影响在途通道。

响应:

json
{
  "txid": "abc123..."
}

UTXO 管理 ​

GET /api/v1/wallet/utxo/status ​

查询单个 outpoint 的状态（只读，不同步钱包、不解除预留）。

查询参数: outpoint=txid:vout。

响应:

json
{
  "outpoint": "txid:0",
  "account_id": "...",
  "scope_id": "...",
  "value_sats": "100000",
  "onchain_state": "...",
  "availability": "...",
  "selectable": true,
  "operation": null,
  "lock": null,
  "unavailable_reason": null
}

POST /api/v1/rgb/utxos/release ​

释放一条 RGB UTXO 预留。

请求:

json
{
  "reservation_id": "resv_abc123"
}

reservation_id 与 outpoint 二选一即可。

响应:

json
{
  "released": true
}

RGB 钱包 UTXO 的完整操作（fund、top_up、sweep）见 RGB 操作。

网络图谱 ​

用于在开通道或支付前预检对等体可达性与路由。

GET /api/v1/network_graph/nodes ​

列出图谱中已知的节点公钥（hex）。

响应:

json
{
  "nodes": ["02abc123...", "03def456..."]
}

GET /api/v1/network_graph/node/ ​

按节点公钥查询节点信息。

响应:

json
{
  "announcement_info": {
    "last_update": 1704067200,
    "alias": "example-node",
    "addresses": ["203.0.113.20:9735"]
  },
  "channels": [144927727168913409]
}

announcement_info 可能为 null。

GET /api/v1/network_graph/channels ​

列出图谱中已知的 short channel ID。

响应:

json
{
  "channels": [144927727168913409]
}

GET /api/v1/network_graph/channel/ ​

按 short channel ID 查询通道信息。

响应:

json
{
  "node_one": "02abc123...",
  "node_two": "03def456...",
  "capacity_sats": "1000000",
  "one_to_two": {
    "last_update": 1704067200,
    "enabled": true,
    "cltv_expiry_delta": 40,
    "htlc_minimum_msat": "1000",
    "htlc_maximum_msat": "990000000",
    "fee_base_msat": 1000,
    "fee_proportional_millionths": 1
  },
  "two_to_one": null
}

详细文档 ​

  • 通道管理 — 通道生命周期、RGB 通道与关闭流程
  • 支付操作 — BOLT11、BOLT12、自发支付与支付状态
  • RGB 操作 — RGB 钱包、合约、发行、链上转账与 RGB 闪电支付
  • 原子交换 — 报价、接受、执行与交换状态

错误处理 ​

非 2xx 响应返回 JSON，其中 error 为机器可读错误码（例如 DuplicatePayment），message 为可读信息：

json
{
  "error": "DuplicatePayment",
  "message": "Payment with this hash already in progress"
}

响应头 X-Request-Id 可用于问题排查。涉及资金的接口在超时或连接中断后可能已改变节点状态，应通过余额与支付/通道查询接口重新核对，而不是直接重试。

交易并保护您的 RGB 资产 | 释放 RGB 协议的全部潜力

© 2026 Stash Labs. All rights reserved.