Payments

This page covers BTC Lightning payments (pay ...) and shared payment inspection tools (pay wait/get/ls/...).

For RGB payments over Lightning, see ./rgb (and the end-to-end walkthrough in ./transfers).

Bolt11: receive (create invoice)

On the receiver:

rgbldk --output json --pretty pay invoice create --desc "demo" --amount-msat 10000

Copy the invoice value.

Bolt11: decode an invoice

If someone sends you an invoice string and you want to see what it means:

rgbldk pay invoice decode '<INVOICE>'

For example, the decoded output includes destination, payment_hash, and amount_msat.

Bolt11: send (pay invoice)

On the sender:

rgbldk --output json --pretty pay invoice pay --invoice '<INVOICE>'

Copy the payment_id value.

pay invoice pay is the recommended interactive command: it waits for completion and returns a preimage on success.

Bolt11: send (non-blocking)

If you want to start a payment without waiting:

rgbldk --output json --pretty pay invoice send '<INVOICE>'

Copy the payment_id, then check progress with rgbldk pay wait ... / rgbldk pay get ....

Bolt11: send variable-amount invoices (explicit amount)

If the invoice is variable-amount, you must specify the amount:

rgbldk --output json --pretty pay invoice send-using-amount --invoice '<INVOICE>' --amount-msat 11000

Copy the payment_id.

Hold invoices (advanced): create-for-hash / claim-for-hash / fail-for-hash

A “hold invoice” lets the receiver decide later whether to claim or fail the incoming payment.

This is an advanced workflow; you usually only need it when integrating with another system that already manages a payment_hash and preimage.

Create a hold invoice (receiver)

rgbldk --output json --pretty pay invoice create-for-hash \
  --desc "hold-demo" \
  --amount-msat 10000 \
  --payment-hash <PAYMENT_HASH_HEX>

Copy the invoice value and send it to the payer.

Fail a hold payment (receiver)

rgbldk --output json --pretty pay invoice fail-for-hash <PAYMENT_HASH_HEX>

Claim a hold payment (receiver)

To claim, you must provide the matching preimage and the claimable amount:

rgbldk --output json --pretty pay invoice claim-for-hash \
  --payment-hash <PAYMENT_HASH_HEX> \
  --preimage <PREIMAGE_HEX> \
  --claimable-amount-msat 10000

Wait for a payment to finish

rgbldk pay wait <PAYMENT_ID> --timeout-secs 60

If it times out, the payment might still complete later. Re-run pay wait or check with pay get.

Inspect a payment

rgbldk pay get <PAYMENT_ID>

Long fields (like invoices) may be truncated in tables. Use --no-truncate if you need the full value.

List payments

rgbldk pay ls

Keysend (spontaneous payment)

Keysend sends directly to a destination node_id without an invoice. It typically requires a route (channels).

Send a small keysend payment:

rgbldk --output json --pretty pay keysend send --node-id <NODE_ID> --amount-msat 10000

Run rgbldk pay keysend --help to see additional options (for example custom TLVs).

Abandon a payment

If a payment is stuck and you want to stop tracking it:

rgbldk pay abandon <PAYMENT_ID>