Stash Labs

English

中文

English

中文

Appearance

RGB Lightning Node API Reference ​

The RGB Lightning Node is an RGB-enabled Lightning node implementation built on LDK (Lightning Development Kit), developed by Bitlight Labs and orchestrated by Stash Cloud. The node process (rgbldkd) exposes a complete HTTP API for managing Lightning channels, making payments and handling RGB assets over the Lightning Network.

These pages follow the node's real endpoints. Paths and fields match the node HTTP client implementation; no unverified request body is reproduced.

Base URL and calls ​

The node API runs on each node's dedicated domain:

https://<your-node-domain>
  • Data-plane endpoints share the /api/v1 prefix, for example GET https://<your-node-domain>/api/v1/status.
  • A few control-plane endpoints have no prefix and sit on the root path: /control/status, /control/version, /control/lock, /control/unlock, /node/stop.
  • Requests and responses are JSON (some import endpoints take a binary body). Amount fields distinguish sats (_sats) from millisatoshis (_msat); on-chain fee rates use fee_rate_sats_per_vb (sats/vB). u64 quantities are returned as decimal strings to avoid JSON number precision loss.

Authentication and access ​

Node runtime endpoints use the node's own credentials. The data plane (/api/v1/*) and the control plane (/control/*) use separate Bearer tokens.

Cloud-managed nodes have their lifecycle managed by the Cloud management API; the management API Key is not a node runtime credential and cannot call these endpoints. Reaching a node domain does not by itself grant runtime access. See Runtime API scope for the boundary.

bash
curl -X GET https://<your-node-domain>/api/v1/status \
  -H "Authorization: Bearer <node-credential>"

API sections ​

Core operations ​

Bitcoin layer ​

Lightning Network ​

RGB protocol ​

  • RGB operations — RGB wallet, contracts, issuance, on-chain transfers and RGB Lightning payments

Advanced features ​

Node status & info ​

GET /api/v1/healthz ​

Liveness probe for process health.

Response:

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

checks is optional; each entry has name, ok and optional detail / hint.

GET /api/v1/readyz ​

Readiness probe. Returns 200 when the node can serve; otherwise a non-2xx status.

Response: the same ok / checks structure as healthz.

GET /api/v1/status ​

Get the node run state.

Response:

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

GET /api/v1/version ​

Get node software version information.

Response:

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 ​

Get the node public key (secp256k1 compressed, 66 hex characters).

Response:

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

GET /api/v1/listening_addresses ​

Get the node's Lightning listening addresses.

Response:

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

GET /api/v1/balances ​

Get on-chain and Lightning balances plus the RGB balance summary.

Response:

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.* fields are sats; rgb.l1 is on-chain RGB balance and rgb.l2 is in-channel RGB balance, in raw asset units.

Control plane ​

Control-plane endpoints have no /api/v1 prefix. The data plane and control plane use different tokens.

GET /control/status ​

Get node lock/run state and whether it is safe to lock now.

Response:

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

ok, running, lockable and checks are optional fields.

GET /control/version ​

Get control-plane version information.

Response:

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

POST /control/unlock ​

Unlock a locked node.

Request:

json
{
  "passphrase": "<keystore-passphrase>"
}

Response: ControlStatusDto (same structure as GET /control/status).

POST /control/lock ​

Lock a running node.

Request:

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

yes is a required confirmation field; force is optional. Response: ControlStatusDto.

POST /node/stop ​

Stop the node process (no /api/v1 prefix).

Response:

json
{ "ok": true }

Peer management ​

GET /api/v1/peers ​

List the node's current peers.

Response:

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

POST /api/v1/peers/connect ​

Connect to a remote Lightning node.

Request:

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

node_id and address are required; persist is optional and keeps the peer across reconnects when true.

Response:

json
{ "ok": true }

POST /api/v1/peers/disconnect ​

Disconnect from a peer.

Request:

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

Response:

json
{ "ok": true }

For Cloud-managed nodes, apply for the inbound P2P address through the p2p_* fields of the Cloud management API; never treat the HTTPS API domain as a P2P address.

Event stream ​

The node pushes state changes to callers through a long-poll event queue.

POST /api/v1/events/wait_next ​

Block until the next node event or timeout.

Request:

json
{
  "timeout_secs": 25
}

Response: a single event object with type and data. type values include:

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

Keep the long-poll timeout below the infrastructure gateway timeout so the gateway does not cut the connection first.

POST /api/v1/events/handled ​

Tell the node the current event has been handled so it can push the next one.

Response:

json
{ "ok": true }

Wallet operations ​

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

Generate a new on-chain Bitcoin receiving address (advances the derivation index).

Response:

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

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

Return the most recently generated on-chain address without advancing the derivation index. Returns 404 when the node has not initialized an address yet.

Response:

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

POST /api/v1/wallet/sync ​

Synchronize on-chain wallet state.

Response:

json
{ "ok": true }

GET /api/v1/wallet/utxos ​

List plain L1 wallet UTXOs. The node excludes UTXOs bound to RGB assets, so this endpoint is the authoritative balance source for pure BTC operations (opening channels, on-chain sends).

Query parameter: refresh=true reconciles confirmation heights with the indexer first.

Response:

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

confirmation.status is confirmed or mempool; lock.kind is none, manual_reservation or operation.

POST /api/v1/wallet/send ​

Send on-chain BTC (excluding RGB-colored UTXOs).

Request:

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

Response:

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

POST /api/v1/wallet/send_all ​

Send all on-chain BTC to the specified address (excluding RGB-colored UTXOs).

Request:

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

retain_reserves: true keeps channel reserves and avoids affecting channels in flight.

Response:

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

UTXO management ​

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

Query one outpoint's status (read-only; does not sync the wallet or clear a reservation).

Query parameter: outpoint=txid:vout.

Response:

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 ​

Release an RGB UTXO reservation.

Request:

json
{
  "reservation_id": "resv_abc123"
}

Provide either reservation_id or outpoint.

Response:

json
{
  "released": true
}

Full RGB wallet UTXO operations (fund, top_up, sweep) are in RGB operations.

Network graph ​

Use these to pre-check peer reachability and routing before opening a channel or paying.

GET /api/v1/network_graph/nodes ​

List known node pubkeys (hex) in the graph.

Response:

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

GET /api/v1/network_graph/node/ ​

Get node info by pubkey.

Response:

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

announcement_info may be null.

GET /api/v1/network_graph/channels ​

List known short channel IDs in the graph.

Response:

json
{
  "channels": [144927727168913409]
}

GET /api/v1/network_graph/channel/ ​

Get channel info by short channel ID.

Response:

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
}

Detailed documentation ​

  • Channel management — channel lifecycle, RGB channels and closing flow
  • Payments — BOLT11, BOLT12, spontaneous payments and payment status
  • RGB operations — RGB wallet, contracts, issuance, on-chain transfers and RGB Lightning payments
  • Atomic swaps — offers, accept, execute and swap status

Error handling ​

Non-2xx responses return JSON where error is a machine-readable code (for example DuplicatePayment) and message is human-readable:

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

The X-Request-Id response header helps with troubleshooting. For funds-related endpoints, a timeout or dropped connection may still have changed node state; re-check balances and payment/channel queries rather than retrying blindly.

Trade and secure your RGB assets | Unlock the full potential of the RGB protocol

© 2026 Stash Labs. All rights reserved.