# 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"]}}}}
```