Lightning API Reference

Create a Lightning invoice for receiving BTC or asset payments

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/create-invoice

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Body

application/json

amount_satsnumberOptional

Amount in satoshis for BTC invoice

expiry_secondsnumberOptional

Optional invoice expiration time in seconds

Responses

200

Successful response

application/json

idstringRequired

Invoice request ID

invoicestringRequired

Lightning invoice string

statusstring · enumRequired

Invoice status

Possible values:

payment_typestring · enumRequired

Payment type

Possible values:

amount_satsnumberOptional

Amount in satoshis (for BTC invoices)

created_atstringRequired

Creation timestamp

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/create-invoice

HTTPcURLJavaScriptPython

POST /lightning/create-invoice HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "amount_sats": 1,
  "asset": {
    "asset_id": "text",
    "amount": 1
  },
  "expiry_seconds": 1
}

{
  "id": "text",
  "invoice": "text",
  "status": "OPEN",
  "payment_type": "BTC",
  "amount_sats": 1,
  "asset": {
    "asset_id": "text",
    "amount": 1
  },
  "created_at": "text"
}

Get the status of a Lightning invoice by request ID

get

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/receive-request/{request_id}

Path parameters

request_idstringRequired

The request_id parameter

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Responses

200

Successful response

application/json

idstringRequired

Invoice request ID

invoicestringRequired

Lightning invoice string

statusstring · enumRequired

Invoice status

Possible values:

payment_typestring · enumRequired

Payment type

Possible values:

amount_satsnumberOptional

Amount in satoshis (for BTC invoices)

created_atstringRequired

Creation timestamp

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/lightning/receive-request/{request_id}

HTTPcURLJavaScriptPython

GET /lightning/receive-request/{request_id} HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Accept: */*

{
  "id": "text",
  "invoice": "text",
  "status": "OPEN",
  "payment_type": "BTC",
  "amount_sats": 1,
  "asset": {
    "asset_id": "text",
    "amount": 1
  },
  "created_at": "text"
}

Begin a Lightning invoice payment process

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/pay-invoice-begin

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Body

application/json

invoicestringRequired

Lightning invoice to pay

max_fee_satsnumberRequired

Maximum fee in satoshis you're willing to pay

Responses

200

Successful response

application/json

stringOptional

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/pay-invoice-begin

HTTPcURLJavaScriptPython

POST /lightning/pay-invoice-begin HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "invoice": "text",
  "max_fee_sats": 1
}

text

Complete a Lightning invoice payment using signed PSBT

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/pay-invoice-end

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Body

application/json

signed_psbtstringRequired

Signed PSBT in base64

Responses

200

Successful response

application/json

idstringRequired

Send request ID

statusstring · enumRequired

Payment status

Possible values:

payment_typestring · enumRequired

Payment type

Possible values:

amount_satsnumberOptional

Amount in satoshis

fee_satsnumberOptional

Fee paid in satoshis

created_atstringRequired

Creation timestamp

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/pay-invoice-end

HTTPcURLJavaScriptPython

POST /lightning/pay-invoice-end HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "signed_psbt": "text"
}

{
  "id": "text",
  "status": "PENDING",
  "payment_type": "BTC",
  "amount_sats": 1,
  "asset": {
    "asset_id": "text",
    "amount": 1
  },
  "fee_sats": 1,
  "created_at": "text"
}

Estimate the routing fee required to pay a Lightning invoice

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/fee-estimate

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Body

application/json

invoicestringRequired

Lightning invoice to pay

Responses

200

Successful response

application/json

numberOptional

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/fee-estimate

HTTPcURLJavaScriptPython

POST /lightning/fee-estimate HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Content-Type: application/json
Accept: */*
Content-Length: 57

{
  "invoice": "text",
  "asset": {
    "asset_id": "text",
    "amount": 1
  }
}

1

List Lightning payments

get

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/listpayments

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Responses

200

Successful response

application/json

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/lightning/listpayments

HTTPcURLJavaScriptPython

GET /lightning/listpayments HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Accept: */*

{
  "payments": [
    {
      "amt_msat": 1,
      "asset_amount": 1,
      "asset_id": "text",
      "payment_hash": "text",
      "inbound": true,
      "status": "Pending",
      "created_at": 1,
      "updated_at": 1,
      "payee_pubkey": "text"
    }
  ]
}

Get the status of a Lightning payment by request ID

get

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/send-request/{request_id}

Path parameters

request_idstringRequired

The request_id parameter

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Responses

200

Successful response

application/json

idstringRequired

Send request ID

statusstring · enumRequired

Payment status

Possible values:

payment_typestring · enumRequired

Payment type

Possible values:

amount_satsnumberOptional

Amount in satoshis

fee_satsnumberOptional

Fee paid in satoshis

created_atstringRequired

Creation timestamp

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/lightning/send-request/{request_id}

HTTPcURLJavaScriptPython

GET /lightning/send-request/{request_id} HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Accept: */*

{
  "id": "text",
  "status": "PENDING",
  "payment_type": "BTC",
  "amount_sats": 1,
  "asset": {
    "asset_id": "text",
    "amount": 1
  },
  "fee_sats": 1,
  "created_at": "text"
}

Get an on-chain receive address for receiving assets

get

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/onchain-receive

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Responses

200

Successful response

application/json

btc_addressstringRequired

Bitcoin address for deposit

asset_invoicestringRequired

RGB asset invoice string

expires_atstringOptional

Optional expiration timestamp

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/lightning/onchain-receive

HTTPcURLJavaScriptPython

GET /lightning/onchain-receive HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Accept: */*

{
  "btc_address": "text",
  "asset_invoice": "text",
  "expires_at": "text"
}

Get wallet balance including BTC and asset balances

get

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/balance

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Responses

200

Successful response

application/json

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/lightning/balance

HTTPcURLJavaScriptPython

GET /lightning/balance HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Accept: */*

{
  "balance": {
    "vanilla": {
      "settled": 1,
      "future": 1,
      "spendable": 1
    },
    "colored": {
      "settled": 1,
      "future": 1,
      "spendable": 1
    },
    "offchain_balance": {
      "total": 1,
      "details": [
        {
          "expiry_time": "text",
          "amount": 1
        }
      ]
    }
  },
  "asset_balances": [
    {
      "asset_id": "text",
      "ticker": "text",
      "precision": 1,
      "balance": {
        "settled": 1,
        "future": 1,
        "spendable": 1,
        "offchain_outbound": 1
      }
    }
  ]
}

Settle balances in the wallet

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/settle

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Responses

200

Successful response

application/json

Settlement result object

Other propertiesanyOptional

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/settle

HTTPcURLJavaScriptPython

POST /lightning/settle HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Begin an on-chain send process from UTEXO

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/onchain-send-begin

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Body

application/json

address_or_rgbinvoicestringRequired

Bitcoin on-chain address or RGB invoice string

amount_satsnumberOptional

Amount in satoshis to send (optional)

fee_ratenumberRequired

Fee rate used to build the Bitcoin transaction

Responses

200

Successful response

application/json

stringOptional

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/onchain-send-begin

HTTPcURLJavaScriptPython

POST /lightning/onchain-send-begin HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "address_or_rgbinvoice": "text",
  "amount_sats": 1,
  "fee_rate": 1,
  "asset": {
    "asset_id": "text",
    "amount": 1
  }
}

text

Complete an on-chain send from UTEXO using signed PSBT

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/onchain-send-end

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Body

application/json

signed_psbtstringRequired

Signed PSBT in base64

Responses

200

Successful response

application/json

send_idstringRequired

Unique on-chain send identifier

txidstringOptional

Bitcoin transaction id (if available)

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/onchain-send-end

HTTPcURLJavaScriptPython

POST /lightning/onchain-send-end HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "signed_psbt": "text"
}

{
  "send_id": "text",
  "txid": "text"
}

Get the status of an on-chain send by send ID

get

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/onchain-send/{send_id}

Path parameters

send_idstringRequired

The send_id parameter

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Responses

200

Successful response

application/json

send_idstringRequired

On-chain send identifier

statusstringRequired

Current on-chain send status

address_or_rgbinvoicestringRequired

Bitcoin address or RGB invoice used for on-chain send

amount_sats_requestednumberOptional

Amount in satoshis that was requested

amount_sats_sentnumberOptional

Amount in satoshis that was actually sent

close_txidsstring[]Required

Array of close transaction IDs

sweep_txidstringOptional

Sweep transaction ID if available

fee_satsnumberOptional

Fee paid in satoshis

error_codestringOptional

Error code if on-chain send failed

error_messagestringOptional

Error message if on-chain send failed

retryablebooleanRequired

Whether the on-chain send can be retried

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

get

/onchain-send/{send_id}

HTTPcURLJavaScriptPython

GET /onchain-send/{send_id} HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Accept: */*

{
  "send_id": "text",
  "status": "text",
  "address_or_rgbinvoice": "text",
  "amount_sats_requested": 1,
  "amount_sats_sent": 1,
  "asset": {
    "asset_id": "text",
    "amount": 1
  },
  "close_txids": [
    "text"
  ],
  "sweep_txid": "text",
  "fee_sats": 1,
  "timestamps": {
    "ANY_ADDITIONAL_PROPERTY": 1
  },
  "error_code": "text",
  "error_message": "text",
  "retryable": true
}

List on-chain transfers for a specific asset

post

https://rgb-node.thunderstack.orghttps://rgb-node.test.thunderstack.orghttp://127.0.0.1:8000

/lightning/listtransfers

Header parameters

xpub-vanstringRequired

Vanilla extended public key

xpub-colstringRequired

Colored extended public key

master-fingerprintstringRequired

Master fingerprint

Body

application/json

asset_idstringRequired

Asset ID to list transfers for

Responses

200

Successful response

application/json

idxnumberRequired

batch_transfer_idxnumberRequired

created_atnumberRequired

updated_atnumberRequired

statusnumber · enumRequired

0=WAITING_COUNTERPARTY, 1=WAITING_CONFIRMATIONS, 2=SETTLED, 3=FAILED

Possible values:

amountnumberRequired

kindnumber · enumRequired

Transfer kind: 0=ISSUANCE, 1=RECEIVE_BLIND, 2=RECEIVE_WITNESS, 3=SEND, 4=INFLATION

Possible values:

txidstring · nullableOptional

recipient_idstringRequired

expirationnumberRequired

400

RGB library error

application/json

404

Not found

application/json

500

Internal server error

application/json

post

/lightning/listtransfers

HTTPcURLJavaScriptPython

POST /lightning/listtransfers HTTP/1.1
Host: rgb-node.thunderstack.org
xpub-van: text
xpub-col: text
master-fingerprint: text
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "asset_id": "text"
}

[
  {
    "idx": 1,
    "batch_transfer_idx": 1,
    "created_at": 1,
    "updated_at": 1,
    "status": 0,
    "amount": 1,
    "kind": 0,
    "txid": "text",
    "recipient_id": "text",
    "receive_utxo": {
      "txid": "text",
      "vout": 1
    },
    "change_utxo": {
      "txid": "text",
      "vout": 1
    },
    "expiration": 1,
    "transport_endpoints": [
      {
        "endpoint": "text",
        "transport_type": 1,
        "used": true
      }
    ]
  }
]