# Lightning API Reference ## POST /lightning/create-invoice > Create a Lightning invoice for receiving BTC or asset payments ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/create-invoice":{"post":{"tags":["Lightning"],"summary":"Create a Lightning invoice for receiving BTC or asset payments","operationId":"createLightningInvoice","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LightningReceiveRequest"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLightningInvoiceRequestModel"}}}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"LightningReceiveRequest":{"type":"object","properties":{"id":{"type":"string","description":"Invoice request ID"},"invoice":{"type":"string","description":"Lightning invoice string"},"status":{"type":"string","enum":["OPEN","SETTLED","EXPIRED","FAILED"],"description":"Invoice status"},"payment_type":{"type":"string","enum":["BTC","ASSET"],"description":"Payment type"},"amount_sats":{"type":"number","description":"Amount in satoshis (for BTC invoices)"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset invoices)"},"created_at":{"type":"string","description":"Creation timestamp"}},"required":["id","invoice","status","payment_type","created_at"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]},"CreateLightningInvoiceRequestModel":{"type":"object","properties":{"amount_sats":{"type":"number","description":"Amount in satoshis for BTC invoice"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details for asset invoice"},"expiry_seconds":{"type":"number","description":"Optional invoice expiration time in seconds"}}}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## GET /lightning/receive-request/{request\_id} > Get the status of a Lightning invoice by request ID ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/receive-request/{request_id}":{"get":{"tags":["Lightning"],"summary":"Get the status of a Lightning invoice by request ID","operationId":"getLightningReceiveRequest","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"},{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The request_id parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LightningReceiveRequest"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"LightningReceiveRequest":{"type":"object","properties":{"id":{"type":"string","description":"Invoice request ID"},"invoice":{"type":"string","description":"Lightning invoice string"},"status":{"type":"string","enum":["OPEN","SETTLED","EXPIRED","FAILED"],"description":"Invoice status"},"payment_type":{"type":"string","enum":["BTC","ASSET"],"description":"Payment type"},"amount_sats":{"type":"number","description":"Amount in satoshis (for BTC invoices)"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset invoices)"},"created_at":{"type":"string","description":"Creation timestamp"}},"required":["id","invoice","status","payment_type","created_at"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## POST /lightning/pay-invoice-begin > Begin a Lightning invoice payment process ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/pay-invoice-begin":{"post":{"tags":["Lightning"],"summary":"Begin a Lightning invoice payment process","operationId":"payLightningInvoiceBegin","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayLightningInvoiceRequestModel"}}}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}},"schemas":{"PayLightningInvoiceRequestModel":{"type":"object","properties":{"invoice":{"type":"string","description":"Lightning invoice to pay"},"max_fee_sats":{"type":"number","description":"Maximum fee in satoshis you're willing to pay"}},"required":["invoice","max_fee_sats"]}}}} ``` ## POST /lightning/pay-invoice-end > Complete a Lightning invoice payment using signed PSBT ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/pay-invoice-end":{"post":{"tags":["Lightning"],"summary":"Complete a Lightning invoice payment using signed PSBT","operationId":"payLightningInvoiceEnd","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LightningSendRequest"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAssetEndRequestModel"}}}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"LightningSendRequest":{"type":"object","properties":{"id":{"type":"string","description":"Send request ID"},"status":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"],"description":"Payment status"},"payment_type":{"type":"string","enum":["BTC","ASSET"],"description":"Payment type"},"amount_sats":{"type":"number","description":"Amount in satoshis"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset payments)"},"fee_sats":{"type":"number","description":"Fee paid in satoshis"},"created_at":{"type":"string","description":"Creation timestamp"}},"required":["id","status","payment_type","created_at"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]},"SendAssetEndRequestModel":{"type":"object","properties":{"signed_psbt":{"type":"string","description":"Signed PSBT in base64"}},"required":["signed_psbt"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## POST /lightning/fee-estimate > Estimate the routing fee required to pay a Lightning invoice ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/fee-estimate":{"post":{"tags":["Lightning"],"summary":"Estimate the routing fee required to pay a Lightning invoice","operationId":"getLightningSendFeeEstimate","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"number"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetLightningSendFeeEstimateRequestModel"}}}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}},"schemas":{"GetLightningSendFeeEstimateRequestModel":{"type":"object","properties":{"invoice":{"type":"string","description":"Lightning invoice to pay"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Optional asset details for asset payment estimation"}},"required":["invoice"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## GET /lightning/listpayments > List Lightning payments ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/listpayments":{"get":{"tags":["Lightning"],"summary":"List Lightning payments","operationId":"listLightningPayments","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLightningPaymentsResponse"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"ListLightningPaymentsResponse":{"type":"object","properties":{"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"},"description":"Array of Lightning payments"}},"required":["payments"]},"Payment":{"type":"object","properties":{"amt_msat":{"type":"number","description":"Amount in millisatoshis"},"asset_amount":{"type":"number","description":"Asset amount (for asset payments)"},"asset_id":{"type":"string","description":"Asset ID (for asset payments)"},"payment_hash":{"type":"string","description":"Payment hash"},"inbound":{"type":"boolean","description":"Whether the payment is inbound"},"status":{"type":"string","enum":["Pending","Succeeded","Failed"],"description":"HTLC status"},"created_at":{"type":"number","description":"Creation timestamp"},"updated_at":{"type":"number","description":"Last update timestamp"},"payee_pubkey":{"type":"string","description":"Payee public key"}},"required":["amt_msat","payment_hash","inbound","status","created_at","updated_at"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## GET /lightning/send-request/{request\_id} > Get the status of a Lightning payment by request ID ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/send-request/{request_id}":{"get":{"tags":["Lightning"],"summary":"Get the status of a Lightning payment by request ID","operationId":"getLightningSendRequest","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"},{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The request_id parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LightningSendRequest"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"LightningSendRequest":{"type":"object","properties":{"id":{"type":"string","description":"Send request ID"},"status":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"],"description":"Payment status"},"payment_type":{"type":"string","enum":["BTC","ASSET"],"description":"Payment type"},"amount_sats":{"type":"number","description":"Amount in satoshis"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset payments)"},"fee_sats":{"type":"number","description":"Fee paid in satoshis"},"created_at":{"type":"string","description":"Creation timestamp"}},"required":["id","status","payment_type","created_at"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## GET /lightning/onchain-receive > Get an on-chain receive address for receiving assets ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/onchain-receive":{"get":{"tags":["Lightning"],"summary":"Get an on-chain receive address for receiving assets","operationId":"onchainReceive","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleUseDepositAddressResponse"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"SingleUseDepositAddressResponse":{"type":"object","properties":{"btc_address":{"type":"string","description":"Bitcoin address for deposit"},"asset_invoice":{"type":"string","description":"RGB asset invoice string"},"expires_at":{"type":"string","description":"Optional expiration timestamp"}},"required":["btc_address","asset_invoice"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## GET /lightning/balance > Get wallet balance including BTC and asset balances ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/balance":{"get":{"tags":["Lightning"],"summary":"Get wallet balance including BTC and asset balances","operationId":"getBalance","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletBalanceResponse"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"WalletBalanceResponse":{"type":"object","properties":{"balance":{"$ref":"#/components/schemas/BtcBalanceResponse"},"asset_balances":{"type":"array","items":{"$ref":"#/components/schemas/AssetBalance"}}},"required":["balance","asset_balances"]},"BtcBalanceResponse":{"type":"object","properties":{"vanilla":{"$ref":"#/components/schemas/Balance"},"colored":{"$ref":"#/components/schemas/Balance"},"offchain_balance":{"$ref":"#/components/schemas/OffchainBalance"}},"required":["vanilla","colored"]},"Balance":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"}},"required":["settled","future","spendable"]},"OffchainBalance":{"type":"object","properties":{"total":{"type":"number","description":"Total offchain balance"},"details":{"type":"array","items":{"$ref":"#/components/schemas/OffchainBalanceDetail"}}},"required":["total","details"]},"OffchainBalanceDetail":{"type":"object","properties":{"expiry_time":{"type":"string","description":"Expiry time"},"amount":{"type":"number","description":"Amount"}},"required":["expiry_time","amount"]},"AssetBalance":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"ticker":{"type":"string","description":"Asset ticker symbol"},"precision":{"type":"number","description":"Asset precision"},"balance":{"$ref":"#/components/schemas/AssetBalanceDetails"}},"required":["asset_id","precision","balance"]},"AssetBalanceDetails":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"},"offchain_outbound":{"type":"number","description":"Offchain outbound balance"}},"required":["settled","future","spendable"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## POST /lightning/settle > Settle balances in the wallet ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/settle":{"post":{"tags":["Lightning"],"summary":"Settle balances in the wallet","operationId":"settle","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettleResponse"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"SettleResponse":{"type":"object","additionalProperties":true,"description":"Settlement result object"}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## POST /lightning/onchain-send-begin > Begin an on-chain send process from UTEXO ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/onchain-send-begin":{"post":{"tags":["Lightning"],"summary":"Begin an on-chain send process from UTEXO","operationId":"onchainSendBegin","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnchainSendRequestModel"}}}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}},"schemas":{"OnchainSendRequestModel":{"type":"object","properties":{"address_or_rgbinvoice":{"type":"string","description":"Bitcoin on-chain address or RGB invoice string"},"amount_sats":{"type":"number","description":"Amount in satoshis to send (optional)"},"fee_rate":{"type":"number","description":"Fee rate used to build the Bitcoin transaction"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Optional asset to send (required for asset send)"}},"required":["address_or_rgbinvoice","fee_rate"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## POST /lightning/onchain-send-end > Complete an on-chain send from UTEXO using signed PSBT ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/onchain-send-end":{"post":{"tags":["Lightning"],"summary":"Complete an on-chain send from UTEXO using signed PSBT","operationId":"onchainSendEnd","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnchainSendResponse"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAssetEndRequestModel"}}}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"OnchainSendResponse":{"type":"object","properties":{"send_id":{"type":"string","description":"Unique on-chain send identifier"},"txid":{"type":"string","description":"Bitcoin transaction id (if available)"}},"required":["send_id"]},"SendAssetEndRequestModel":{"type":"object","properties":{"signed_psbt":{"type":"string","description":"Signed PSBT in base64"}},"required":["signed_psbt"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## GET /onchain-send/{send\_id} > Get the status of an on-chain send by send ID ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Deposit & UTEXO","description":"Deposit and UTEXO management operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/onchain-send/{send_id}":{"get":{"tags":["Deposit & UTEXO"],"summary":"Get the status of an on-chain send by send ID","operationId":"getOnchainSendStatus","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"},{"name":"send_id","in":"path","required":true,"schema":{"type":"string"},"description":"The send_id parameter"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetOnchainSendResponse"}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"GetOnchainSendResponse":{"type":"object","properties":{"send_id":{"type":"string","description":"On-chain send identifier"},"status":{"type":"string","description":"Current on-chain send status"},"address_or_rgbinvoice":{"type":"string","description":"Bitcoin address or RGB invoice used for on-chain send"},"amount_sats_requested":{"type":"number","description":"Amount in satoshis that was requested"},"amount_sats_sent":{"type":"number","description":"Amount in satoshis that was actually sent"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset sends)"},"close_txids":{"type":"array","items":{"type":"string"},"description":"Array of close transaction IDs"},"sweep_txid":{"type":"string","description":"Sweep transaction ID if available"},"fee_sats":{"type":"number","description":"Fee paid in satoshis"},"timestamps":{"type":"object","additionalProperties":{"type":"number"},"description":"Timestamps for various on-chain send events"},"error_code":{"type":"string","description":"Error code if on-chain send failed"},"error_message":{"type":"string","description":"Error message if on-chain send failed"},"retryable":{"type":"boolean","description":"Whether the on-chain send can be retried"}},"required":["send_id","status","address_or_rgbinvoice","close_txids","timestamps","retryable"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## POST /lightning/listtransfers > List on-chain transfers for a specific asset ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"tags":[{"name":"Lightning","description":"Lightning Network operations"}],"servers":[{"url":"https://rgb-node.thunderstack.org","description":"Mainnet RGB Node"},{"url":"https://rgb-node.test.thunderstack.org","description":"Testnet RGB Node"},{"url":"http://127.0.0.1:8000","description":"Local RGB Node (development)"}],"paths":{"/lightning/listtransfers":{"post":{"tags":["Lightning"],"summary":"List on-chain transfers for a specific asset","operationId":"listOnchainTransfers","parameters":[{"$ref":"#/components/parameters/XpubVan"},{"$ref":"#/components/parameters/XpubCol"},{"$ref":"#/components/parameters/MasterFingerprint"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RgbTransfer"}}}}},"400":{"$ref":"#/components/responses/RgbLibError"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListLightningTransfersRequest"}}}}}}},"components":{"parameters":{"XpubVan":{"name":"xpub-van","in":"header","required":true,"schema":{"type":"string"},"description":"Vanilla extended public key"},"XpubCol":{"name":"xpub-col","in":"header","required":true,"schema":{"type":"string"},"description":"Colored extended public key"},"MasterFingerprint":{"name":"master-fingerprint","in":"header","required":true,"schema":{"type":"string"},"description":"Master fingerprint"}},"schemas":{"RgbTransfer":{"type":"object","properties":{"idx":{"type":"number"},"batch_transfer_idx":{"type":"number"},"created_at":{"type":"number"},"updated_at":{"type":"number"},"status":{"type":"number","enum":[0,1,2,3],"description":"0=WAITING_COUNTERPARTY, 1=WAITING_CONFIRMATIONS, 2=SETTLED, 3=FAILED"},"amount":{"type":"number"},"kind":{"type":"number","enum":[0,1,2,3,4],"description":"Transfer kind: 0=ISSUANCE, 1=RECEIVE_BLIND, 2=RECEIVE_WITNESS, 3=SEND, 4=INFLATION"},"txid":{"type":"string","nullable":true},"recipient_id":{"type":"string"},"receive_utxo":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"}},"required":["txid","vout"]},"change_utxo":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"}},"nullable":true},"expiration":{"type":"number"},"transport_endpoints":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"transport_type":{"type":"number"},"used":{"type":"boolean"}},"required":["endpoint","transport_type","used"]}}},"required":["idx","batch_transfer_idx","created_at","updated_at","status","amount","kind","recipient_id","receive_utxo","expiration","transport_endpoints"]},"ListLightningTransfersRequest":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset ID to list transfers for"}},"required":["asset_id"]}},"responses":{"RgbLibError":{"description":"RGB library error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Detailed error message"},"status":{"type":"number","description":"HTTP status code"}},"required":["error","message","status"]}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["error","message"]}}}}}}} ``` ## The SingleUseDepositAddressResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"SingleUseDepositAddressResponse":{"type":"object","properties":{"btc_address":{"type":"string","description":"Bitcoin address for deposit"},"asset_invoice":{"type":"string","description":"RGB asset invoice string"},"expires_at":{"type":"string","description":"Optional expiration timestamp"}},"required":["btc_address","asset_invoice"]}}}} ``` ## The UnusedDepositAddressesResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"UnusedDepositAddressesResponse":{"type":"object","properties":{"addresses":{"type":"array","items":{"$ref":"#/components/schemas/SingleUseDepositAddressResponse"},"description":"Array of unused deposit addresses"}},"required":["addresses"]},"SingleUseDepositAddressResponse":{"type":"object","properties":{"btc_address":{"type":"string","description":"Bitcoin address for deposit"},"asset_invoice":{"type":"string","description":"RGB asset invoice string"},"expires_at":{"type":"string","description":"Optional expiration timestamp"}},"required":["btc_address","asset_invoice"]}}}} ``` ## The WalletBalanceResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"WalletBalanceResponse":{"type":"object","properties":{"balance":{"$ref":"#/components/schemas/BtcBalanceResponse"},"asset_balances":{"type":"array","items":{"$ref":"#/components/schemas/AssetBalance"}}},"required":["balance","asset_balances"]},"BtcBalanceResponse":{"type":"object","properties":{"vanilla":{"$ref":"#/components/schemas/Balance"},"colored":{"$ref":"#/components/schemas/Balance"},"offchain_balance":{"$ref":"#/components/schemas/OffchainBalance"}},"required":["vanilla","colored"]},"Balance":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"}},"required":["settled","future","spendable"]},"OffchainBalance":{"type":"object","properties":{"total":{"type":"number","description":"Total offchain balance"},"details":{"type":"array","items":{"$ref":"#/components/schemas/OffchainBalanceDetail"}}},"required":["total","details"]},"OffchainBalanceDetail":{"type":"object","properties":{"expiry_time":{"type":"string","description":"Expiry time"},"amount":{"type":"number","description":"Amount"}},"required":["expiry_time","amount"]},"AssetBalance":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"ticker":{"type":"string","description":"Asset ticker symbol"},"precision":{"type":"number","description":"Asset precision"},"balance":{"$ref":"#/components/schemas/AssetBalanceDetails"}},"required":["asset_id","precision","balance"]},"AssetBalanceDetails":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"},"offchain_outbound":{"type":"number","description":"Offchain outbound balance"}},"required":["settled","future","spendable"]}}}} ``` ## The BtcBalanceResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"BtcBalanceResponse":{"type":"object","properties":{"vanilla":{"$ref":"#/components/schemas/Balance"},"colored":{"$ref":"#/components/schemas/Balance"},"offchain_balance":{"$ref":"#/components/schemas/OffchainBalance"}},"required":["vanilla","colored"]},"Balance":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"}},"required":["settled","future","spendable"]},"OffchainBalance":{"type":"object","properties":{"total":{"type":"number","description":"Total offchain balance"},"details":{"type":"array","items":{"$ref":"#/components/schemas/OffchainBalanceDetail"}}},"required":["total","details"]},"OffchainBalanceDetail":{"type":"object","properties":{"expiry_time":{"type":"string","description":"Expiry time"},"amount":{"type":"number","description":"Amount"}},"required":["expiry_time","amount"]}}}} ``` ## The Balance object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"Balance":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"}},"required":["settled","future","spendable"]}}}} ``` ## The OffchainBalance object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"OffchainBalance":{"type":"object","properties":{"total":{"type":"number","description":"Total offchain balance"},"details":{"type":"array","items":{"$ref":"#/components/schemas/OffchainBalanceDetail"}}},"required":["total","details"]},"OffchainBalanceDetail":{"type":"object","properties":{"expiry_time":{"type":"string","description":"Expiry time"},"amount":{"type":"number","description":"Amount"}},"required":["expiry_time","amount"]}}}} ``` ## The OffchainBalanceDetail object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"OffchainBalanceDetail":{"type":"object","properties":{"expiry_time":{"type":"string","description":"Expiry time"},"amount":{"type":"number","description":"Amount"}},"required":["expiry_time","amount"]}}}} ``` ## The AssetBalance object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"AssetBalance":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"ticker":{"type":"string","description":"Asset ticker symbol"},"precision":{"type":"number","description":"Asset precision"},"balance":{"$ref":"#/components/schemas/AssetBalanceDetails"}},"required":["asset_id","precision","balance"]},"AssetBalanceDetails":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"},"offchain_outbound":{"type":"number","description":"Offchain outbound balance"}},"required":["settled","future","spendable"]}}}} ``` ## The AssetBalanceDetails object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"AssetBalanceDetails":{"type":"object","properties":{"settled":{"type":"number","description":"Settled balance"},"future":{"type":"number","description":"Future balance"},"spendable":{"type":"number","description":"Spendable balance"},"offchain_outbound":{"type":"number","description":"Offchain outbound balance"}},"required":["settled","future","spendable"]}}}} ``` ## The SettleResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"SettleResponse":{"type":"object","additionalProperties":true,"description":"Settlement result object"}}}} ``` ## The LightningAsset object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## The CreateLightningInvoiceRequestModel object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"CreateLightningInvoiceRequestModel":{"type":"object","properties":{"amount_sats":{"type":"number","description":"Amount in satoshis for BTC invoice"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details for asset invoice"},"expiry_seconds":{"type":"number","description":"Optional invoice expiration time in seconds"}}},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## The LightningReceiveRequest object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"LightningReceiveRequest":{"type":"object","properties":{"id":{"type":"string","description":"Invoice request ID"},"invoice":{"type":"string","description":"Lightning invoice string"},"status":{"type":"string","enum":["OPEN","SETTLED","EXPIRED","FAILED"],"description":"Invoice status"},"payment_type":{"type":"string","enum":["BTC","ASSET"],"description":"Payment type"},"amount_sats":{"type":"number","description":"Amount in satoshis (for BTC invoices)"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset invoices)"},"created_at":{"type":"string","description":"Creation timestamp"}},"required":["id","invoice","status","payment_type","created_at"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## The LightningSendRequest object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"LightningSendRequest":{"type":"object","properties":{"id":{"type":"string","description":"Send request ID"},"status":{"type":"string","enum":["PENDING","SUCCEEDED","FAILED"],"description":"Payment status"},"payment_type":{"type":"string","enum":["BTC","ASSET"],"description":"Payment type"},"amount_sats":{"type":"number","description":"Amount in satoshis"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset payments)"},"fee_sats":{"type":"number","description":"Fee paid in satoshis"},"created_at":{"type":"string","description":"Creation timestamp"}},"required":["id","status","payment_type","created_at"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## The GetLightningSendFeeEstimateRequestModel object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"GetLightningSendFeeEstimateRequestModel":{"type":"object","properties":{"invoice":{"type":"string","description":"Lightning invoice to pay"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Optional asset details for asset payment estimation"}},"required":["invoice"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## The PayLightningInvoiceRequestModel object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"PayLightningInvoiceRequestModel":{"type":"object","properties":{"invoice":{"type":"string","description":"Lightning invoice to pay"},"max_fee_sats":{"type":"number","description":"Maximum fee in satoshis you're willing to pay"}},"required":["invoice","max_fee_sats"]}}}} ``` ## The SendAssetEndRequestModel object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"SendAssetEndRequestModel":{"type":"object","properties":{"signed_psbt":{"type":"string","description":"Signed PSBT in base64"}},"required":["signed_psbt"]}}}} ``` ## The OnchainSendRequestModel object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"OnchainSendRequestModel":{"type":"object","properties":{"address_or_rgbinvoice":{"type":"string","description":"Bitcoin on-chain address or RGB invoice string"},"amount_sats":{"type":"number","description":"Amount in satoshis to send (optional)"},"fee_rate":{"type":"number","description":"Fee rate used to build the Bitcoin transaction"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Optional asset to send (required for asset send)"}},"required":["address_or_rgbinvoice","fee_rate"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` ## The OnchainSendResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"OnchainSendResponse":{"type":"object","properties":{"send_id":{"type":"string","description":"Unique on-chain send identifier"},"txid":{"type":"string","description":"Bitcoin transaction id (if available)"}},"required":["send_id"]}}}} ``` ## The ListLightningTransfersRequest object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"ListLightningTransfersRequest":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset ID to list transfers for"}},"required":["asset_id"]}}}} ``` ## The RgbTransfer object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"RgbTransfer":{"type":"object","properties":{"idx":{"type":"number"},"batch_transfer_idx":{"type":"number"},"created_at":{"type":"number"},"updated_at":{"type":"number"},"status":{"type":"number","enum":[0,1,2,3],"description":"0=WAITING_COUNTERPARTY, 1=WAITING_CONFIRMATIONS, 2=SETTLED, 3=FAILED"},"amount":{"type":"number"},"kind":{"type":"number","enum":[0,1,2,3,4],"description":"Transfer kind: 0=ISSUANCE, 1=RECEIVE_BLIND, 2=RECEIVE_WITNESS, 3=SEND, 4=INFLATION"},"txid":{"type":"string","nullable":true},"recipient_id":{"type":"string"},"receive_utxo":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"}},"required":["txid","vout"]},"change_utxo":{"type":"object","properties":{"txid":{"type":"string"},"vout":{"type":"number"}},"nullable":true},"expiration":{"type":"number"},"transport_endpoints":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"transport_type":{"type":"number"},"used":{"type":"boolean"}},"required":["endpoint","transport_type","used"]}}},"required":["idx","batch_transfer_idx","created_at","updated_at","status","amount","kind","recipient_id","receive_utxo","expiration","transport_endpoints"]}}}} ``` ## The Transaction object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"Transaction":{"type":"object","properties":{"transaction_type":{"type":"number","enum":[0,1,2,3],"description":"0=RGB_SEND, 1=DRAIN, 2=CREATE_UTXOS, 3=USER"},"txid":{"type":"string"},"received":{"type":"number"},"sent":{"type":"number"},"fee":{"type":"number"},"confirmation_time":{"type":"object","properties":{"height":{"type":"number"},"timestamp":{"type":"number"}}}},"required":["transaction_type","txid","received","sent","fee"]}}}} ``` ## The ListLightningPaymentsResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"ListLightningPaymentsResponse":{"type":"object","properties":{"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"},"description":"Array of Lightning payments"}},"required":["payments"]},"Payment":{"type":"object","properties":{"amt_msat":{"type":"number","description":"Amount in millisatoshis"},"asset_amount":{"type":"number","description":"Asset amount (for asset payments)"},"asset_id":{"type":"string","description":"Asset ID (for asset payments)"},"payment_hash":{"type":"string","description":"Payment hash"},"inbound":{"type":"boolean","description":"Whether the payment is inbound"},"status":{"type":"string","enum":["Pending","Succeeded","Failed"],"description":"HTLC status"},"created_at":{"type":"number","description":"Creation timestamp"},"updated_at":{"type":"number","description":"Last update timestamp"},"payee_pubkey":{"type":"string","description":"Payee public key"}},"required":["amt_msat","payment_hash","inbound","status","created_at","updated_at"]}}}} ``` ## The Payment object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"Payment":{"type":"object","properties":{"amt_msat":{"type":"number","description":"Amount in millisatoshis"},"asset_amount":{"type":"number","description":"Asset amount (for asset payments)"},"asset_id":{"type":"string","description":"Asset ID (for asset payments)"},"payment_hash":{"type":"string","description":"Payment hash"},"inbound":{"type":"boolean","description":"Whether the payment is inbound"},"status":{"type":"string","enum":["Pending","Succeeded","Failed"],"description":"HTLC status"},"created_at":{"type":"number","description":"Creation timestamp"},"updated_at":{"type":"number","description":"Last update timestamp"},"payee_pubkey":{"type":"string","description":"Payee public key"}},"required":["amt_msat","payment_hash","inbound","status","created_at","updated_at"]}}}} ``` ## The GetOnchainSendResponse object ```json {"openapi":"3.0.3","info":{"title":"RGB Node API - New Features","version":"1.2.8"},"components":{"schemas":{"GetOnchainSendResponse":{"type":"object","properties":{"send_id":{"type":"string","description":"On-chain send identifier"},"status":{"type":"string","description":"Current on-chain send status"},"address_or_rgbinvoice":{"type":"string","description":"Bitcoin address or RGB invoice used for on-chain send"},"amount_sats_requested":{"type":"number","description":"Amount in satoshis that was requested"},"amount_sats_sent":{"type":"number","description":"Amount in satoshis that was actually sent"},"asset":{"$ref":"#/components/schemas/LightningAsset","description":"Asset details (for asset sends)"},"close_txids":{"type":"array","items":{"type":"string"},"description":"Array of close transaction IDs"},"sweep_txid":{"type":"string","description":"Sweep transaction ID if available"},"fee_sats":{"type":"number","description":"Fee paid in satoshis"},"timestamps":{"type":"object","additionalProperties":{"type":"number"},"description":"Timestamps for various on-chain send events"},"error_code":{"type":"string","description":"Error code if on-chain send failed"},"error_message":{"type":"string","description":"Error message if on-chain send failed"},"retryable":{"type":"boolean","description":"Whether the on-chain send can be retried"}},"required":["send_id","status","address_or_rgbinvoice","close_txids","timestamps","retryable"]},"LightningAsset":{"type":"object","properties":{"asset_id":{"type":"string","description":"Asset identifier"},"amount":{"type":"number","description":"Amount in asset units"}},"required":["asset_id","amount"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.thunderstack.org/bitcoin-native-infrastructure/readme/thunderlink/rgb-node/lightning-api-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.