Lightning Channel Order APIs

Overview

The RGB LSPS1 APIs let clients order Lightning channels with RGB asset allocation from a Lightning Service Provider (LSP). Use these endpoints when you need to:

Open a channel with RGB assets pre-allocated — the LSP opens the channel and pre-funds it with the requested asset amount on the LSP side.
Query LSP capabilities — check supported assets, min/max channel sizes, and fee structures before creating an order.
Track channel order status — poll an order until the channel is confirmed and open.

These endpoints are used by the KaleidoSwap Desktop App when you open a channel through the default LSP. SDK users can call them directly via client.maker.createLspOrder(). Base URL: https://api.signet.kaleidoswap.com/api/v1 (Signet)

Get LSP Information

Endpoint

GET /api/v1/lsps1/get_info

Description

Retrieve information about the RGB Lightning Service Provider, including available assets, liquidity options, and channel configurations.

Response Structure

lsp_connection_url: The LSP node’s connection URI (pubkey@host:port) — connect to this peer before ordering a channel.
options: Configuration settings for orders and channels.
assets: List of assets managed by the LSP.

Example Response

{
  "lsp_connection_url": "034eedc97802d7e2766704bd06d6bfded8aa2d35a1a007e277fd7278f3dc962706@lsp.signet.kaleidoswap.com:9735",
  "options": {
    "min_required_channel_confirmations": 0,
    "min_funding_confirms_within_blocks": 0,
    "min_onchain_payment_confirmations": 0,
    "supports_zero_channel_reserve": true,
    "min_onchain_payment_size_sat": 0,
    "max_channel_expiry_blocks": 30160,
    "min_initial_client_balance_sat": 0,
    "max_initial_client_balance_sat": 100000000,
    "min_initial_lsp_balance_sat": 0,
    "max_initial_lsp_balance_sat": 100000000,
    "min_channel_balance_sat": 50000,
    "max_channel_balance_sat": 100000000
  },
  "assets": [
    {
      "name": "Tether USD",
      "asset_id": "rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB",
      "ticker": "USDT",
      "precision": 6,
      "issued_supply": 100000000000,
      "min_initial_client_amount": 0,
      "max_initial_client_amount": 0,
      "min_initial_lsp_amount": 0,
      "max_initial_lsp_amount": 1000000,
      "min_channel_amount": 0,
      "max_channel_amount": 1000000
    }
  ]
}

Get Network Information

Endpoint

GET /api/v1/lsps1/network_info

Description

Retrieve the LSP node’s current blockchain height and network. Safe to poll and cache.

Example Response

{
  "network": "Signet",
  "height": 805434
}

Estimate Fees

Endpoint

POST /api/v1/lsps1/estimate_fees

Description

Estimate the fees for a channel order without creating one. When the client is purchasing assets (client_asset_amount > 0), a fresh rfq_id from /market/quote is required so the asset price can be folded into the total.

Request Body

Field	Type	Description
`lsp_balance_sat`	Integer	Balance in satoshis for the LSP side of the channel.
`client_balance_sat`	Integer	Balance in satoshis for the client side of the channel.
`channel_expiry_blocks`	Integer	Number of blocks after which the channel expires.
`token` (optional)	String	Discount or referral token.
`asset_id` (optional)	String	ID of the RGB asset for the channel.
`lsp_asset_amount` (optional)	Integer	Amount of RGB asset for the LSP side.
`client_asset_amount` (optional)	Integer	Amount of RGB asset for the client side.
`rfq_id` (optional)	String	Quote ID — required when `client_asset_amount > 0`.

Example Response

{
  "setup_fee": 1000,
  "capacity_fee": 1500,
  "duration_fee": 500,
  "total_fee": 3000,
  "applied_discount": null,
  "discount_code": null
}

Create Order

Endpoint

POST /api/v1/lsps1/create_order

Description

Create a new order for a channel with the RGB Lightning Service Provider.

Request Body

Field	Type	Description
`client_pubkey`	String	Public key of the client (required).
`lsp_balance_sat`	Integer	Balance in satoshis for the LSP side of the channel.
`client_balance_sat`	Integer	Balance in satoshis for the client side of the channel.
`required_channel_confirmations`	Integer	Number of confirmations required for the channel.
`funding_confirms_within_blocks`	Integer	Number of blocks within which funding should be confirmed.
`channel_expiry_blocks`	Integer	Number of blocks after which the channel expires.
`token` (optional)	String	Discount or referral token applied to the order fees.
`refund_onchain_address` (optional)	String	On-chain address to refund the payment to if the order fails or is declined.
`announce_channel`	Boolean	Whether to announce the channel publicly.
`asset_id` (optional)	String	ID of the RGB asset for the channel.
`lsp_asset_amount` (optional)	Integer	Amount of RGB asset for the LSP side.
`client_asset_amount` (optional)	Integer	Amount of RGB asset for the client side.
`rfq_id` (optional)	String	Quote ID from `/market/quote`. Required when `client_asset_amount > 0` — the client is purchasing assets, so a fresh quote must back the order.
`email` (optional)	String	Email address for order notifications.

Example Request

{
  "client_pubkey": "03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad",
  "lsp_balance_sat": 100000,
  "client_balance_sat": 50000,
  "required_channel_confirmations": 3,
  "funding_confirms_within_blocks": 144,
  "channel_expiry_blocks": 4032,
  "announce_channel": true,
  "asset_id": "rgb:$i4cFKwt-2C5LZ3X-l$kOTGN-O6l1AOP-aP9COyn-7IeBkEM",
  "lsp_asset_amount": 5000,
  "client_asset_amount": 2500,
  "rfq_id": "8e6635fb-ab37-4aed-89f4-bc9c98fb8b49",
  "refund_onchain_address": "tb1qexampleaddress0000000000000000000000000",
  "email": "ops@example.com"
}

Response Body

Field	Type	Description
`order_id`	String	Unique identifier for the created order.
`client_pubkey`	String	The public key of the client.
`lsp_balance_sat`	Integer	The balance in satoshis for the LSP side of the channel.
`client_balance_sat`	Integer	The balance in satoshis for the client side of the channel.
`required_channel_confirmations`	Integer	The number of confirmations required for the channel.
`funding_confirms_within_blocks`	Integer	The number of blocks within which funding should be confirmed.
`channel_expiry_blocks`	Integer	The number of blocks after which the channel expires.
`token`	String / Null	The token associated with the order (if provided).
`created_at`	String date-time	Timestamp of order creation.
`announce_channel`	Boolean	Whether the channel will be announced publicly.
`order_state`	String	Current state of the order: `CREATED`, `CHANNEL_OPENING`, `COMPLETED`, `FAILED`, or `PENDING_RATE_DECISION`.
`payment`	Object	Payment details including fees, invoice or on-chain address. Payment expiries live in `payment.bolt11.expires_at` and `payment.onchain.expires_at` — there is no top-level `expires_at`.
`channel` (optional)	Object / Null	Channel details if the channel has been created (its expiry is `channel.expires_at`).
`asset_id` (optional)	String / Null	The ID of the RGB asset for the channel.
`lsp_asset_amount` (optional)	Integer / Null	The amount of RGB asset for the LSP side.
`client_asset_amount` (optional)	Integer / Null	The amount of RGB asset for the client side.
`rfq_id` (optional)	String / Null	The quote ID the order was created against.
`asset_price_sat` (optional)	Integer / Null	BTC price (in satoshis) paid for `client_asset_amount`.
`failure_reason` (optional)	String / Null	Reason the order failed, when `order_state` is `FAILED`.
`access_token`	String	Per-order token required for `get_order` and `rate_decision`. Returned only here at creation — store it with the order ID.

Example Response

{
  "order_id": "string",
  "client_pubkey": "string",
  "lsp_balance_sat": 0,
  "client_balance_sat": 0,
  "required_channel_confirmations": 0,
  "funding_confirms_within_blocks": 0,
  "channel_expiry_blocks": 0,
  "token": "",
  "created_at": "2024-12-18T19:09:19.868Z",
  "announce_channel": true,
  "order_state": "CREATED",
  "payment": {
    "bolt11": {
      "state": "EXPECT_PAYMENT",
      "expires_at": "2024-12-18T19:09:19.868Z",
      "fee_total_sat": 0,
      "order_total_sat": 0,
      "invoice": "string"
    },
    "onchain": {
      "state": "EXPECT_PAYMENT",
      "expires_at": "2024-12-18T19:09:19.868Z",
      "fee_total_sat": 0,
      "order_total_sat": 0,
      "address": "string",
      "min_fee_for_0conf": 0,
      "min_onchain_payment_confirmations": 0,
      "refund_onchain_address": "string"
    }
  },
  "channel": null,
  "asset_id": "string",
  "lsp_asset_amount": 0,
  "client_asset_amount": 0,
  "rfq_id": "8e6635fb-ab37-4aed-89f4-bc9c98fb8b49",
  "asset_price_sat": 0,
  "failure_reason": null,
  "access_token": "ord_live_3rCkP9dG7mN4"
}

Get Order

Endpoint

POST /api/v1/lsps1/get_order

Description

Retrieve information about an existing order. This endpoint is safe to poll.

Request Body

Field	Type	Description
`order_id`	String	Unique identifier of the order.
`access_token`	String	The per-order access token returned by `create_order`.

Example Request

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token": "ord_live_3rCkP9dG7mN4"
}

An invalid access_token returns a 400 error; an unknown order_id returns a 404.

Example Response

The response structure is identical to the create_order endpoint.

Rate Decision

Endpoint

POST /api/v1/lsps1/rate_decision

Description

Resolve a repricing event on an asset-backed order. If the market rate moves significantly before the payment settles, the LSP moves the order into the PENDING_RATE_DECISION state instead of opening the channel. The client must then either accept the new rate (the order proceeds with fresh pricing) or decline it (a refund is initiated to the refund_onchain_address).

Request Body

Field	Type	Description
`order_id`	String	Unique identifier of the order.
`access_token`	String	The per-order access token returned by `create_order`.
`accept_new_rate`	Boolean	`true` to accept the new rate, `false` to request a refund.

Example Request

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token": "ord_live_3rCkP9dG7mN4",
  "accept_new_rate": true
}

Example Response

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "decision_accepted": true,
  "message": "Rate accepted. Order will proceed with current market rate.",
  "refund_txid": null
}

Calling this endpoint on an order that is not in the PENDING_RATE_DECISION state returns a 400 error. When a refund is requested and processed, refund_txid carries the on-chain transaction ID.

For more details about trading and market operations, proceed to Market APIs.

Introduction

Guides

Endpoints

Overview

Get LSP Information

Endpoint

Description

Response Structure

Example Response

Get Network Information

Endpoint

Description

Example Response

Estimate Fees

Endpoint

Description

Request Body

Example Response

Create Order

Endpoint

Description

Request Body

Example Request

Response Body

Example Response

Get Order

Endpoint

Description

Request Body

Example Request

Example Response

Rate Decision

Endpoint

Description

Request Body

Example Request

Example Response

​Overview

​Get LSP Information

​Endpoint

​Description

​Response Structure

​Example Response

​Get Network Information

​Endpoint

​Description

​Example Response

​Estimate Fees

​Endpoint

​Description

​Request Body

​Example Response

​Create Order

​Endpoint

​Description

​Request Body

​Example Request

​Response Body

​Example Response

​Get Order

​Endpoint

​Description

​Request Body

​Example Request

​Example Response

​Rate Decision

​Endpoint

​Description

​Request Body

​Example Request

​Example Response

Overview

Get LSP Information

Endpoint

Description

Response Structure

Example Response

Get Network Information

Endpoint

Description

Example Response

Estimate Fees

Endpoint

Description

Request Body

Example Response

Create Order

Endpoint

Description

Request Body

Example Request

Response Body

Example Response

Get Order

Endpoint

Description

Request Body

Example Request

Example Response

Rate Decision

Endpoint

Description

Request Body

Example Request

Example Response